13 KiB
Contractless Transaction Reference
Contractless transactions are native protocol operations. They are not smart contracts. Each transaction is validated before block inclusion, then the balance-sheet changes are applied when the block is saved. If an orphan correction rolls a block back, the matching balance-sheet operations are undone before replacement blocks are replayed.
This reference explains what each transaction does, which tool creates it, what fee or tip rules apply and how it changes balances.
Table of Contents
- Shared Concepts
- Transaction Type IDs
- Fee Summary
- Transaction Flow
- Wallet Registration
- Transaction Types
- Loan Transactions
- Validation Failures
Shared Concepts
Addresses
User-facing addresses are network-specific. Mainnet short addresses end with .clc; testnet short addresses end with .cltc.
Vanity addresses are display addresses. When a normal transaction accepts a vanity address, the node resolves it to the real short address before the transaction is saved in blocks, mempool records or balance-sheet records. The only transaction that stores a vanity address as its own transaction field is the vanity-address registration transaction.
Timestamps
Each transaction carries its own timestamp. The transaction timestamp records when the transaction was created, not when it was mined. Blocks also carry their own timestamp, which records when the miner discovered and assembled the valid block.
Fees
Most transactions include a txfee field paid in the base network currency. On mainnet that is CLC. On testnet that is CLTC. The fee is removed from the sender and credited to the miner when the transaction is included in a saved block.
Base-currency transfers use a percentage minimum fee:
minimum fee = ceil(value * 1 / 100)
Token and NFT transfers use a fixed non-base transfer minimum of 1 CLC or CLTC.
Users may pay more than the minimum fee. Higher fees can improve the chance that a transaction is selected when miners have more valid transactions available than will fit in the next block.
Token Tips
Some transaction types also include a token tip. A token tip is different from the base-currency transaction fee. It is paid in the asset involved in the transaction and credited to the miner balance sheet for that asset.
Token tips are used by swap transactions and loan payment transactions.
Signatures
Transactions are signed by the wallet private key. Multi-party transactions require more than one signature. For example, a swap is created by one party, then validated and signed by the second party before broadcast.
Transaction Hashes
Transaction hashes identify the signed transaction. They are used for lookup, mempool records, duplicate checks and block transaction records.
Mempool and Block Validation
Broadcast transactions are checked before they are accepted into peer records. They are checked again when a miner attempts to include them in a block. This keeps invalid, stale or already-spent transaction state from being accepted just because it passed an earlier network request.
Transaction Type IDs
Transaction type bytes are the canonical IDs used in blocks, mempool routing and verification dispatch.
| ID | Transaction | Purpose |
|---|---|---|
| 0 | Genesis | Creates the genesis network record |
| 1 | Rewards | Pays the miner reward |
| 2 | Transfer | Moves CLC, CLTC, tokens or NFTs |
| 3 | Create token | Creates a new token definition |
| 4 | Create NFT | Creates a new NFT definition |
| 5 | Marketing | Creates a marketing record |
| 6 | Swap | Exchanges assets between two parties |
| 7 | Loan | Creates a collateralized loan contract |
| 8 | Loan payment | Pays against an existing loan |
| 9 | Collateral claim | Claims collateral from a defaulted loan |
| 10 | Burn | Burns a token or NFT |
| 11 | Issue token | Issues more supply for an existing token |
| 12 | Vanity address | Registers or updates a vanity address |
Fee Summary
Fixed fees are stored in the smallest coin unit. The values below are shown as human-readable CLC or CLTC.
| Transaction | Minimum fee |
|---|---|
| Base transfer | 1% of transfer value, rounded up |
| Token or NFT transfer | 1 |
| Create token | 500 |
| Create NFT | 0.5 |
| Marketing | 1 |
| Swap | 1 from each party |
| Loan | 3 from lender |
| Loan payment | 0.01 from payer |
| Collateral claim | 3 |
| Burn | 0.0001 |
| Issue token | 100 |
| Vanity address | 5 |
Swap transactions and loan payment transactions may also include token tips paid to the miner in the related asset.
Transaction Flow
The normal user flow is:
create_* tool -> signed JSON -> broadcast_transaction -> mempool checks -> block validation -> balance-sheet update
For two-party transactions:
create_swap_tx/create_loan_tx -> verify_sign_swap_tx/verify_sign_loan_tx -> broadcast_transaction
Wallet registration uses register_wallet directly because it submits the wallet mapping to a peer instead of creating a normal block transaction JSON file.
Wallet Registration
Wallet registration is a network registry operation, not a block transaction type. It submits a signed short-address to long-address mapping so peers can resolve and verify wallet identities during later network operations.
Created with:
register_wallet
Requires tip:
No.
Minimum fee:
None.
Balance-sheet effect:
None.
Notes:
The command returns Wallet registered: <short address> when the peer accepts the mapping.
Transaction Types
Genesis
Purpose:
Creates the genesis transaction for the chain.
Created with:
node startup / genesis creation path
Requires tip:
No.
Minimum fee:
None.
Balance-sheet effect:
Creates the initial chain state required for block zero.
Notes:
Users do not normally create genesis transactions with a CLI tool.
Rewards
Purpose:
Pays the miner reward for a saved block.
Created with:
mining process
Requires tip:
No.
Minimum fee:
None.
Balance-sheet effect:
Credits the miner base-currency balance sheet with the block reward. During the first 100 blocks mined by a registered miner, the reward transaction is valid but has zero value.
Notes:
Reward transactions are created by the miner, not by a standalone user transaction tool.
Transfer
Purpose:
Moves base currency, tokens or NFTs from one wallet to another.
Created with:
create_transfer_tx
Requires tip:
No.
Minimum fee:
Base-currency transfers pay 1% of the transferred value, rounded up. Token and NFT transfers pay the fixed non-base minimum fee of 1 CLC or CLTC.
Balance-sheet effect:
Removes the transferred value and transaction fee from the sender. Adds the transferred value to the receiver. Adds the transaction fee to the miner.
Notes:
Vanity receiver addresses are resolved to the real short address before the transaction is stored.
Create Token
Purpose:
Creates a new token definition.
Created with:
create_tokens_tx
Requires tip:
No.
Minimum fee:
500 CLC or CLTC.
Balance-sheet effect:
Removes the transaction fee from the creator and credits the fee to the miner. Creates the token record used by later issue-token and transfer transactions.
Notes:
Token names are fixed-length protocol fields. Duplicate token names are rejected.
Issue Token
Purpose:
Issues additional supply for an existing token.
Created with:
create_issue_token_tx
Requires tip:
No.
Minimum fee:
100 CLC or CLTC.
Balance-sheet effect:
Removes the transaction fee from the issuer and credits the fee to the miner. Credits the issued token amount to the issuer if the token rules allow more supply.
Notes:
Hard-limited tokens cannot be issued past their allowed supply.
Create NFT
Purpose:
Creates a new NFT definition. This can be a 1/1 NFT or a series NFT.
Created with:
create_nft_tx
Requires tip:
No.
Minimum fee:
0.5 CLC or CLTC.
Balance-sheet effect:
Removes the transaction fee from the creator and credits the fee to the miner. Creates the NFT record and credits the NFT ownership state to the creator.
Notes:
Use series number 0 for a 1/1 NFT in lookup tooling.
Burn
Purpose:
Destroys a token or NFT balance.
Created with:
create_burn_tx
Requires tip:
No.
Minimum fee:
0.0001 CLC or CLTC.
Balance-sheet effect:
Removes the burned asset from the burner. Removes the base-currency transaction fee from the burner and credits the fee to the miner.
Notes:
Base currency cannot be burned with this transaction type.
Marketing
Purpose:
Creates a marketing record with campaign metadata, impression value and click value.
Created with:
create_marketing_tx
Requires tip:
No.
Minimum fee:
1 CLC or CLTC.
Balance-sheet effect:
Removes the transaction fee from the advertiser and credits the fee to the miner. Stores the marketing record for later lookup.
Notes:
The marketing record stores its own transaction data. It does not move a token or NFT balance to another wallet.
Vanity Address
Purpose:
Registers or updates the wallet vanity address mapping.
Created with:
create_vanity_tx
Requires tip:
No.
Minimum fee:
5 CLC or CLTC.
Balance-sheet effect:
Removes the transaction fee from the registering wallet and credits the fee to the miner. Registers the vanity address mapping so future user-facing input can resolve to the wallet short address.
Notes:
The vanity-address transaction is the only normal transaction type that stores the vanity address itself. Other transactions store the resolved short address.
Swap
Purpose:
Exchanges assets between two wallets.
Created with:
create_swap_tx
verify_sign_swap_tx <path/to/file.json>
Requires tip:
Yes. Swap transactions include tip1 and tip2, paid in the assets being swapped.
Minimum fee:
1 CLC or CLTC from each party.
Balance-sheet effect:
Removes each offered asset from its sender and credits it to the other party. Removes each party's base-currency transaction fee and credits those fees to the miner. Removes token tips from the parties and credits the tips to the miner in the related assets.
Notes:
The first party creates the swap JSON. The second party validates and signs it before broadcast.
Loan Transactions
Loan, loan payment and collateral claim transactions are related. The loan transaction creates the contract terms. Loan payment transactions pay against that contract. Collateral claim transactions enforce the collateral path when the contract rules allow it.
Loan
Purpose:
Creates a collateralized loan contract between lender and borrower.
Created with:
create_loan_tx
verify_sign_loan_tx <path/to/file.json>
Requires tip:
No.
Minimum fee:
3 CLC or CLTC paid by the lender.
Balance-sheet effect:
Moves or locks the relevant loan and collateral values according to the contract terms. Removes the lender transaction fee and credits it to the miner.
Notes:
The first party creates the loan JSON. The second party validates and signs it before broadcast.
Loan Payment
Purpose:
Pays against an existing loan contract.
Created with:
create_loan_payment_tx
Requires tip:
Yes. Loan payment transactions include a miner tip in the loan token.
Minimum fee:
0.01 CLC or CLTC.
Balance-sheet effect:
Removes the payment amount, token tip and base-currency transaction fee from the payer. Credits the payment to the loan receiver according to the contract. Credits the base fee and token tip to the miner.
Notes:
Loan payments must match the active loan contract state.
Collateral Claim
Purpose:
Claims collateral from a loan contract when the contract rules allow it.
Created with:
create_collateral_claim_tx
Requires tip:
No.
Minimum fee:
3 CLC or CLTC.
Balance-sheet effect:
Moves eligible collateral to the claimant according to the contract. Removes the base-currency transaction fee from the claimant and credits the fee to the miner.
Notes:
Collateral claims fail when the loan state does not allow collateral to be claimed.
Validation Failures
Common validation failures include:
- Invalid network address.
- Invalid vanity address mapping.
- Invalid transaction signature.
- Missing second signature on a two-party transaction.
- Transaction fee below the required minimum.
- Insufficient base-currency balance for fees.
- Insufficient token or NFT balance for the asset being moved.
- Duplicate token, NFT or vanity registration.
- Token supply rules reject the requested issue amount.
- Loan contract state does not match the payment or collateral claim.
- Transaction has already been accepted or conflicts with current mempool state.
When a transaction fails validation, fix the transaction fields or wallet state before broadcasting again.