AVM state and execution
What a contract call receives, what it returns, and how state is expected to be carried between calls.
Experimental or beta Verified 2026-08-31
Behavior exists in beta or unreleased code. Do not build production dependencies on it.
- Page ID
-
protocol/avm/state-and-execution - Normative authority
- Atomicals reference implementation
- Networks
- none
- Documentation version
- 2026.08
- Audience
- developer
- Owner
- bitcoin-universe-docs
- Sources
-
- Atomicals Virtual Machine interpreter
at
c185e6216a3e - Atomicals Virtual Machine interpreter
at
c185e6216a3e
- Atomicals Virtual Machine interpreter
at
- Known limitations
-
- This page describes the upstream beta interpreter's model. No Universe deployment runs it, so none of it is verified against Universe infrastructure.
Esta página aún no está disponible en tu idioma.
The execution model
Section titled “The execution model”The interpreter is a sandbox invoked per contract. Upstream describes the entry point as a library function that verifies a script for the AVM, with the caller supplying state inputs, scripts, and current block information. On success, updated state variables are returned as CBOR encoded structures.
Three consequences follow:
- The caller owns state. The interpreter does not persist anything. Whatever calls it must store and supply state.
- The boundary is CBOR. Inputs and outputs cross the boundary as encoded structures, not as language objects.
- Execution is per contract. There is no shared global machine.
What a call needs
Section titled “What a call needs”| Input | Purpose |
|---|---|
| The contract script | What to execute |
| The unlocking script | The caller’s side of the call |
| State inputs | The contract’s stored key and value data |
| Token tables | Fungible balances and non-fungible objects the contract holds |
| Block information | So the script can read chain context |
| Authorisation signatures | So the custom authorisation opcode can validate the caller |
What a call returns
Section titled “What a call returns”- Success or failure.
- Updated state, CBOR encoded.
- Updated token tables, including any deposits or withdrawals marked during execution.
- Any outputs marked for withdrawal.
State hashes
Section titled “State hashes”A state hash lets an independent party check that a claimed post-execution state matches what an honest execution would produce. Without one, a caller must re-execute to verify.
Any integration that stores AVM state must record the hash alongside it, and must record which interpreter revision produced it.
Deposits and withdrawals
Section titled “Deposits and withdrawals”Separate opcodes add fungible balance and non-fungible objects to a contract’s internal tables, and mark outputs for withdrawal. The mechanics differ from ordinary Atomicals transfers, because value moves into and out of a contract’s internal accounting rather than directly between outputs.
Nothing here is exposed by any Universe service. See status and limitations.
Virtual assets
Section titled “Virtual assets”The whitepaper describes virtual unspent output concepts. Those are architectural concepts in a design document. They are not implemented behavior on the basis of appearing there.