Concept
Transactions and UTXOs
How Tenrai stores value in unspent outputs, what a transaction contains, how inputs are authorized, how mass sets the fee, and what a payload is.
On this page
Outputs
All TRAI sits in unspent transaction outputs. An output is an amount in atoms and a 41-byte spend lock that says who may spend it. A balance is the sum of the outputs locked to an address.
A transaction spends whole outputs and creates new ones. What the inputs hold beyond the new outputs is the fee.
An output paid to the burn address is the exception. The cut that executes the transaction creates no output for it and adds its amount to the burned supply.
What a transaction contains
| Part | Content |
|---|---|
| Chain binding | Protocol version, chain ID and the hash of the ledger rules. A transaction is valid on one chain only |
| Validity interval | The first and last cut height at which it may execute |
| Inputs | Up to 8 outputs to spend, sorted and unique |
| Outputs | Up to 8 new outputs |
| Payload | Up to 1,024 bytes of public data |
| Operation | Optionally one staking operation |
| Witnesses | One signature per input, plus one or two for an operation |
The transaction ID is the SHA-384 of the body without the witnesses, so signatures cannot change it.
Authorizing an input
Each input needs one ML-DSA-65 signature over a message that binds the chain, the transaction, the input's position, and the amount and lock of the output it spends. The public key in the witness must reproduce the lock before the signature is even checked.
| Witness | Carries | Size |
|---|---|---|
| Inline | Public key and signature | 5,262 bytes |
| Referenced | Signature only; the key comes from the key registry | 3,310 bytes |
The first spend from an address reveals its public key, and the chain stores it in the key registry. Every later spend from that address can refer to it and save 1,952 bytes. Revealing the key does not weaken the address: ML-DSA is post-quantum.
Witnesses are most of a transaction. That is why a transaction is limited to 8 inputs:
| Payment | First spend | Later spends |
|---|---|---|
| 1 input, 2 outputs | 5,563 bytes | 3,611 bytes |
| 2 inputs, 2 outputs | 10,877 bytes | 6,973 bytes |
| 8 inputs, 2 outputs | 42,761 bytes | 27,145 bytes |
A stake and the other staking operations carry one more witness, the signature of the position's owner. On a first spend that leaves room for 7 inputs under the 46 KiB a transaction may have. The wallets then take fewer coins, or ask to compound first.
Mass and fees
Bytes alone do not price signature checks and state changes, so the chain measures mass:
mass = bytes + 2 × inputs + 3 × outputs + 4 × witnesses + 5 × operation bytes + 6 × payload bytesA transaction pays at least 1 atom per unit of mass. Miners fill blocks by fee per mass, so a higher rate is picked earlier when the mempool is busy. At the same rate, a node first takes the transactions submitted to it and those relayed by others once they have waited a cut interval longer, and picks at random within each group, so miners on different nodes rarely carry the same ones. A work block holds 96,000 units of mass.
Validity
A transaction names the last cut at which it may execute, at most 1,800 cuts after the first, about 75 minutes. After that height it can never execute. A wallet that lost the answer to a submission can therefore send the same transaction again without any risk of paying twice, and knows for certain when to give up.
An output created by one cut can be spent from the next cut on. Wallets spend only finalized outputs.
Payloads
A payload is opaque: nodes store it as bytes and never parse, show or run it. It is part of the transaction ID and public forever. It suits a reference, a short note or a commitment to data kept elsewhere. It is not file storage.
A payment to several recipients can pack one payload per recipient into the field. That layout is a wallet convention, TCC-0005; consensus sees only the size. Everyone can read every entry.
The wallets' messenger, TCC-0009, sends its chat frames as payloads of one-atom payments. From the second message of a chat on, the text inside is end-to-end encrypted.
Staking operations
A transaction may carry one native operation: register a validator, bond stake, unbond it, withdraw it, announce a validator's exit, rotate its key, change its endpoint, schedule a commission change, change a reward address, publish a heartbeat or submit evidence. The stake moves between the transaction's value and the staking state in the same cut that executes it.
Multisig
A spend lock can commit to a 2-of-3 or 3-of-5 set of ML-DSA-65 keys instead of one. Such an address looks like any other and is spent with the threshold of signatures.