Contractless/docs/BLOCKS_AND_TRANSACTIONS.md

Blocks and Transactions

This page covers the general block and transaction CLI tools:

• create_transfer_tx
• broadcast_transaction
• lookup_block_by_hash
• lookup_block_by_height
• lookup_torrent
• lookup_total_transactions
• lookup_transaction

Most specialized transaction types have their own guides. Token creation and swaps are covered in TOKEN_SWAPS.md, NFTs and RWAs are covered in NFT_TRANSACTIONS.md, loans are covered in LOAN_TRANSACTIONS.md, marketing records are covered in MARKETING_TRANSACTIONS.md, and storage transactions are covered in DATA_STORAGE.md.

On Windows, the compiled binaries usually end in .exe. For example, create_transfer_tx becomes create_transfer_tx.exe.

Amounts and Raw Values

Most CLI prompts ask for normal decimal amounts, such as 1, 1.25, or 0.0001.

Internally, Contractless stores amounts as whole integer units where:

1.00000000 = 100000000

That means a transfer entered as 1.25 appears in the saved transaction JSON as:

"value": 125000000

The same conversion is used for transaction fees.

Signed Transaction Files

Transaction creation tools write signed transaction files into:

./transactions/

The filename is the transaction hash:

./transactions/<transaction_hash>.json

The saved JSON often contains a hash field. That field is a CLI convenience used for filenames and user display. The on-chain transaction struct is still verified from the signed transaction payload itself.

create_transfer_tx

create_transfer_tx creates and signs a transfer transaction.

Transfers can send:

• The network base coin.
• A fungible token.
• A 1-of-1 NFT.
• One item from a numbered NFT series.

The tool saves the signed transaction locally. It does not broadcast it. Use broadcast_transaction after reviewing the saved file.

Usage

Interactive:

./create_transfer_tx

With command-line fields:

./create_transfer_tx <coin> <value> <receiver> <txfee> <nft_series>

Example:

./create_transfer_tx CLTC 10 7ba97ce531937388ef8bca4d8a4ca54cefbefb87.cltc 0.1 0

Fields

coin

The base coin, token ticker, or NFT asset name to transfer. The base coin is accepted case-insensitively. Non-base assets must normalize to a canonical 3-15 character alphanumeric asset id.

value

The amount to send, entered in decimal form. For numbered NFT series transfers, this must be exactly 1.0.

receiver

The receiving wallet address. The tool accepts a registered short address or vanity address and resolves it to the canonical short address before signing.

txfee

The transaction fee, entered in decimal form.

Base coin transfers require a minimum fee of 1% of the transfer amount. Token, NFT, and numbered NFT transfers require the fixed non-base transfer minimum fee.

nft_series

Use 0 for base coin transfers, token transfers, and 1-of-1 NFTs.

Use the numbered series item for a collection NFT. For example, if the asset is a numbered NFT and the user wants to transfer item 12, use:

nft_series = 12

Validation

The network verifies that:

• The transaction is not already in the mempool.
• The sender and receiver are valid canonical registered short addresses.
• The receiver is already registered.
• The receiver is not an all-zero burn address.
• The sender signature matches the sender wallet.
• The asset is the base coin or a canonical padded asset id.
• The fee meets the required minimum.
• Numbered NFT transfers send exactly one item and the numbered NFT exists.
• The sender has enough confirmed plus pending-adjusted balance.
• The transaction hash does not already exist on-chain.

Example Output

{
  "txtype": 2,
  "timestamp": 1783657720,
  "value": 1000000000,
  "coin": "CLTC           ",
  "nft_series": 0,
  "sender": "1439f758f93333734778a6459dc64b8d63a74c06.cltc",
  "receiver": "7ba97ce531937388ef8bca4d8a4ca54cefbefb87.cltc",
  "txfee": 10000000,
  "hash": "8d38f9e9f4f03fb936a6f45e1bcf1a9e706d7f3795e78b7ff16d5b4a4536d73",
  "signature": "<signature>"
}

In this example, value is 10.00000000 and txfee is 0.10000000.

broadcast_transaction

broadcast_transaction submits a signed transaction JSON file to a configured node.

This is the common broadcast path for transaction files created by the CLI tools.

Usage

./broadcast_transaction <hash.json>

Example:

./broadcast_transaction ./transactions/8d38f9e9f4f03fb936a6f45e1bcf1a9e706d7f3795e78b7ff16d5b4a4536d73.json

The tool asks for the wallet path and wallet decryption key so it can authenticate to the node. The transaction file itself must already contain the required signature or signatures.

Success Output

successful_broadcast: true
8d38f9e9f4f03fb936a6f45e1bcf1a9e706d7f3795e78b7ff16d5b4a4536d73

If every configured node fails or rejects the transaction, the tool prints the node error or:

failed to connect

lookup_block_by_height

lookup_block_by_height asks a configured node for a block at a specific height.

