Handle Complex Transaction

Summary

The tx subcommand handle common sighash/multisig transaction. Common here means we can manually select live cells(inputs) to use, and manually add any number of new live cells(outputs). The inputs and outputs must with sighash or multisig lock scripts. The process is based on a json format transaction file. We can initialize the file by tx init:

CKB> tx init --tx-file tx.json
ok

Current directory will have a new tx.json file with content:

{
  "transaction": {
    "version": "0x0",
    "cell_deps": [],
    "header_deps": [],
    "inputs": [],
    "outputs": [],
    "outputs_data": [],
    "witnesses": []
  },
  "multisig_configs": {},
  "signatures": {}
}

The transaction field is a empty transaction. The multisig_configs field is for multisig configuration. The signatures field is for storing signatures of the final transaction, since we support multisig and inputs may owned by more than one secp256k1 private keys.

A Demo

Follow is a demo show how to use tx to build a multisig address with absolute epoch since, then transfer some capacity into this address, then transfer all capacity from this address to other address.

First we build the address:

CKB> tx build-multisig-address --sighash-address ckt1qyqdfjzl8ju2vfwjtl4mttx6me09hayzfldq8m3a0y --since-absolute-epoch 61
lock-arg: 0x9e2578fd0679a24726b7930fffb99a721c26f8db3d00000000010020
lock-hash: 0x0486e7ec2a98b7a19a9f9fcabd8b58f046a36353677663330e512ec13576ea82
mainnet: ckb1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqlm8p7r
testnet: ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n

Since we operate on testnet, we use the testnet address, which is ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n. Then we transfer some capacity to this address:

CKB> wallet transfer --from-account 0xda648442dbb7347e467d1d09da13e5cd3a0ef0e1 --to-address ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n --capacity 20000 --tx-fee 0.0001
Password:
0x1aefd4b0b8e542bbc0f0e9e7f8109646feeb39a087f460aab108dd9e64b274f9

We can use wallet get-capacity to query the total capacity of this address:

CKB> wallet get-capacity --address ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n
total: 20000.0 (CKB)

Since we need to know the out points of live cells owned by this address, we can use wallet get-live-cells to query them.

CKB> wallet get-live-cells --address ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n
current_capacity: 20000.0 (CKB)
current_count: 1
live_cells:
  - capacity: 20000.0 (CKB)
    data_bytes: 0
    index:
      output_index: 0
      tx_index: 1
    lock_hash: 0x0486e7ec2a98b7a19a9f9fcabd8b58f046a36353677663330e512ec13576ea82
    mature: true
    number: 56207
    tx_hash: 0x1aefd4b0b8e542bbc0f0e9e7f8109646feeb39a087f460aab108dd9e64b274f9
    tx_index: 0
    type_hashes: ~
total_capacity: 20000.0 (CKB)
total_count: 1

Also we need to add multisig configration of this address, so we can use inputs/outputs with corresponding multisig lock scripts:

CKB> tx add-multisig-config --sighash-address ckt1qyqdfjzl8ju2vfwjtl4mttx6me09hayzfldq8m3a0y --tx-file tx.json
ok

Please noticed that beside --since-absolute-epoch argument, other argument should be the same as how we build above address (which is ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n).

The file will changed to:

{
  "transaction": { /* ... */ },
  "multisig_configs": {
    "0x9e2578fd0679a24726b7930fffb99a721c26f8db": {
      "sighash_addresses": [
        "ckt1qyqdfjzl8ju2vfwjtl4mttx6me09hayzfldq8m3a0y"
      ],
      "require_first_n": 0,
      "threshold": 1
    }
  },
  "signatures": {}
}

Then we add the input to the transaction:

CKB> tx add-input --tx-hash 0x1aefd4b0b8e542bbc0f0e9e7f8109646feeb39a087f460aab108dd9e64b274f9 --index 0 --tx-file tx.json
ok

And add an output to the transation(here we transfer the capacity to sighash address ckt1qyqg7zchpds6lv3v0nr36z2msu2x9a5lkhrq7kvyww):

CKB> tx add-output --to-sighash-address ckt1qyqg7zchpds6lv3v0nr36z2msu2x9a5lkhrq7kvyww --capacity 19999.9999 --tx-file tx.json
ok

Here the output capacity is 19999.9999 CKB, because we need to remain some capacity as transaction fee.

We can show the details of this transaction:

CKB> tx info --tx-file tx.json
[input] ckt1q3w9q60tppt7l3j7r09qcp7lxnp3vcanvgha8pmvsa3jplykxn3238390r7sv7dzgunt0yc0l7ue5usuymudk0gqqqqqqqgqyqsyxc6n => 20000.0, (data-length: 0, type-script: none, lock-kind: multisig with since)
[output] ckt1qyqg7zchpds6lv3v0nr36z2msu2x9a5lkhrq7kvyww => 19999.9999, (data-length: 0, type-script: none, lock-kind: sighash(secp))
input_total: 20000.0 (CKB)
output_total: 19999.9999 (CKB)
tx_fee: 0.0001 (CKB)

It shows the details of inputs, the details of outputs, total capacity of inputs, total capacity of outputs, and the transaction fee.

Now the main part of the transaction construction is finished. We have to sign this transactions so we can send it to CKB node. There are two steps.

First, we need to build the signature:

CKB> tx sign-inputs --from-account 0xd4c85f3cb8a625d25febb5acdade5e5bf4824fda --tx-file tx.json
Password:
- lock-arg: 0x9e2578fd0679a24726b7930fffb99a721c26f8db3d00000000010020
  signature: 0x0c44c12638277ffa6eafeac55cd918932f1cdbcfd4df413c11e8fb5b48f41ba22f738bad494e63d78c2bf2a4e0f4676db1d48d37f3d872d28bac70b2ef5a567a01

Second, we need to add above signature to the transaction file:

CKB> tx add-signature --lock-arg 0x9e2578fd0679a24726b7930fffb99a721c26f8db3d00000000010020 --signature 0x0c44c12638277ffa6eafeac55cd918932f1cdbcfd4df413c11e8fb5b48f41ba22f738bad494e63d78c2bf2a4e0f4676db1d48d37f3d872d28bac70b2ef5a567a01 --tx-file tx.json
ok

If you have a multisig address with more than one required private keys, you just repeat the tx sign-inputs and tx add-signature actions. Please noticed that in a typical multisig transaction for security consideration we can tx sign-inputs in different machines and then combine the signatures.

Finally, we can send this transaction to CKB node:

CKB> tx send --tx-file tx.json
0x9245ecb248ec88991a80dcb8fee3932fe694ddc4c7ee061fb38f2e27befacf47

Then check the target address:

CKB> wallet get-capacity --address ckt1qyqg7zchpds6lv3v0nr36z2msu2x9a5lkhrq7kvyww
total: 19999.9999 (CKB)