9.8 KiB
| id | title |
|---|---|
| dlc | Executing A DLC with Bitcoin-S |
Executing A Discreet Log Contract (DLC)
Step 1: Get Bitcoin-S Setup
See the setup document.
Make sure to follow Step 4 to checkout the dlc feature branch.
Step 2: Agree On Contract Terms
Both parties must agree on all fields from the table below:
| Field Name | Format |
|---|---|
| oracleInfo | OraclePubKeyHex ++ OracleRValueHex |
| contractInfo | Hash1Hex ++ 8ByteValue1Hex ++ Hash2Hex ++ 8ByteValue2Hex |
| collateral | NumInSatoshis |
| locktime | LockTimeNum |
| refundlocktime | LockTimeNum |
| feerate | NumInSatoshisPerVByte |
Here is an example oracleInfo for public key 02debeef17d7be7ced0bf346395a5c5c7177491953e91f0af2b098aac5d23cab and R value b1a63752e5a760f47252545b7cda933afeaf06dba3b6c6fd5356781f240c2750:
02debeef17d7be7ced0bf346395a5c5c7177491953e91f0af2b098aac5d23cabb1a63752e5a760f47252545b7cda933afeaf06dba3b6c6fd5356781f240c2750
Here is an example contractInfo for hashes c07803e32c12e100905e8d69fe38ae72f2e7a17eb7b8dc1a9bce134b0cbe920f and 5c58e41254e7a117ee1db59874f2334facc1576c238c16d18767b47861f93f7c with respective Satoshi denominated outcomes of 100000 sats and 0 sats:
c07803e32c12e100905e8d69fe38ae72f2e7a17eb7b8dc1a9bce134b0cbe920fa0860100000000005c58e41254e7a117ee1db59874f2334facc1576c238c16d18767b47861f93f7c0000000000000000
And finally, here are the oracle signatures for each hash in order in case you want to test with this contract:
f8758d7f03a65b67b90f62301a3554849bde6d00d50e965eb123398de9fd6ea7fbbee821b7166028a6927282830c9452cfcf3c5716c57e43dd4069ca87625010
f8758d7f03a65b67b90f62301a3554849bde6d00d50e965eb123398de9fd6ea7af05f01f1ca852cf5454a7dc91cdad7903dc2e67ddb2b3bc9d61dabd8856aa6a
Note: if you wish to setup your own oracle for testing, you can do so by pasting the following into the sbt core/console:
import org.bitcoins.crypto._
import org.bitcoins.core.currency._
import scodec.bits._
val privKey = ECPrivateKey.freshPrivateKey
val pubKey = privKey.schnorrPublicKey
val kValue = ECPrivateKey.freshPrivateKey
val rValue = kValue.schnorrNonce
//the hash the oracle will sign when the bitcoin price is over $9,000
val winHash = CryptoUtil.sha256(ByteVector("BTC_OVER_9000".getBytes)).flip
//the hash the oracle with sign when the bitcoin price is under $9,000
val loseHash = CryptoUtil.sha256(ByteVector("BTC_UNDER_9000".getBytes)).flip
//the amounts received in the case the oracle signs hash of message "BTC_OVER_9000"
val amtReceivedOnWin = Satoshis(100000)
//the amount received in the case the oracle signs hash of message "BTC_UNDER_9000"
val amtReceivedOnLoss = Satoshis.zero
(pubKey.bytes ++ rValue.bytes).toHex
(winHash.bytes ++ amtReceivedOnWin.bytes ++ loseHash.bytes ++ amtReceivedOnLoss.bytes).toHex
privKey.schnorrSignWithNonce(winHash.bytes, kValue)
privKey.schnorrSignWithNonce(loseHash.bytes, kValue)
Where you can replace the messages WIN and LOSE to have the oracle sign any two messages, and replace Satoshis(100000) and Satoshis.zero to change the outcomes.
Using the GUI
To first start up the GUI you first need to start your bitcoin-s server, after doing so you can run the gui by doing:
sbt gui/run
Step 3: Setup The DLC
If you're a visual learner there is a video demo that explains this process in detail.
Creating The Offer
Once the terms are agreed to, either party can use the Offer button and enter each of the fields from the table above.
Accepting The Offer
Upon receiving a DLC Offer from your counter-party, you can use the Accept button and paste in the DLC Offer.
Signing The DLC
Upon receiving a DLC Accept message from your counter-party, you can use the Sign button and paste in the DLC Accept.
Adding DLC Signatures To Your Database
Upon receiving a DLC Sign message from your counter-party, add their signatures to your database using the Add Sigs button and paste in the message.
After doing so you can get the fully signed funding transaction using the Get Funding Tx button. This will return the fully signed serialized transaction.
Step 4: Executing the DLC
Mutual Close
Upon receiving an oracle signature, either party can initiate a mutual close with the Init Close button.
This will take in the event id of the DLC plus the oracle signature.
Afterwards, it should give you a JSON output that can be sent to your counter party.
And if you receive one of these CloseSig messages from your counter-party, you can generate the fully-signed mutual closing transaction with the AcceptClose button and simply pasting in their message.
Unilateral Close
If your counter-party is unresponsive upon receiving a mutual close message, or is unreachable, you can execute the DLC unilaterally with the Force Close button.
This will return two fully-signed transactions in the case that you are owed any funds, and one fully-signed transaction in the case that you aren't. The first transaction returned should be the fully signed Contract Execution Transaction, and the second transaction, if existing, should be the fully-signed sweep transaction which claims your funds on the CET.
Claiming Penalty Funds
If your counter-party has broadcasted a CET to the network, and does not sweep their ToLocal funds in 5 blocks, you can claim the funds on the ToLocalOutput using the Punish button.
Refund
If the refundlocktime for the DLC has been reached, you can get the fully-signed refund transaction with the Refund button.
Using the CLI
Step 3: Setup The DLC
Creating The Offer
Once these terms are agreed to, either party can call on createdlcoffer with flags for each of the fields in the table above. For example:
./app/cli/target/graalvm-native-image/bitcoin-s-cli createdlcoffer --oracleInfo 02debeef17d7be7ced0bf346395a5c5c7177491953e91f0af2b098aac5d23cabb1a63752e5a760f47252545b7cda933afeaf06dba3b6c6fd5356781f240c2750 --contractInfo c07803e32c12e100905e8d69fe38ae72f2e7a17eb7b8dc1a9bce134b0cbe920fa0860100000000005c58e41254e7a117ee1db59874f2334facc1576c238c16d18767b47861f93f7c0000000000000000 --collateral 40000 --locktime 1666720 --refundlocktime 1666730 --feerate 3
This will return a nice pretty-printed JSON offer. To get an offer that can be sent to the counter-party, add the --escaped flag to the end of this command.
Accepting The Offer
Upon receiving a DLC Offer from your counter-party, the following command will create the serialized accept message:
./app/cli/target/graalvm-native-image/bitcoin-s-cli acceptdlcoffer --offer [offer] --escaped
Signing The DLC
Upon receiving a DLC Accept message from your counter-party, the following command will generate all of your signatures for this DLC:
./app/cli/target/graalvm-native-image/bitcoin-s-cli signdlc --accept [accept] --escaped
Adding DLC Signatures To Your Database
Upon receiving a DLC Sign message from your counter-party, add their signatures to your database by:
./app/cli/target/graalvm-native-image/bitcoin-s-cli adddlcsigs --sigs [sign]
You are now fully setup and can generate the fully signed funding transaction for broadcast using
./app/cli/target/graalvm-native-image/bitcoin-s-cli getdlcfundingtx --eventid [eventid]
where the eventid is in all but the messages other than the DLC Offer message, and is also returned by the adddlcsigs command.
Step 4: Executing the DLC
Mutual Close
Upon receiving an oracle signature, either party can initiate a mutual close with
./app/cli/target/graalvm-native-image/bitcoin-s-cli initdlcmutualclose --eventid [eventid] --oraclesig [sig] --escaped
And if you receive one of these CloseSig messages from your counter-party, you can generate the fully-signed mutual closing transaction with
./app/cli/target/graalvm-native-image/bitcoin-s-cli acceptdlcmutualclose --closesig [closesig]
Unilateral Close
If your counter-party is unresponsive upon receiving an initdlcmutualclose message, or is unreachable, you can execute the DLC unilaterally with
./app/cli/target/graalvm-native-image/bitcoin-s-cli executedlcforceclose --eventid [eventid] --oraclesig [sig]
which will return two fully-signed transactions in the case that you are owed any funds, and one fully-signed transaction in the case that you aren't. The first transaction returned should be the fully signed Contract Execution Transaction, and the second transaction, if existing, should be the fully-signed sweep transaction which claims your funds on the CET.
Claiming Remote Funds When Counter-Party Unilaterally Closes
If your counter-party has broadcasted a CET to the network, you can claim the funds on the ToRemoteOutput using
./app/cli/target/graalvm-native-image/bitcoin-s-cli claimdlcremotefunds --eventid [eventid] --forceclosetx [cet]
Claiming Penalty Funds
If your counter-party has broadcasted a CET to the network, and does not sweep their ToLocal funds in 5 blocks, you can claim the funds on the ToLocalOutput using
./app/cli/target/graalvm-native-image/bitcoin-s-cli claimdlcpenaltyfunds --eventid [eventid] --forceclosetx [cet]
Refund
If the refundlocktime for the DLC has been reached, you can get the fully-signed refund transaction with
./app/cli/target/graalvm-native-image/bitcoin-s-cli executedlcrefund --eventid [eventid]