Transaction Semantics

This document defines the lifecycle, ordering, and idempotency semantics for ledger operations.

Operations

CreateAccount

• Implementations MUST support account creation with a name and account type.
• Account identifiers MUST be unique.
• Creating a system account (issuer, treasury) MUST be idempotent by account type.

Mint

• A mint operation MUST credit a destination account and debit the issuer account by the same amount.
• The amount MUST be a positive integer in minimal units.
• The issuer account MAY have a negative balance after a mint.

Transfer

• A transfer operation MUST debit the source account and credit the destination account by the transfer amount.
• The amount MUST be a positive integer in minimal units.
• The fee amount MUST be a non-negative integer in minimal units.
• The total debit for the source account MUST equal amount + fee.
• Fees, when present, MUST be credited to the treasury account.
• Transfers MUST reject from_account_id == to_account_id.
• Transfers MUST reject from_account_id of type treasury and to_account_id of type issuer.
• User accounts MUST NOT be debited below zero by a transfer.

Transaction Lifecycle

• The runtime MUST validate all required fields before applying a transaction.
• Invalid operations MUST NOT modify ledger state.
• Accepted operations MUST produce an immutable transaction record and the corresponding entries.

Ordering

• Accepted transactions MUST be assigned a monotonically increasing sequence that defines their total order.
• Entries associated with a transaction MUST be ordered consistently with the transaction sequence.

Idempotency

Idempotency ensures safe retries in at-least-once delivery environments.

• Mint and transfer operations MUST accept an optional idempotency key.
• When an idempotency key is provided, the runtime MUST return the original transaction for subsequent requests with the same key and MUST NOT apply duplicate effects.
• Clients SHOULD NOT reuse idempotency keys for different payloads; behavior is implementation-defined if they do.

Idempotency Key Format

• Keys MUST be ASCII and match the pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$
• Maximum length is 128 characters.
• If both an Idempotency-Key header and a body field are supplied, they MUST match exactly.