Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for ordinals #175

Merged
merged 4 commits into from
Nov 24, 2023
Merged

Update documentation for ordinals #175

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c5d29a2
Update documentation for ordinals
sosaucily Nov 20, 2023
70edf27
cleaned up the ordinal readme
sosaucily Nov 21, 2023
816d447
Update docs/Ordinal.md
sosaucily Nov 23, 2023
2b56564
Update docs/Ordinal.md
sosaucily Nov 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 30 additions & 17 deletions docs/Ordinal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,46 @@
# 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 supports the locking of an ordinal as part of the collateral of a DLC.

## Ordinals & additional collateral

The DLC can contain only 1 ordinal, either locked by the offering party or the accepting party.

Either of the participants can choose to include additional satoshis as collateral into the DLC, along with the ordinal.

## How it works

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,
- The party getting the ordinal will always have its CET output in the first position.

### 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.

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* 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
### 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.
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.

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.
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.

# How it works
Changing the postage should thus be done prior to including the ordinal in a DLC by the wallet.

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.
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.
Loading