From c5d29a24cfe5da829100aa90f64fb95570ebcb4e Mon Sep 17 00:00:00 2001 From: sosaucily Date: Mon, 20 Nov 2023 11:13:30 +0100 Subject: [PATCH 1/4] Update documentation for ordinals --- docs/Ordinal.md | 43 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/docs/Ordinal.md b/docs/Ordinal.md index 9ed1238b..fafda5a5 100644 --- a/docs/Ordinal.md +++ b/docs/Ordinal.md @@ -1,13 +1,41 @@ # Ordinal Support -It is possible to use an ordinal as part of the collateral of a DLC. -To do so, an [`OrdDescriptor`](../dlc-manager/src/contract/ord_descriptor.rs) must be used. -This descriptor contains information about the ordinal being included in the DLC (location in the blockchain and the transaction that includes is), as well as information about the event upon which the DLC is based. +This library now supports the locking of an ordinal as part of the collateral of a DLC. + +Notes: +* An ordinal is inscribed into a single satoshi. However, that satoshi is often part of a larger UTXO. DLCs lock UTXOs, so please keep that context in mind. + +* In all cases, the gas fee to lock and later unlock the DLC is split between both parties. + +* For more information about DLCs, please see the main folder of this repo, the [`DLC-Link docs page`](https://docs.dlc.link), https://github.com/dlc-link, and the main https://github.com/discreetlogcontracts/dlcspecs specifications page. + +> Resizing UTXOs +> +> Please note, this package does not currently support the re-sizing of the UTXO containing the ordinal within the DLC. See [this section](#changing-postage) for more details + + +## Supported types of DLCs + +### DLC with only the ordinal +This package supports the use case when the offering party of the DLC locks the ordinal-containing UTXO into the DLC, and the counter-party (the acceptor) does not lock any collateral. + +In this case, the outcome is essentially binary, either the ordinal containing UTXO goes to the offeror, or the acceptor. + +### Ordinal with additional collateral +This package also supports the case when the offering party of the DLC locks the ordinal-contianing UTXO into the dlc, AND any amount of addition collateral is locked into the DLC by either party. + +1. In this case, the outcome of the UTXO containing the ordinal will go to either party A or B, without resizing (as described earlier) +2. The remaining collateral locked by either, or both, parties can be split between the parties based on the standard DLC enumerated or numerical outcome guidelines. + +### Locking an ordinal in the DLC + +To lock an ordinal, an [`OrdDescriptor`](../dlc-manager/src/contract/ord_descriptor.rs) must be used. This descriptor contains information about the ordinal being included in the DLC (location in the blockchain and the transaction that includes is), as well as information about the event upon which the DLC is based. + Event outcomes can be, as for regular contracts, enumerated or numerical. ## Enumerated events -Ordinal DLCs based on enumerated events include, in addition to the regular enumerated event information, an array of boolean indicating for each possible outcome whether the ordinal should be given to the offer party (note this means that this array *must* be have the same number of elements as there are possible outcomes). +Ordinal DLCs based on enumerated events include, in addition to the regular enumerated event information, an array of boolean indicating for each possible outcome whether the ordinal should be given to the *offer* party (note this means that this array *must* have the same number of elements as there are possible outcomes). ## Numerical events @@ -19,10 +47,13 @@ These intervals indicate the ranges of outcomes for which the ordinal should be ## Changing postage It is currently not possible to change the postage of the ordinal. -This means that if an ordinal is contained in a 1BTC UTXO, the entire 1BTC will be included in the DLC and given to the ordinal winner. -Changing the postage should thus be done prior to including the ordinal in a DLC. + +This means that if an ordinal is contained in a 1BTC UTXO, the entire 1BTC will be included in the DLC, and given to the ordinal winner without changing the sats in the UTXO. + +Changing the postage should thus be done prior to including the ordinal in a DLC by the wallet. In addition, the postage of the ordinal will be merged with the payout of the winner. + This means that if a party is given an ordinal with a postage of 1BTC in addition to a payout of 1BTC, the output of the CET including the ordinal will have a value of 2BTC. # How it works From 70edf27e0505b1317fb213af653cd71c1d6d69bc Mon Sep 17 00:00:00 2001 From: sosaucily Date: Tue, 21 Nov 2023 11:53:33 +0100 Subject: [PATCH 2/4] cleaned up the ordinal readme --- docs/Ordinal.md | 46 ++++++++++++++-------------------------------- 1 file changed, 14 insertions(+), 32 deletions(-) diff --git a/docs/Ordinal.md b/docs/Ordinal.md index fafda5a5..5095715e 100644 --- a/docs/Ordinal.md +++ b/docs/Ordinal.md @@ -1,31 +1,20 @@ # Ordinal Support -This library now supports the locking of an ordinal as part of the collateral of a DLC. +This library supports the locking of an ordinal as part of the collateral of a DLC. -Notes: -* An ordinal is inscribed into a single satoshi. However, that satoshi is often part of a larger UTXO. DLCs lock UTXOs, so please keep that context in mind. +## Ordinals & additional collateral -* In all cases, the gas fee to lock and later unlock the DLC is split between both parties. +The DLC can contain only 1 ordinal, either locked by the offering party or the accepting party. -* For more information about DLCs, please see the main folder of this repo, the [`DLC-Link docs page`](https://docs.dlc.link), https://github.com/dlc-link, and the main https://github.com/discreetlogcontracts/dlcspecs specifications page. +Either of the participants can choose to include additional satoshis as collateral into the DLC, along with the ordinal. -> Resizing UTXOs -> -> Please note, this package does not currently support the re-sizing of the UTXO containing the ordinal within the DLC. See [this section](#changing-postage) for more details +## How it works +In order to ensure that the ordinal does not get lost to fee, the DLC transactions for DLCs including an ordinal are created in the following way: -## Supported types of DLCs - -### DLC with only the ordinal -This package supports the use case when the offering party of the DLC locks the ordinal-containing UTXO into the DLC, and the counter-party (the acceptor) does not lock any collateral. - -In this case, the outcome is essentially binary, either the ordinal containing UTXO goes to the offeror, or the acceptor. - -### Ordinal with additional collateral -This package also supports the case when the offering party of the DLC locks the ordinal-contianing UTXO into the dlc, AND any amount of addition collateral is locked into the DLC by either party. - -1. In this case, the outcome of the UTXO containing the ordinal will go to either party A or B, without resizing (as described earlier) -2. The remaining collateral locked by either, or both, parties can be split between the parties based on the standard DLC enumerated or numerical outcome guidelines. +- The ordinal input is always set as the first one in the funding transaction, +- The funding output is always set as the first one in the funding transaction, +- The party getting the ordinal will always have its CET output in the first position. ### Locking an ordinal in the DLC @@ -33,18 +22,18 @@ To lock an ordinal, an [`OrdDescriptor`](../dlc-manager/src/contract/ord_descrip Event outcomes can be, as for regular contracts, enumerated or numerical. -## Enumerated events +### Enumerated events -Ordinal DLCs based on enumerated events include, in addition to the regular enumerated event information, an array of boolean indicating for each possible outcome whether the ordinal should be given to the *offer* party (note this means that this array *must* have the same number of elements as there are possible outcomes). +Ordinal DLCs based on enumerated events include, in addition to the regular enumerated event information, an array of boolean indicating for each possible outcome whether the ordinal should be given to the _offer_ party (note this means that this array _must_ have the same number of elements as there are possible outcomes). -## Numerical events +### Numerical events Ordinal DLCs based on numerical events include, in addition to the regular numerical event information, an array or intervals. These intervals indicate the ranges of outcomes for which the ordinal should be given to the offer party. -# Limitations +## Limitations -## Changing postage +### Changing postage It is currently not possible to change the postage of the ordinal. @@ -55,10 +44,3 @@ Changing the postage should thus be done prior to including the ordinal in a DLC In addition, the postage of the ordinal will be merged with the payout of the winner. This means that if a party is given an ordinal with a postage of 1BTC in addition to a payout of 1BTC, the output of the CET including the ordinal will have a value of 2BTC. - -# How it works - -In order to ensure that the ordinal does not get lost to fee, the DLC transactions for DLCs including an ordinal are created in the following way: -* The ordinal input is always set as the first one in the funding transaction, -* The funding output is always set as the first one in the funding transaction, -* The party getting the ordinal will always have its CET output in the first position. From 816d447d0f5fd2752a75cc8ce763a98346d43257 Mon Sep 17 00:00:00 2001 From: Jesse Eisenberg Date: Thu, 23 Nov 2023 09:08:43 +0000 Subject: [PATCH 3/4] Update docs/Ordinal.md Co-authored-by: Thibaut Le Guilly --- docs/Ordinal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Ordinal.md b/docs/Ordinal.md index 5095715e..ecd55ae7 100644 --- a/docs/Ordinal.md +++ b/docs/Ordinal.md @@ -10,7 +10,7 @@ Either of the participants can choose to include additional satoshis as collater ## How it works -In order to ensure that the ordinal does not get lost to fee, the DLC transactions for DLCs including an ordinal are created in the following way: +In order to ensure that the ordinal gets properly assigned and not given to miners as fee, the DLC transactions for DLCs including an ordinal are created in the following way: - The ordinal input is always set as the first one in the funding transaction, - The funding output is always set as the first one in the funding transaction, From 2b56564d957be1fe6cf9754ba7f942928d451c17 Mon Sep 17 00:00:00 2001 From: Jesse Eisenberg Date: Thu, 23 Nov 2023 10:08:56 +0100 Subject: [PATCH 4/4] Update docs/Ordinal.md Co-authored-by: Thibaut Le Guilly --- docs/Ordinal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Ordinal.md b/docs/Ordinal.md index ecd55ae7..b58bf4a3 100644 --- a/docs/Ordinal.md +++ b/docs/Ordinal.md @@ -16,7 +16,7 @@ In order to ensure that the ordinal gets properly assigned and not given to mine - The funding output is always set as the first one in the funding transaction, - The party getting the ordinal will always have its CET output in the first position. -### Locking an ordinal in the DLC +### Locking an ordinal in a DLC To lock an ordinal, an [`OrdDescriptor`](../dlc-manager/src/contract/ord_descriptor.rs) must be used. This descriptor contains information about the ordinal being included in the DLC (location in the blockchain and the transaction that includes is), as well as information about the event upon which the DLC is based.