mirror of
https://github.com/bitcoin-s/bitcoin-s.git
synced 2025-02-25 07:17:32 +01:00
321 lines
13 KiB
Markdown
321 lines
13 KiB
Markdown
---
|
|
id: dlc
|
|
title: Executing A DLC with Bitcoin-S
|
|
---
|
|
|
|
## Executing A Discreet Log Contract (DLC)
|
|
|
|
## Step 1: Get Bitcoin-S Setup
|
|
|
|
See the [setup document](../getting-setup.md).
|
|
|
|
### Using the GUI
|
|
|
|
To first start up the GUI you first need to start your bitcoin-s server and gui with
|
|
|
|
```bashrc
|
|
sbt bundle/run
|
|
```
|
|
|
|
or if your bitcoin-s server is already running, you can run the standalone gui with
|
|
|
|
```bashrc
|
|
sbt gui/run
|
|
```
|
|
|
|
or by following the instructions for building and running the GUI [here](../getting-setup.md#step-5-setting-up-a-bitcoin-s-server)
|
|
|
|
## Step 2: Agree On Contract Terms
|
|
|
|
Both parties must agree on all fields from the table below:
|
|
|
|
| Field Name | Description |
|
|
| :------------: | :------------------------------------------------------: |
|
|
| contractInfo | Information about payouts and which oracles to use |
|
|
| collateral | Number of sats the initiator is putting up |
|
|
| locktime | Locktime of the CETs |
|
|
| refundlocktime | Locktime of the Refund Transaction |
|
|
| feerate | Fee rate in sats/vbyte |
|
|
|
|
> Note: if you wish to set up your own oracle for testing, you can do so by checking out our [oracle rpc server](../oracle/oracle-server.md) or [Krystal Bull](https://github.com/bitcoin-s/krystal-bull)
|
|
|
|
### Decoding DLC Messages
|
|
|
|
With the cli tool you can decode dlc offers, contract infos, oracle announcements, and oracle attestations.
|
|
This can be helpful for when developing on top of bitcoin-s and not having the proper DLC tooling to understand the messages.
|
|
|
|
Examples:
|
|
|
|
Decoding Offer:
|
|
```bash
|
|
bitcoin-s-cli decodeoffer a71a006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000fdd82ee40000000000010f2cfda7101802035965730000000000010f2c024e6f0000000000000000fda712bcfdd824b8d89fe4d84bdf96299d2e3664acda7e14001297f341afcaca91d3909f12988cb308f309625d89c078bf2268b174faf1c082f1f10bef55834af50b91d9a241ffb2b8b005b07acf849ad2cec22107331dedbf5a607654fad4eafe39c278e27dde68fdd822540001ef8bd9f4445543c63923dde8c00f60d649c445a7772ac4693136b2fd234fcc2f60dfa880fdd80609000203596573024e6f20446f657320746865206d656d706f6f6c20636c656172206f6e20372f322f323102279cf17c387d7101b08d90b2aeef46231957d9d3558f5871e62781a68e7d75c9001600148dc81a3097bf28c6020eaf89cefae69c5f31aceb5d655d867008d23e00000000000090880001fda714fd01b3627231e09b7948c3019d02000000000102368af13baeef5a313d3ef12e895b232f1e76212cb76957d7e4b8a664915d15960100000000fdfffffffaec4ef43ae2365d0abc53336188053da4078a5b7489928602bcc8c9a4b75f0d0000000000fdffffff030f0b000000000000160014107eb2463ad25843ed01fd33656c83bdd11db3554a8701000000000022002002265c41f299b3c7f0dda5b9d7bc4135d25c2d8aed286837aa9e0954d70894d606961c000000000016001482a7ecd4624e6856d1b09c27e9f3a82323f49c2d0247304402200911162e99e23e4a26e0219a4bdaaf7a5f790be63a8376516640dcc0860ca4d602203a078371904842e2e6adfbebebcac138db23514b3396851569f5f2bf82c3197a012103cd2d0a4eace5993ebb0a75da85d9070627e64f1a5783cf5217e9bd82d20d1c470247304402200fa8515323410ca2b14b08bf22c618b6ced77b9289cb1dfa7ac10548e2e1b2e002206a407bcafdfb64009182fb5838db9671968abdd902e1194f6883cd0e5413ad36012103d3864eb755690e2b4ff139047419373e36a05630429da76fef5de25eeffb4ffc0000000000000002fffffffd006b000000160014d13be5f330b1ea9bbf61f68002b4465e02c341d9df27e1460161e002825311ec94d1e91b000000000000000a0000000061316580
|
|
{
|
|
"contractFlags": "0",
|
|
"chainHash": "6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000",
|
|
"contractInfo": {
|
|
"totalCollateral": 69420,
|
|
"contractDescriptor": {
|
|
"outcomes": [
|
|
{
|
|
"outcome": "Yes",
|
|
"localPayout": 69420
|
|
},
|
|
{
|
|
"outcome": "No",
|
|
"localPayout": 0
|
|
}
|
|
]
|
|
},
|
|
"oracleInfo": {
|
|
"announcement": {
|
|
"announcementSignature": "d89fe4d84bdf96299d2e3664acda7e14001297f341afcaca91d3909f12988cb308f309625d89c078bf2268b174faf1c082f1f10bef55834af50b91d9a241ffb2",
|
|
"publicKey": "b8b005b07acf849ad2cec22107331dedbf5a607654fad4eafe39c278e27dde68",
|
|
"event": {
|
|
"nonces": [
|
|
"ef8bd9f4445543c63923dde8c00f60d649c445a7772ac4693136b2fd234fcc2f"
|
|
],
|
|
"maturity": "2021-07-03T00:00:00Z",
|
|
"descriptor": {
|
|
"outcomes": [
|
|
"Yes",
|
|
"No"
|
|
]
|
|
},
|
|
"eventId": "Does the mempool clear on 7/2/21"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"fundingPubKey": "02279cf17c387d7101b08d90b2aeef46231957d9d3558f5871e62781a68e7d75c9",
|
|
"payoutSPK": "1600148dc81a3097bf28c6020eaf89cefae69c5f31aceb",
|
|
"payoutSerialId": 6729888050161701888,
|
|
"offerCollateral": 37000,
|
|
"fundingInputs": [
|
|
{
|
|
"inputSerialId": 7093787203812804608,
|
|
"prevTx": "02000000000102368af13baeef5a313d3ef12e895b232f1e76212cb76957d7e4b8a664915d15960100000000fdfffffffaec4ef43ae2365d0abc53336188053da4078a5b7489928602bcc8c9a4b75f0d0000000000fdffffff030f0b000000000000160014107eb2463ad25843ed01fd33656c83bdd11db3554a8701000000000022002002265c41f299b3c7f0dda5b9d7bc4135d25c2d8aed286837aa9e0954d70894d606961c000000000016001482a7ecd4624e6856d1b09c27e9f3a82323f49c2d0247304402200911162e99e23e4a26e0219a4bdaaf7a5f790be63a8376516640dcc0860ca4d602203a078371904842e2e6adfbebebcac138db23514b3396851569f5f2bf82c3197a012103cd2d0a4eace5993ebb0a75da85d9070627e64f1a5783cf5217e9bd82d20d1c470247304402200fa8515323410ca2b14b08bf22c618b6ced77b9289cb1dfa7ac10548e2e1b2e002206a407bcafdfb64009182fb5838db9671968abdd902e1194f6883cd0e5413ad36012103d3864eb755690e2b4ff139047419373e36a05630429da76fef5de25eeffb4ffc00000000",
|
|
"prevTxVout": 2,
|
|
"sequence": 4294967293,
|
|
"maxWitnessLen": 107,
|
|
"redeemScript": null
|
|
}
|
|
],
|
|
"changeSPK": "160014d13be5f330b1ea9bbf61f68002b4465e02c341d9",
|
|
"changeSerialId": 1.6080068685336797E19,
|
|
"fundOutputSerialId": 9.390869355804355E18,
|
|
"feeRatePerVb": 10,
|
|
"cetLocktime": 0,
|
|
"refundLocktime": 1630627200
|
|
}
|
|
```
|
|
|
|
Decoding Contract Info:
|
|
```bash
|
|
bitcoin-s-cli decodecontractinfo fdd82ee40000000000010f2cfda7101802035965730000000000010f2c024e6f0000000000000000fda712bcfdd824b8d89fe4d84bdf96299d2e3664acda7e14001297f341afcaca91d3909f12988cb308f309625d89c078bf2268b174faf1c082f1f10bef55834af50b91d9a241ffb2b8b005b07acf849ad2cec22107331dedbf5a607654fad4eafe39c278e27dde68fdd822540001ef8bd9f4445543c63923dde8c00f60d649c445a7772ac4693136b2fd234fcc2f60dfa880fdd80609000203596573024e6f20446f657320746865206d656d706f6f6c20636c656172206f6e20372f322f3231
|
|
{
|
|
"totalCollateral": 69420,
|
|
"contractDescriptor": {
|
|
"outcomes": [
|
|
{
|
|
"outcome": "Yes",
|
|
"localPayout": 69420
|
|
},
|
|
{
|
|
"outcome": "No",
|
|
"localPayout": 0
|
|
}
|
|
]
|
|
},
|
|
"oracleInfo": {
|
|
"announcement": {
|
|
"announcementSignature": "d89fe4d84bdf96299d2e3664acda7e14001297f341afcaca91d3909f12988cb308f309625d89c078bf2268b174faf1c082f1f10bef55834af50b91d9a241ffb2",
|
|
"publicKey": "b8b005b07acf849ad2cec22107331dedbf5a607654fad4eafe39c278e27dde68",
|
|
"event": {
|
|
"nonces": [
|
|
"ef8bd9f4445543c63923dde8c00f60d649c445a7772ac4693136b2fd234fcc2f"
|
|
],
|
|
"maturity": "2021-07-03T00:00:00Z",
|
|
"descriptor": {
|
|
"outcomes": [
|
|
"Yes",
|
|
"No"
|
|
]
|
|
},
|
|
"eventId": "Does the mempool clear on 7/2/21"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Decoding Oracle Announcement:
|
|
```bash
|
|
bitcoin-s-cli decodeannouncement fdd824b1585e18c3bc1d922854329fdb5a402713b161b7baebb6b6f3249936ef79c0a6671027afd7a1126d79e589811042eb4885c0cb7c150b4c4863a1e35a2ac432f7c81d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e4fdd8224d0001424c11a44c2e522f90bbe4abab6ec1bc8ab44c9b29316ce6e1d0d7d08385a474603c2e80fdd80609000203594553024e4f194254432d5553442d4f5645522d35304b2d434f494e42415345
|
|
{
|
|
"announcementSignature": "585e18c3bc1d922854329fdb5a402713b161b7baebb6b6f3249936ef79c0a6671027afd7a1126d79e589811042eb4885c0cb7c150b4c4863a1e35a2ac432f7c8",
|
|
"publicKey": "1d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e4",
|
|
"event": {
|
|
"nonces": [
|
|
"424c11a44c2e522f90bbe4abab6ec1bc8ab44c9b29316ce6e1d0d7d08385a474"
|
|
],
|
|
"maturity": "2021-03-01T00:00:00Z",
|
|
"descriptor": {
|
|
"outcomes": [
|
|
"YES",
|
|
"NO"
|
|
]
|
|
},
|
|
"eventId": "BTC-USD-OVER-50K-COINBASE"
|
|
}
|
|
}
|
|
```
|
|
|
|
Decoding Oracle Attestations
|
|
```bash
|
|
bitcoin-s-cli decodeattestments fdd8687f194254432d5553442d4f5645522d35304b2d434f494e424153451d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e40001424c11a44c2e522f90bbe4abab6ec1bc8ab44c9b29316ce6e1d0d7d08385a474de6b75f1da183a2a4f9ad144b48bf1026cee9687221df58f04128db79ca17e2a024e4f
|
|
{
|
|
"eventId": "BTC-USD-OVER-50K-COINBASE",
|
|
"signatures": [
|
|
"424c11a44c2e522f90bbe4abab6ec1bc8ab44c9b29316ce6e1d0d7d08385a474de6b75f1da183a2a4f9ad144b48bf1026cee9687221df58f04128db79ca17e2a"
|
|
],
|
|
"values": [
|
|
"NO"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Step 3: Set up The DLC
|
|
|
|
### Using the GUI
|
|
|
|
If you're a visual learner there is a [video demo](https://www.youtube.com/watch?v=zy1sL2ndcDg) that explains this process in detail.
|
|
But do note that this demonstrates the old non-adaptor version of DLCs so that the Offer, Accept, Sign protocol is the same, but the contents will be different.
|
|
|
|
If using a numeric contract and/or multiple oracles, messages can get very large and sometimes even too large to for the application.
|
|
To solve this there is an `Export to file` button located under the text box for the messages your wallet will construct.
|
|
This can be used to export a DLC message to a file and then the file can be sent to your counterparty.
|
|
If you receive a file from a counter-party, there is an `Import file` button on every dialog you input a DLC message.
|
|
This can be used to import the file of the DLC message from your counter-party.
|
|
|
|
#### 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.
|
|
|
|
### Using the CLI
|
|
|
|
If using a numeric contract and/or multiple oracles, messages can get very large and sometimes even too large to for the application.
|
|
To solve this there are RPC calls where you can give a file instead of the entire DLC message.
|
|
To output a file you simply just need to pipe the output of a command into a file.
|
|
|
|
For example:
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli acceptdlcoffer [offer] > myDLCAccept.txt
|
|
```
|
|
|
|
#### 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:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli createdlcoffer [contractInfo] [collateral] [feerate] [locktime] [refundlocktime]
|
|
```
|
|
|
|
#### Accepting The Offer
|
|
|
|
Upon receiving a DLC Offer from your counter-party, the following command will create the serialized accept message:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli acceptdlcoffer [offer]
|
|
```
|
|
|
|
or from file:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli acceptdlcofferfromfile [filepath]
|
|
```
|
|
|
|
#### 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:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli signdlc [accept]
|
|
```
|
|
|
|
or from file:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli signdlcfromfile [filepath]
|
|
```
|
|
|
|
|
|
#### Adding DLC Signatures To Your Database
|
|
|
|
Upon receiving a DLC Sign message from your counter-party, add their signatures to your database by:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli adddlcsigs [sign]
|
|
```
|
|
|
|
or from file:
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli adddlcsigsfromfile [filepath]
|
|
```
|
|
|
|
#### Getting Funding Transaction
|
|
|
|
You are now fully setup and can generate the fully signed funding transaction for broadcast using
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli getdlcfundingtx [contractId]
|
|
```
|
|
|
|
where the `contractId` is in all but the messages other than the DLC Offer message, and is also returned by the `adddlcsigs` command.
|
|
|
|
Alternatively, you can use the `getdlcs` command to list all of your current DLCs saved in your wallet.
|
|
|
|
## Step 4: Executing the DLC
|
|
|
|
### Using the GUI
|
|
|
|
#### Execute
|
|
|
|
You can execute the DLC unilaterally with the `Execute` button which will require the oracle signature.
|
|
This will return a fully signed Contract Execution Transaction for the event signed by the oracle.
|
|
|
|
#### Refund
|
|
|
|
If the `refundlocktime` for the DLC has been reached, you can get the fully-signed refund transaction with the `Refund` button and entering the `contractId`.
|
|
|
|
### Using the CLI
|
|
|
|
#### Execute
|
|
|
|
Upon receiving an oracle signature, you can execute the DLC unilaterally with
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli executedlc [contractId] [signatureTLVs]
|
|
```
|
|
|
|
which will return fully signed Contract Execution Transaction for the event signed by the oracle.
|
|
|
|
#### Refund
|
|
|
|
If the `refundlocktime` for the DLC has been reached, you can get the fully-signed refund transaction with
|
|
|
|
```bashrc
|
|
./app/cli/target/universal/stage/bitcoin-s-cli executedlcrefund [contractId]
|
|
```
|