Usage

./lookup_block_by_height <block_number>

Example:

./lookup_block_by_height 31445

The tool asks for the wallet path and wallet decryption key for the node handshake. This lookup does not spend funds.

Example Return

The exact transaction list depends on the block contents, but the response is a decoded block JSON object:

{
  "vrf_block": {
    "unmined_block": {
      "timestamp": 1783657720,
      "miner": "1439f758f93333734778a6459dc64b8d63a74c06.cltc",
      "previous_hash": "<previous_block_hash>",
      "next_block_difficulty": 1806884765625000,
      "nonce": 42
    },
    "vrf": 123456789,
    "proof": "<miner_signature_proof>"
  },
  "transactions": [
    {
      "Rewards": {
        "unsigned": {
          "txtype": 1,
          "timestamp": 1783657720,
          "value": 41666666666
        }
      }
    }
  ]
}

If the node returns a text error, the text is printed directly. If binary data cannot be decoded as a block, the tool prints the raw response as hex JSON.

lookup_block_by_hash

lookup_block_by_hash asks a configured node for a block by its block hash.

Usage

./lookup_block_by_hash <block_hash>

Example:

./lookup_block_by_hash 8d38f9e9f4f03fb936a6f45e1bcf1a9e706d7f3795e78b7ff16d5b4a4536d73

The hash must be 64 hexadecimal characters.

The returned JSON has the same decoded block shape as lookup_block_by_height.

lookup_torrent

lookup_torrent asks a configured node for the torrent metadata associated with a block height.

Blocks and torrents work together in Contractless. The block file contains the block header and transaction payload. The torrent metadata describes how peers can retrieve and verify the block data used during sync and relay.

Usage

./lookup_torrent <block_number>

Example:

./lookup_torrent 31445

The tool asks for the wallet path and wallet decryption key for the node handshake. This lookup does not spend funds.

Example Return

The exact fields depend on the torrent structure, but a successful response is printed as decoded torrent JSON.

{
  "announce": "<announce data>",
  "info": {
    "name": "31445.block",
    "piece_length": 16384,
    "pieces": "<piece hashes>"
  }
}

If the torrent is not found, the node may return a text error such as:

error: Block 31445 not found

If the response cannot be decoded as a torrent but contains bytes, the tool prints a hex JSON fallback.

lookup_total_transactions

lookup_total_transactions asks a configured node for transaction totals grouped by transaction type.

Usage

./lookup_total_transactions

The tool asks for the wallet path and wallet decryption key for the node handshake. This lookup does not spend funds.

Example Return

[
  {
    "txtype": 1,
    "type": "rewards",
    "total": 31445,
    "non_zero": 31345
  },
  {
    "txtype": 2,
    "type": "transfer",
    "total": 82
  },
  {
    "txtype": 3,
    "type": "token",
    "total": 4
  },
  {
    "txtype": 6,
    "type": "swap",
    "total": 1
  }
]

For rewards, total is the total number of reward transactions and non_zero is the number of rewards that paid a non-zero block reward. This lets wallets and explorers show the first 100 free mined blocks while still distinguishing unpaid rewards from paid rewards.

For other transaction types, only total is returned.

lookup_transaction

lookup_transaction asks a configured node for one transaction by transaction hash.

Usage

./lookup_transaction <transaction_hash>

Example:

./lookup_transaction 8d38f9e9f4f03fb936a6f45e1bcf1a9e706d7f3795e78b7ff16d5b4a4536d73

The tool asks for the wallet path and wallet decryption key for the node handshake. This lookup does not spend funds.

Example Return

For a transfer transaction, the output looks like:

{
  "block": 4484,
  "transaction": {
    "unsigned_transfer": {
      "txtype": 2,
      "time": 1782760786,
      "value": 100000000,
      "coin": "CLTC           ",
      "nft_series": 0,
      "sender": "7ba97ce531937388ef8bca4d8a4ca54cefbefb87.cltc",
      "receiver": "1439f758f93333734778a6459dc64b8d63a74c06.cltc",
      "txfee": 1000000
    },
    "signature": "<signature>"
  }
}

block is the confirmed block height where the transaction was found.

transaction contains the decoded transaction struct. The inner field name depends on the transaction type, such as unsigned_transfer, unsigned_create_token, unsigned_nft, unsigned_swap, unsigned_loan_contract, or another transaction-specific payload.

If the transaction is not found, the node may return a plain text error such as:

Transaction not found in mempool.

Common Workflow

A normal transfer flow is:

1. Create the signed transaction.

./create_transfer_tx

2. Review the saved JSON in ./transactions/.

3. Broadcast the signed file.

./broadcast_transaction ./transactions/<transaction_hash>.json

4. Look up the transaction after it is submitted or confirmed.

./lookup_transaction <transaction_hash>

5. Look up the block after the transaction is confirmed.

./lookup_block_by_height <block_number>