Contractless/docs/TRANSACTIONS.md

# 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](#shared-concepts)
- [Transaction Type IDs](#transaction-type-ids)
- [Fee Summary](#fee-summary)
- [Transaction Flow](#transaction-flow)
- [Wallet Registration](#wallet-registration)
- [Transaction Types](#transaction-types)
- [Loan Transactions](#loan-transactions)
- [Validation Failures](#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:

```text
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:

```text
create_* tool -> signed JSON -> broadcast_transaction -> mempool checks -> block validation -> balance-sheet update
```

For two-party transactions:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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.