|
1 | | -# Auctions |
| 1 | +--- |
| 2 | +description: A low level overview of the spaces protocol but not an exact spec! |
| 3 | +--- |
| 4 | + |
| 5 | +# Spec |
| 6 | + |
| 7 | +## Auctions |
2 | 8 |
|
3 | 9 | The auction mechanism involves selecting some UTXO to represent the Space, which is "passed" around between bidders until the auction concludes. Bidders leave a partially signed Bitcoin transaction (PSBT) stating, "If I'm outbid, the next person may spend my space output, on the condition they return my bid to me". Bid amounts are sent to an OP\_RETURN address, which also carries the Bid PSBT in a compressed format. |
4 | 10 |
|
5 | 11 | As the auction progresses, each new bidder consumes the previous space output and creates a new one. This process continues until the final space output is created by the winner. The burning of funds happens incrementally. For example, if Alice places an initial bid burning 1000 sats, and Bob wants to bid 1500 sats, Bob would refund Alice's 1000 sats and burn an additional 500 sats. Since all bids are attempting to spend the same UTXO, the Bitcoin blockchain will still guarantee that only one of the bids manages to burn their coins during simultaneous bidding. For this reason, it's important to burn a small amount in the initial bid because the auction isn't established yet. |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +## Bid Psbt Format |
| 16 | + |
| 17 | +{% hint style="info" %} |
| 18 | +If you would like to manually construct bid transactions, you can use the Spaces Wallet CLI to get the bid contract signature for the auctioned space output, total burned and other details:\ |
| 19 | +\ |
| 20 | +$ `space-cli getspace myspacename` |
| 21 | +{% endhint %} |
| 22 | + |
| 23 | +The bid PSBT spends an _auctioned_ space output and refunds the previous bidder's burned coins. Bid PSBTs must follow the exact structure defined here otherwise it would not be possible to re-construct it from the compressed form: |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +| Field | Value | |
| 28 | +| ------------------ | ----- | |
| 29 | +| **TX** **Version** | 2 | |
| 30 | +| **Lock Time** | 0 | |
| 31 | + |
| 32 | +**Input** |
| 33 | + |
| 34 | +| Field | Value | |
| 35 | +| --------------- | ---------------------- | |
| 36 | +| Previous Output | `prev_txid:prev_index` | |
| 37 | +| Sequence | `0xFFFFFFFD` | |
| 38 | +| Sighash type | `SINGLE\|ANYONECANPAY` | |
| 39 | + |
| 40 | +**Output** |
| 41 | + |
| 42 | +| Field | Value | |
| 43 | +| ------------- | --------------------------- | |
| 44 | +| Script Pubkey | `prev_script_pubkey` | |
| 45 | +| Value | `total_burned + prev_value` | |
| 46 | + |
| 47 | +Where: |
| 48 | + |
| 49 | +* `prev_txid:prev_index` refers to the transaction ID and output index of the previous auctioned space UTXO. |
| 50 | +* `total_burned` is the total amount of coins burned during the auction until this point. |
| 51 | +* `prev_value` is the value of the previous output (`prev_txid:prev_index`) |
| 52 | +* `prev_script_pubkey` the exact p2tr script pubkey of (`prev_txid:prev_index`) |
| 53 | + |
| 54 | +**Compressing Bid PSBT to 65 bytes** |
| 55 | + |
| 56 | +<figure><picture><source srcset="../.gitbook/assets/cpsbt-dark.png" media="(prefers-color-scheme: dark)"><img src="../.gitbook/assets/cpsbt-light.png" alt=""></picture><figcaption><p><br>In this example, the Space UTXO would be identified with the outpoint <code>#f9395e:6</code></p></figcaption></figure> |
| 57 | + |
| 58 | +To fit the PSBT into a single OP\_RETURN (80-byte limit), we: |
| 59 | + |
| 60 | +1. Omit known details (tx version, input sequence, lock time). |
| 61 | +2. Use transactions with at least two unspent outputs for auctions (these outputs must be [tracked](broken-reference) by the protocol). |
| 62 | +3. Encode information in this format: |
| 63 | + |
| 64 | +| **Inputs** | **Outputs** | |
| 65 | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | |
| 66 | +| Previous Output: `prev_txid:prev_index` | <p>Script Pubkey: <code>OP_RETURN OP_PUSHBYTES_65 prev_index_2:64-byte sig</code><br>Value: <code>bid_increment</code></p> | |
| 67 | + |
| 68 | +Where: |
| 69 | + |
| 70 | +* `prev_txid`: Transaction ID containing the UTXO to be auctioned |
| 71 | +* `prev_index`: Any output index from `prev_txid` (references the transaction) |
| 72 | +* `prev_index_2`: Index of the output to be auctioned (1 byte) |
| 73 | +* `64-byte sig`: Schnorr signature |
| 74 | +* `bid_increment`: The current bid increment which equals the bid amount minus the total burned in prior bids and must be greater than zero |
| 75 | + |
| 76 | +Total size: 65 bytes (1 byte + 64 bytes), fitting within the OP\_RETURN limit. |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +## Making bids |
| 81 | + |
| 82 | +A bid transaction carries a Bid PSBT and consumes a previous Bid PSBT (if any) |
| 83 | + |
| 84 | +| Inputs/Outputs | Notes | |
| 85 | +| -------------------------------------------- | ---------------------------------- | |
| 86 | +| Carried bid psbt input/output pair | Offers a new UTXO for the next bid | |
| 87 | +| Re-constructed refund psbt Input/Output pair | Spends auctioned UTXO | |
| 88 | + |
| 89 | +In scenarios where multiple bids are placed simultaneously on the same auctioned space output from the re-constructed PSBT, only one bid will succeed in burning the coins. |
| 90 | + |
| 91 | + |
| 92 | + |
| 93 | +## **Open Transactions** |
| 94 | + |
| 95 | +{% hint style="warning" %} |
| 96 | +When opening an auction for a space, avoid placing large initial bids. If two auctions for the same space are opened simultaneously, only the first to be included in a block will establish the auction process for that space. To mitigate potential losses, the Spaces wallet currently defaults to 1000 sats for initial bids. |
| 97 | +{% endhint %} |
| 98 | + |
| 99 | +An open transaction is exactly the same as a bid transaction except it includes a [space script](broken-reference) which reveals the name in the witness. |
| 100 | + |
| 101 | +``` |
| 102 | +OP_OPEN <sname> |
| 103 | +``` |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +## Claiming a space |
| 108 | + |
| 109 | +{% hint style="warning" %} |
| 110 | +Attempting to register a space before the claim period will invalidate the auction causing the current holder to lose their bid without successfully registering the space. |
| 111 | +{% endhint %} |
| 112 | + |
| 113 | +Once a space enters the claim period, the current space output holder i.e the winner can safely register it. It's important to note that auctions remain open indefinitely until the winner claims. The registration process itself is straightforward: a register transaction is identical to a [transfer](broken-reference) and requires no additional metadata. |
| 114 | + |
| 115 | + |
| 116 | + |
| 117 | +#### How does the protocol distinguish bid spends from claim spends? |
| 118 | + |
| 119 | +Since bidding is still possible in the claim period, the protocol determines if a spend of a space output is a bid spend if the following conditions are met: |
| 120 | + |
| 121 | +* The transaction version, lock time, input sequence for the space output spend, ... etc match the [Bid PSBT](broken-reference) format. |
| 122 | +* It's a P2TR key spend with a signature matching exactly the one carried out in the PSBT. |
| 123 | + |
| 124 | +In all other cases it will be interpreted as a claim. |
| 125 | + |
| 126 | + |
| 127 | + |
| 128 | + |
| 129 | + |
| 130 | +## Moving Space Utxos |
| 131 | + |
| 132 | +<figure><picture><source srcset="../.gitbook/assets/space-utxos-dark.png" media="(prefers-color-scheme: dark)"><img src="../.gitbook/assets/space-utxos-light.png" alt=""></picture><figcaption></figcaption></figure> |
| 133 | + |
| 134 | +Space UTXOs are indistinguishable from standard Bitcoin UTXOs and may carry any value. Spaces can be transferred by following a simple rule. If the space is at input index N, then it will be at output index N + 1. |
| 135 | + |
| 136 | +## Listing spaces for sale |
| 137 | + |
| 138 | +You can sell spaces in a trustless way by creating a PSBT with the space as an input and required payment as the output signed with `SINGLE|ANYONECANPAY`. Then anyone can complete the transaction paying the required amount and getting the Space as one of their outputs. |
| 139 | + |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | + |
| 144 | +## Script format |
| 145 | + |
| 146 | + |
| 147 | + |
| 148 | +Scripts are very simple. They're are embedded within standard Bitcoin scripts and are interpreted as a NOP by the Bitcoin blockchain but they define protocol specific operations on top of what can already be specified with Bitcoin scripting capabilities. |
| 149 | + |
| 150 | +Scripts are identified with a 4-byte magic (0xDE repeated) followed by an op code and its data |
| 151 | + |
| 152 | +For example, to encode the following space script: |
| 153 | + |
| 154 | +<pre><code><strong>OP_OPEN @bitcoin |
| 155 | +</strong></code></pre> |
| 156 | + |
| 157 | +It would look like this when embedded as a Bitcoin script: |
| 158 | + |
| 159 | +``` |
| 160 | +OP_PUSHBYTES26 dededede0107626974636f696e |
| 161 | +OP_DROP |
| 162 | +``` |
| 163 | + |
| 164 | +The protocol will read any push bytes in the transaction for spends of outputs relevant to the protocol looking for the magic prefix. |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | +The following are the op codes useable within a space script |
| 169 | + |
| 170 | +<table><thead><tr><th width="195">OP</th><th width="161">Code</th><th width="157">OP Data</th><th>Description</th></tr></thead><tbody><tr><td>OP_OPEN</td><td>0x01</td><td>Length prefixed space name</td><td>Reveals the space name for auction. Requires a <a href="broken-reference">Bid PSBT</a> to be carried in the transaction</td></tr><tr><td>OP_SETFALLBACK</td><td>0x02</td><td>Length prefixed bytes</td><td>Removes the top stack item; associates the given bytes with the space output at the specified index</td></tr><tr><td>OP_RESERVE_1..4</td><td>0xFC to 0xFF</td><td>--</td><td>Marks space as reserved until the specific op code is enabled in a future upgrade</td></tr></tbody></table> |
| 171 | + |
| 172 | +All other op code values are interperted as a NOP. |
| 173 | + |
| 174 | + |
| 175 | + |
| 176 | +## Tracking UTXOs |
| 177 | + |
| 178 | +The Spaces protocol tracks relevant Unspent Transaction Outputs (UTXOs) instead of monitoring the entire Bitcoin UTXO set. This approach allows clients like [spaced](https://github.com/buffrr/spaces-docs/blob/main/deep-dive/broken-reference/README.md) to operate without relying on the full Bitcoin UTXO set database, enabling them to sync using Simplified Payment Verification (SPV). This selective tracking also enables faster sync since the protocol does not need to check the witness of every input in every transaction looking for [space script](broken-reference)[s](broken-reference). Additionally, it enables building a smaller more lightweight version of [Utreexo](https://eprint.iacr.org/2019/611) for the zk-light clients. |
| 179 | + |
| 180 | +The protocol automatically tracks any space outputs. However, for transactions creating [auctioned outputs](broken-reference) and/or committing to P2TR [space scripts](broken-reference), you need to indicate that such transactions are creating outputs relevant to the protocol: |
| 181 | + |
| 182 | +* The transaction must use a special locktime ending with `222` |
| 183 | +* Within such transactions, any outputs with a value ending in `2` are tracked. |
| 184 | + |
| 185 | +While this may occasionally result in false positives, these are removed from the tracked set once they're spent. |
| 186 | + |
| 187 | + |
| 188 | + |
| 189 | +## Covenants |
| 190 | + |
| 191 | +While Bitcoin itself doesn't have native [covenant](https://bitcoinops.org/en/topics/covenants/) capabilities, protocol-specific spending conditions can be implemented for space outputs. If these conditions are not met, the space is revoked, effectively enforcing how space outputs can be spent. |
| 192 | + |
| 193 | +<table><thead><tr><th width="150">Covenant</th><th>Properties</th><th>Covenant Definition</th></tr></thead><tbody><tr><td>bid</td><td>claim_height: Block height at which the auction winner may safely claim the space. If null, it means space is in pre-auctions</td><td>Spends of this output must be bid spends creating other bid outputs unless the `claim_height` is reached in which case it acts as a transfer covenant for the winner.</td></tr><tr><td>transfer</td><td>expire_height</td><td>Spends of this output must create a corresponding output at N+1. Once the `expire_height` is reached, this essentially becomes anyone can spend in the sense that the space can be -reopened for auction.</td></tr><tr><td>reserved</td><td></td><td>If a space uses one of the reserved op codes, it will be reserved until a future upgrade enables that op code. This is to enable future extensibility.</td></tr></tbody></table> |
| 194 | + |
0 commit comments