Skip to content

docs: add asset lock special txs #112

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

Merged
merged 4 commits into from
Aug 22, 2024
Merged

docs: add asset lock special txs #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c1674f1
docs(rpc): add new rpcs (#97)
thephez Feb 8, 2024
307b4da
docs: add asset lock tx
thephez Feb 13, 2024
2392fdd
docs: add asset unlock tx
thephez Feb 13, 2024
93deedb
docs: minor label / link update
thephez Feb 14, 2024
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
4 changes: 2 additions & 2 deletions docs/api/remote-procedure-calls-raw-transactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1205,14 +1205,14 @@ _Result (if verbose=`false`)---the serialized transactions_
| Name | Type | Presence | Description |
| -------- | ------------ | ----------------------- | ----------- |
| `result` | object | Required<br>(exactly 1) | If the transaction was found, this will be an object containing the serialized transaction encoded as hex. |
|→<br>TXID / Raw tx | string:string | Required<br>(1 or more) | A key/value pair with the transaction ID (key) and raw transaction data (value). See the [`getrawtransaction` RPC](#rpc-raw-txs-getrawtx-hex) for an example of the hex transaction data. |
|→<br>TXID / Raw tx | string:string | Required<br>(1 or more) | A key/value pair with the transaction ID (key) and raw transaction data (value). See the [`getrawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#rpc-raw-txs-getrawtx-hex) for an example of the hex transaction data. |

_Result (if verbose=`true`)---the decoded transactions_

| Name | Type | Presence | Description |
| --------------------------- | -------------- | ----------------------- | ----------- |
| `result` | object | Required<br>(exactly 1) | If the transaction was found, this will be an object describing it |
|→<br>TXID / Decoded tx | string:string | Required<br>(1 or more) | A key/value pair with the transaction ID (key) and decoded transaction data represented in JSON (value). See the [`getrawtransaction` RPC](#rpc-raw-txs-getrawtx-decoded) for an example of the decoded transaction data. |
|→<br>TXID / Decoded tx | string:string | Required<br>(1 or more) | A key/value pair with the transaction ID (key) and decoded transaction data represented in JSON (value). See the [`getrawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#rpc-raw-txs-getrawtx-decoded) for an example of the decoded transaction data. |

_Examples from Dash Core 20.1.0_

Expand Down
247 changes: 247 additions & 0 deletions docs/reference/transactions-special-transactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ Classical (financial) transactions have a `type` of 0 while special transactions
| 0.13.0 | 3 | 5 | [CbTx](#cbtx) | Masternode List Merkle Proof | hex | compactSize uint |
| 0.13.0 | 3 | 6 | [QcTx](#qctx) | Long-Living Masternode Quorum Commitment | hex | compactSize uint |
| 18.0.0 | 3 | 7 | [MnHfTx](#mnhftx) | Masternode hard fork signal | hex | compactSize uint |
| 21.0.0 | 3 | 8 | [AssetLockTx](#assetlocktx) | Asset Lock Transaction | hex | compactSize uint |
| 21.0.0 | 3 | 9 | [AssetUnlocktx](#assetunlocktx) | Asset Unlock Transaction | hex | compactSize uint |

```{eval-rst}
.. _ref-txs-proregtx:
Expand Down Expand Up @@ -1026,3 +1028,248 @@ An itemized masternode hard fork signal transaction:
0700 ....................................... Type (7 - Masternode Hard Fork Signal)
<Add example mnhfsignal when available>
```

```{eval-rst}
.. _ref-txs-assetlocktx:
```

## AssetLockTx

The Asset Lock transaction is a DIP2-based special transaction that gives Platform the information to assign credits to [identities](inv:platform:std#explanations-identity).

The special transaction type used for asset lock transactions is 8 and the extra payload consists of the following data:

| Bytes | Name | Data type | Description |
|-|-|-|-|
| 1 | version | uint8_t | Asset lock payload version number |
| 1 | count | uint8_t | Number of accounts funded by this asset lock |
| Variable | credit_outputs | vector<TxOut> | The hash of the public key used to claim credits on Dash Platform, as well as the amount of Dash in duffs transferred into credits for this hash |

The following annotated hexdump shows an asset lock transaction.

``` text
0300 ....................................... Version (3)
0800 ....................................... Type (8 - Asset Lock)

01 ......................................... Number of inputs
| eecf4e8f1ffd3a3a4e5033d618231fd0
| 5e5f08c1a727aac420f9a26db9bf39eb ......... Previous outpoint TXID
| 01000000 ................................. Previous outpoint index (1)
|
| 6a ....................................... Bytes in script: 106
|
| 473044022026f169570532332f857cb6
| 4a0b7d9c0837d6f031633e1d6c395d7c
| 03b799460302207eba4c4575a66803ce
| cf50b61ff5f2efc2bd4e61dff00d9d48
| 47aa3d8b1a5e550121036cd0b73d304b
| acc80fa747d254fbc5f0bf944dd8c8b9
| 25cd161bb499b790d08d03 ................... Signature script
|
| 00000000 ................................. Sequence

02 ......................................... Number of outputs
| Transaction Output 1
| | 317dd0be03000000 ....................... Duffs (160.86236465 DASH)
| | 23 ..................................... Bytes in script: 35
| | 21022ca85dba11c4e5a6da3a00e73a08765
| | 319a5d66c2f6434b288494337b0c9ed2dac .... Script
|
| Transaction Output 2
| | 6df29c3b00000000 ....................... Duffs (10.00141421 DASH)
| | 02 ..................................... Bytes in script: 2
| | 6a00 ................................... Script (OP_RETURN)

00000000 ................................... Locktime

46 ......................................... Extra payload size (70)

Asset Lock Payload
| 01 ....................................... Version (1)
|
| 02 ....................................... Count: 2
|
| Credit Output 1
| | 00e1f50500000000 ....................... Duffs (100000000 DASH)
| | 1976a9147c75beb097957cc095
| | 37b615dde9ea6807719cdf88ac ............. Script
|
| Credit Output 2
| | 6d11a73500000000 ....................... Duffs (900141421 DASH)
| | 1976a9147c75beb097957cc095
| | 37b615dde9ea6807719cdf88ac ............. Script
```

### Example Asset Lock Transaction

```Text Raw Transaction hex
0300080001eecf4e8f1ffd3a3a4e5033d618231fd05e5f08c1a727aac420f9a26db9bf39eb0
10000006a473044022026f169570532332f857cb64a0b7d9c0837d6f031633e1d6c395d7c03
b799460302207eba4c4575a66803cecf50b61ff5f2efc2bd4e61dff00d9d4847aa3d8b1a5e5
50121036cd0b73d304bacc80fa747d254fbc5f0bf944dd8c8b925cd161bb499b790d08d0000
000002317dd0be030000002321022ca85dba11c4e5a6da3a00e73a08765319a5d66c2f6434b
288494337b0c9ed2dac6df29c3b00000000026a000000000046010200e1f505000000001976
a9147c75beb097957cc09537b615dde9ea6807719cdf88ac6d11a735000000001976a9147c7
5beb097957cc09537b615dde9ea6807719cdf88ac
```

The JSON representation of a raw transaction can be obtained with the [`getrawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#getrawtransaction) or the [`decoderawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#decoderawtransaction).

```json JSON Representation
{
"txid": "fdb0e981c3febc6c2c032e6f51e6f063bfc6aaa9bd238985a442c93bd376fd57",
"version": 3,
"type": 8,
"size": 283,
"locktime": 0,
"vin": [
{
"txid": "eb39bfb96da2f920c4aa27a7c1085f5ed01f2318d633504e3a3afd1f8f4ecfee",
"vout": 1,
"scriptSig": {
"asm": "3044022026f169570532332f857cb64a0b7d9c0837d6f031633e1d6c395d7c03b799460302207eba4c4575a66803cecf50b61ff5f2efc2bd4e61dff00d9d4847aa3d8b1a5e55[ALL] 036cd0b73d304bacc80fa747d254fbc5f0bf944dd8c8b925cd161bb499b790d08d",
"hex": "473044022026f169570532332f857cb64a0b7d9c0837d6f031633e1d6c395d7c03b799460302207eba4c4575a66803cecf50b61ff5f2efc2bd4e61dff00d9d4847aa3d8b1a5e550121036cd0b73d304bacc80fa747d254fbc5f0bf944dd8c8b925cd161bb499b790d08d"
},
"sequence": 0
}
],
"vout": [
{
"value": 160.86236465,
"valueSat": 16086236465,
"n": 0,
"scriptPubKey": {
"asm": "022ca85dba11c4e5a6da3a00e73a08765319a5d66c2f6434b288494337b0c9ed2d OP_CHECKSIG",
"hex": "21022ca85dba11c4e5a6da3a00e73a08765319a5d66c2f6434b288494337b0c9ed2dac",
"type": "pubkey"
}
},
{
"value": 10.00141421,
"valueSat": 1000141421,
"n": 1,
"scriptPubKey": {
"asm": "OP_RETURN 0",
"hex": "6a00",
"type": "nulldata"
}
}
],
"extraPayloadSize": 70,
"extraPayload": "010200e1f505000000001976a9147c75beb097957cc09537b615dde9ea6807719cdf88ac6d11a735000000001976a9147c75beb097957cc09537b615dde9ea6807719cdf88ac",
"assetLockTx": {
"version": 1,
"creditOutputs": [
"CTxOut(nValue=1.00000000, scriptPubKey=76a9147c75beb097957cc09537b615)",
"CTxOut(nValue=9.00141421, scriptPubKey=76a9147c75beb097957cc09537b615)"
]
}
}
```

```{eval-rst}
.. _ref-txs-assetunlocktx:
```

## AssetUnlockTx

> 🚧 Note
>
> This special transaction has no inputs

The Asset Unlock transaction is a DIP2-based special transaction that enables Platform credits to be withdrawn back to Dash.

The special transaction type used for asset unlock transactions is 9 and the extra payload consists of the following data:

| Bytes | Name | Data type | Description |
|-|-|-|-|
| 1 | version | uint8_t | Asset unlock payload version number |
| 8 | index | uint64_t | The index of the transaction |
| 4 | fee | uint32_t | The transaction fee in duffs that should be awarded to the miner |
| 4 | requestedHeight | uint32_t | The payment chain block height known by platform at the moment of the withdrawal signing |
| 32 | quorumHash | uint256 | Hash of the quorum signing this message |
| 96 | quorumSig | CBLSSig | BLS signature for the entire transaction by a public key associated with the quorum referenced by `quorumHash` |

The following annotated hexdump shows an asset unlock transaction.

``` text
0300 ....................................... Version (3)
0900 ....................................... Type (9 - Asset Unlock)

00 ......................................... Number of inputs

01 ......................................... Number of outputs
| Transaction Output 1
| | 90cff40500000000 ....................... Duffs (0.99930000 DASH)
| | 23 ..................................... Bytes in script: 35
| | 2103d2c317552f5617f534065b9693fd4d7
| | a8925daacdb9d44e908f9ffb0d285ea61ac .... Script

00000000 ................................... Locktime

91 ......................................... Extra payload size (145)

Asset Unlock Payload
| 01 ....................................... Version (1)
|
| 6500000000000000 ......................... Index: 101
| 70110100 ................................. Fee: 70000
| db040000 ................................. Requested height: 1243
|
| 6f0f4a04d9a37a8c7791e90428d596d0
| caf5dc85292537ff92ffd361300c3101 ......... Quorum hash
|
| a533b35ae1d7685c6c795b7344963d48
| 589d536a1c2b22e6a580b46439adaaf8
| 51b4243b48be81d508ef3ff622bcba26
| 030b5bf8aa404dd3b5876727f4112a9d
| af99f27d250059679ae5abd30bc3029d
| eeeb7267c1fa6204f6976a3a7a2512ea ......... Quorum Signature
```

### Example AssetUnlockTx

```Text Raw Transaction hex
03000900000190cff40500000000232103d2c317552f5617f534065b9693fd4d7a8925daacd
b9d44e908f9ffb0d285ea61ac000000009101650000000000000070110100db0400006f0f4a
04d9a37a8c7791e90428d596d0caf5dc85292537ff92ffd361300c3101a533b35ae1d7685c6
c795b7344963d48589d536a1c2b22e6a580b46439adaaf851b4243b48be81d508ef3ff622bc
ba26030b5bf8aa404dd3b5876727f4112a9daf99f27d250059679ae5abd30bc3029deeeb726
7c1fa6204f6976a3a7a2512ea
```

The JSON representation of a raw transaction can be obtained with the [`getrawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#getrawtransaction) or the [`decoderawtransaction` RPC](../api/remote-procedure-calls-raw-transactions.md#decoderawtransaction).

```json JSON Representation
{
"txid": "fb1b419b2b909f2ddb7fabee91d8e1aa7bb8e7114c83712ff20ba1859ec57b30",
"version": 3,
"type": 9,
"size": 200,
"locktime": 0,
"vin": [
],
"vout": [
{
"value": 0.99930000,
"valueSat": 99930000,
"n": 0,
"scriptPubKey": {
"asm": "03d2c317552f5617f534065b9693fd4d7a8925daacdb9d44e908f9ffb0d285ea61 OP_CHECKSIG",
"hex": "2103d2c317552f5617f534065b9693fd4d7a8925daacdb9d44e908f9ffb0d285ea61ac",
"type": "pubkey"
}
}
],
"extraPayloadSize": 145,
"extraPayload": "01650000000000000070110100db0400006f0f4a04d9a37a8c7791e90428d596d0caf5dc85292537ff92ffd361300c3101a533b35ae1d7685c6c795b7344963d48589d536a1c2b22e6a580b46439adaaf851b4243b48be81d508ef3ff622bcba26030b5bf8aa404dd3b5876727f4112a9daf99f27d250059679ae5abd30bc3029deeeb7267c1fa6204f6976a3a7a2512ea",
"assetUnlockTx": {
"version": 1,
"index": 101,
"fee": 70000,
"requestedHeight": 1243,
"quorumHash": "01310c3061d3ff92ff37252985dcf5cad096d52804e991778c7aa3d9044a0f6f",
"quorumSig": "a533b35ae1d7685c6c795b7344963d48589d536a1c2b22e6a580b46439adaaf851b4243b48be81d508ef3ff622bcba26030b5bf8aa404dd3b5876727f4112a9daf99f27d250059679ae5abd30bc3029deeeb7267c1fa6204f6976a3a7a2512ea"
}
}
```
Loading