Versions

Every Umbra instruction carries a version, and every account records its layout version. A program refuses an instruction whose version it does not serve, so a change of format never silently means something else.

InstructionsCopy Anchor Link

Every instruction starts with the same envelope: a one-byte tag that names the instruction, a two-byte version, then the payload. The chart below shows how a program handles one.

flowchart LR
I["Instruction"] --> K{"Tag and version"}
K -->|"both served"| H["Handler runs"]
K -->|"known tag, other version"| V["Refused: unsupported version"]
K -->|"unknown tag"| U["Refused: unknown instruction"]

A program matches the tag and the version as a pair. Only a pair it serves reaches a handler, and the handler then requires the payload to be exactly its expected length. A known tag at any other version is refused with an error of its own, distinct from an unknown tag, so a client can tell that it is out of date rather than wrong. When an instruction's payload or account list changes, its version goes up and the old version stops being served. The programs built for the mainnet addresses start every instruction at version 0, the value instruction included.

Every version an instruction has had at a program's address, current and retired, is recorded in the repository's ABI ledger. The indexer's decoder is built from that ledger, so it can still read transactions made under a version the program no longer accepts. A program at a new address starts a new ledger, and the indexer archives only the programs at the mainnet addresses.

AccountsCopy Anchor Link

Every account starts with the same five-byte header, which records the account's status, its layout version and the bump of its program-derived address. A reader checks the layout version before it trusts any of the account's other fields. A program reading another program's account does the same: the shielded pool, for instance, refuses a guardian cluster account whose version is not the one it was built against. When an account's layout changes, its version goes up, so a reader built for the old layout refuses the new one instead of misreading it. Every account of the programs built for the mainnet addresses starts at layout version 0.

Generated, not hand-writtenCopy Anchor Link

The instruction tables on this site are read at build time from the manifests the repository generates from each program's source, never typed by hand. The shielded pool's is in the reference below. Every other program's is in the reference section of on-chain programs.

ReferenceCopy Anchor Link

RelatedCopy Anchor Link