FIP: Snap Compute — Turing-Complete Programmable Frames

Overview

Farcaster Frames and Snaps (the interactive embed card format defined at @farcaster/snap) are currently server-driven: every interaction requires an HTTP round-trip to an external server that holds all application logic. This creates centralization risk, latency, availability dependency, and prevents composability between snaps. If a snap server goes offline, the snap is dead.

This FIP extends the Snap 1.0 format with Snap Compute — a Turing-complete client-side execution layer that allows snaps to embed deterministic programs alongside their UI definitions. Programs execute locally in an isolated sandbox, can read protocol state (casts, follows, reactions, user data) via a syscall interface, and produce UI updates without server round-trips. Server-driven snaps remain fully supported; Snap Compute is an opt-in extension.

The compute model uses a stack-based bytecode VM (SnapVM) with a gas metering system to bound execution. Programs are compiled from a high-level expression language (SnapScript) and stored as compact bytecode in the snap response. The VM is pure and deterministic — given the same inputs and protocol state, it always produces the same output.

1. Motivation

1.1 Current Limitations

The server-driven Snap 1.0 model has fundamental constraints:

1.2 Design Goals

1. Backward compatible: Snap 1.0 responses remain valid. Compute is opt-in.
2. Deterministic: Given the same inputs and protocol state snapshot, the VM always produces identical output. This enables client-side caching, p2p snap state sharing, and reproducible debugging.
3. Bounded: Gas metering prevents infinite loops. Memory limits prevent OOM. Programs cannot perform I/O beyond reading protocol state.
4. Compact: Bytecode is small enough to embed inline in a cast or snap response without bloating the protocol.
5. Composable: Programs can invoke other snaps' exported functions, enabling a library ecosystem.

2. Snap Response Extension

The SnapResponse envelope gains an optional compute field:

{
  "version": "1.1",
  "theme": { "accent": "purple" },
  "compute": {
    "bytecode": "<base64url-encoded SnapVM bytecode>",
    "entrypoint": "main",
    "gas_limit": 1000000,
    "capabilities": ["shared_state", "user_state", "cast", "react"],
    "exports": ["score", "leaderboard"],
    "state_schema": {
      "counter": "i64",
      "name": "string"
    }
  },
  "ui": { ... }
}

Capabilities declare what side effects the snap may produce. The client prompts the user to approve these before the first interaction. Valid capabilities:

When compute is present, the client:

1. Decodes and validates the bytecode
2. On initial load, calls entrypoint(action: "get") — read-only, no side effects
3. On first interaction requiring side effects, prompts the user to approve the declared capabilities
4. On button press, calls entrypoint(action: "post", inputs, button_index) locally
5. The VM executes and produces an output log: UI spec, state writes, and embedded protocol messages
6. The client submits a SnapExecutionBundle containing all outputs, the execution context for replay, and the user's capability approval (see Section 6.2)
7. The node verifies the bundle by re-executing the VM and comparing outputs

If compute is absent, the snap behaves exactly as Snap 1.0 (server-driven).

3. SnapVM Specification

3.1 Architecture

SnapVM is a stack-based virtual machine with:

• Operand stack: dynamically typed values (i64, f64, string, bytes, bool, array, map, null)
• Call stack: function frames with local variables (max depth: 64)
• Gas counter: decremented per instruction, execution halts at zero

Note: the VM does not include linear memory (addressable byte arrays). All data lives on the operand stack and in local variables. This keeps the VM simple and auditable. Linear memory may be added in a future version if use cases demand it.

3.2 Value Types

enum SnapValueType {
  SNAP_VALUE_TYPE_NULL = 0;
  SNAP_VALUE_TYPE_BOOL = 1;
  SNAP_VALUE_TYPE_I64 = 2;
  SNAP_VALUE_TYPE_F64 = 3;
  SNAP_VALUE_TYPE_STRING = 4;
  SNAP_VALUE_TYPE_BYTES = 5;
  SNAP_VALUE_TYPE_ARRAY = 6;
  SNAP_VALUE_TYPE_MAP = 7;
}

Strings are UTF-8, max 64 KiB. Arrays and maps are reference-counted, max 10,000 elements. All values are immutable; operations produce new values.

3.3 Instruction Set

Instructions are encoded as a 1-byte opcode followed by optional immediate operands.

Stack operations (gas: 1):

Arithmetic (gas: 1):

Comparison (gas: 1):

Control flow (gas: 1):

Local variables (gas: 1):

Collections (gas: 2):

Type conversion (gas: 1):

String operations (gas: 2):

Syscalls (gas: 100–10,000, see Section 4):

3.4 Bytecode Format

SnapVM Bytecode v1

Header (16 bytes):
  magic:     [0x53, 0x4E, 0x41, 0x50]  ("SNAP")
  version:   u16 (1)
  flags:     u16 (reserved, 0)
  const_offset: u32 (byte offset to constant pool)
  func_offset:  u32 (byte offset to function table)

Constant Pool:
  count:    u32
  entries:  [ConstEntry...]
    type:   u8 (0=string, 1=bytes)
    len:    u32
    data:   [u8; len]

Function Table:
  count:    u32
  entries:  [FuncEntry...]
    name_idx:   u32 (index into constant pool)
    arity:      u16
    locals:     u16
    code_len:   u32
    code:       [u8; code_len]

Maximum bytecode size: 256 KiB (after base64url decoding).

4. Syscall Interface

Syscalls are the only way the VM interacts with the outside world. They provide protocol state reads, persistent local and shared state, UI output, external HTTP requests, cross-snap calls, and cryptographic primitives.

4.1 Protocol State Reads

4.2 User State

Per-user state is scoped to (snap_cast_hash, fid) — each user has their own key-value store per snap instance. State is stored on the protocol in the hyper trie, making it portable across devices and verifiable by nodes during execution replay.

User state writes do not execute immediately — they are appended to the execution output log and committed atomically as part of the SnapExecutionBundle after node verification (see Section 6.2).

Storage location:

RootPrefix::SnapUserState (56)
Key: [56][snap_cast_hash:20][fid:8][key_hash:8] -> [value_bytes]

Maximum 100 keys, 4 KiB per value, 256 KiB total per user per snap instance. Only the owning FID can read or write their own entries.

4.3 UI Output

4.4 Message Emission

The VM can emit protocol messages (casts, reactions, links, user data) as side effects. Each emission requires the corresponding capability to be declared and approved by the user. Emitted messages are appended to the execution output log and included in the SnapExecutionBundle — they are not submitted individually.

Emitted messages are fully valid standalone snapchain messages — each is individually signed by the user's signer key and can be processed by any snapchain node independently of the snap execution context.

4.5 External Resources

Snaps can reference external images and media in their UI output. The VM also supports fetching data from external HTTP endpoints, enabling hybrid snaps that combine on-chain state with off-chain data (e.g., price feeds, weather, game servers).

Image and media loading is handled by the client, not the VM. The ui.render spec can include image elements with HTTPS URLs — the client fetches and renders these as it does today in Snap 1.0. No syscall is needed for this; it is a property of the UI layer.

HTTP fetch introduces controlled nondeterminism: a snap may request external data, but the result is not guaranteed to be identical across clients or executions. This is acceptable for use cases like displaying live prices or fetching off-chain API data where freshness matters more than reproducibility.

Restrictions:

• Only HTTPS URLs are permitted (no HTTP, no local/private IPs)
• The client may cache responses for up to 60 seconds to reduce redundant fetches
• The client may refuse requests to URLs on a blocklist (e.g., known tracking domains)
• Max 5 HTTP syscalls per execution (prevents abuse)
• HTTP syscalls are non-deterministic: the snap author must handle the possibility that different clients see different responses, and design UI accordingly
• A snap that uses http.get or http.post is marked as nondeterministic in its metadata — clients may display a badge indicating this snap fetches external data

4.6 Shared State

Shared state enables multiple users to read and write to a common data store scoped to a snap instance, enabling collaborative experiences like polls, leaderboards, multiplayer games, and counters. Requires the shared_state capability.

Like user state writes, shared state writes are appended to the execution output log and committed atomically via the SnapExecutionBundle after node verification.

CRDT semantics: Last-write-wins per (snap_cast_hash, key, fid). Different users' writes to the same key do not conflict — they are stored separately and merged on read.

Storage location:

RootPrefix::SnapSharedState (55)
Key: [55][snap_cast_hash:20][key_hash:8][fid:8] -> [value_bytes]

Limits:

Example — Poll snap:

export fn main(action: string, inputs: map, button_index: i64) {
  if action == "post" {
    let choice = inputs["choice"]
    @shared_set("vote", choice)
    @emit_cast("I voted " + choice + " in the poll!")
  }

  let all_votes = @shared_get_all("vote")
  var counts = {}
  for fid in @map_keys(all_votes) {
    let v = all_votes[fid]
    counts[v] = (counts[v] ?? 0) + 1
  }

  let total = @shared_count("vote")
  let my_vote = @shared_get_by_fid("vote", @self_fid())

  @render({
    root: "main",
    elements: {
      main: { type: "stack", props: { direction: "vertical", gap: "md" }, children: ["title", "chart", "toggle", "btn"] },
      title: { type: "text", props: { content: "Poll: Favorite color? (" + to_str(total) + " votes)" } },
      chart: { type: "bar_chart", props: {
        bars: [
          { label: "Red", value: counts["red"] ?? 0 },
          { label: "Blue", value: counts["blue"] ?? 0 },
          { label: "Green", value: counts["green"] ?? 0 },
        ]
      }},
      toggle: { type: "toggle_group", props: { name: "choice", options: ["red", "blue", "green"], defaultValue: my_vote }},
      btn: { type: "button", props: { label: my_vote != null ? "Change Vote" : "Vote" }, on: { press: { type: "submit" } } },
    },
  })
}

4.7 Crypto

5. SnapScript Language

SnapScript is a high-level expression language that compiles to SnapVM bytecode. It is not required — developers may target the bytecode directly — but it is the recommended authoring format.

5.1 Syntax Overview

// Types: i64, f64, string, bool, bytes, array, map, null
// Variables are immutable by default
let name = "world"
var counter = 0  // mutable

// Functions
fn greet(name: string) -> string {
  "Hello, " + name + "!"
}

// Control flow
if counter > 10 {
  "big"
} else if counter > 0 {
  "small"
} else {
  "zero"
}

// Pattern matching
match action {
  "get" => render_home(),
  "post" => handle_submit(inputs),
  _ => render_error("unknown action"),
}

// Loops
for item in items {
  total = total + item.value
}

while counter < 100 {
  counter = counter + 1
}

// Protocol access
let fid = @self_fid()
let user = @get_user_data(fid, "display")
let friends = @get_following(fid, 50)

// State
@state_set("visits", @state_get("visits") ?? 0 + 1)

// UI output (must be called once)
@render({
  root: "main",
  elements: {
    main: { type: "stack", props: { direction: "vertical" }, children: ["title", "btn"] },
    title: { type: "text", props: { content: greet(user ?? "anon") } },
    btn: { type: "button", props: { label: "Click me" }, on: { press: { type: "submit" } } },
  },
})

5.2 Language Details

Variables: let declares immutable bindings. var declares mutable bindings. Assigning to a let variable is a compile error.

Null coalescing: The ?? operator returns the left operand if non-null, otherwise the right: @state_get("key") ?? "default". Compiles to a DUP -> PUSH_NULL -> NEQ -> JMP_IF -> POP -> <right> sequence.

Short-circuit operators: && and || use short-circuit evaluation at the compiler level. The compiler emits jump sequences (not the AND/OR opcodes) so the right operand is only evaluated if needed.

Field access: Dot syntax (user.name) desugars to MAP_GET — it is semantically identical to user["name"].

Index access: arr[0] uses ARRAY_GET for numeric literal indices. map[key] uses MAP_GET for all other index expressions (string literals, variables, expressions).

For loops: for x in items { ... } iterates over arrays only. Compiles to an index-based while loop internally. To iterate map keys, use for k in @map_keys(m) { ... }.

Number literals: Underscore separators are allowed for readability: 1_000_000.

Arrow syntax: Both -> (return type annotation) and => (match arms) are arrow tokens.

5.3 Built-in Functions

Syscalls are accessed via @ prefix: @self_fid(), @get_user_data(fid, type), @render(spec), @state_get(key), @state_set(key, value), @sha256(data), etc.

The following builtins compile to native opcodes rather than syscalls for efficiency:

• @map_keys(m) — MAP_KEYS opcode
• @to_str(v) — TO_STR opcode (also available as to_str(v))
• @to_i64(v) — TO_I64 opcode (also available as to_i64(v))
• @to_f64(v) — TO_F64 opcode (also available as to_f64(v))

5.4 Entry Point Convention

// The main function receives the snap action context
export fn main(action: string, inputs: map, button_index: i64) {
  match action {
    "get" => render_home(),
    "post" => handle_interaction(inputs, button_index),
  }
}

// Exported functions are callable by other snaps via snap.call
export fn score(fid: i64) -> i64 {
  // compute and return a score
}

6. Execution Model

6.1 Lifecycle

Cast created with snap URL
        |
        v
Client fetches snap URL (GET)
        |
        v
Response has `compute` field?
    No ──> Snap 1.0 (server-driven)
    Yes ──> Snap Compute:
        |
        v
Decode bytecode, validate header
        |
        v
Client prompts user to approve declared capabilities
(only on first interaction; approval is cached per snap)
        |
        v
Call entrypoint("get", {}, 0) — read-only, no side effects
        |
        v
VM executes, calls ui.render(spec)
        |
        v
Client renders UI
        |
        v
User interacts (fills inputs, presses button)
        |
        v
Call entrypoint("post", inputs, button_index)
        |
        v
VM executes, producing:
  - UI spec (via ui.render)
  - State writes (user + shared)
  - Embedded protocol messages (casts, reactions, links)
        |
        v
Client renders updated UI immediately (optimistic)
        |
        v
Client constructs SnapExecutionBundle:
  - Execution context (action, inputs, button_index)
  - Nonce (random 32 bytes, unique per execution)
  - Timestamp (Farcaster time)
  - Capability approval signature
  - All state writes (user + shared)
  - All embedded messages (individually signed)
  - Outer signature over entire bundle
        |
        v
Submit bundle to the node
        |
        v
Node validates (see Section 6.2)
        |
        (repeat)

6.2 Verified Execution and the SnapExecutionBundle

Every interaction that produces side effects (state writes, message emissions) is submitted as a SnapExecutionBundle. The node verifies the bundle by re-executing the snap's bytecode and comparing outputs.

SnapExecutionBundle structure:

message SnapExecutionBundle {
  // Identity
  bytes snap_cast_hash = 1;         // Cast containing the snap embed (instance ID)
  uint64 fid = 2;                   // User's FID
  uint32 timestamp = 3;             // Farcaster time (for LWW ordering)
  bytes nonce = 4;                  // Random 32 bytes (unique per execution, prevents replay)

  // Capability approval (signed once, reused across executions)
  SnapCapabilityApproval approval = 5;

  // Execution replay context
  string action = 6;                // "get" or "post"
  map<string, bytes> inputs = 7;    // Input field values
  uint32 button_index = 8;

  // VM outputs
  repeated SnapStateWrite user_state_writes = 9;
  repeated SnapStateWrite shared_state_writes = 10;
  repeated bytes embedded_messages = 11;  // Standalone-valid signed Message protos

  // Authenticity
  bytes signer = 12;                // Ed25519 public key
  bytes signature = 13;             // Signs all fields above including nonce
}

message SnapCapabilityApproval {
  bytes snap_cast_hash = 1;
  uint64 fid = 2;
  repeated string capabilities = 3; // ["shared_state", "cast", "react", ...]
  bytes signature = 4;              // User signs (snap_cast_hash, fid, capabilities)
}

message SnapStateWrite {
  string key = 1;
  bytes value = 2;                  // JSON-encoded, max 1 KiB (shared) or 4 KiB (user)
}

Node validation procedure:

1. Nonce uniqueness: Reject if this nonce has been seen before
2. Signature verification: Outer signature must verify against signer for fid
3. Signer validity: signer must be an active registered signer for fid
4. Capability approval: Verify the approval signature matches (snap_cast_hash, fid, capabilities)
5. Capability coverage: Every output must fall within approved capabilities (state writes require user_state/shared_state, embedded casts require cast, etc.)
6. Embedded message validity: Each embedded message must have a valid standalone signature and be a valid snapchain message
7. Re-execution: Fetch the snap's bytecode from the cast at snap_cast_hash. Load current user state and shared state from the hyper trie. Execute the VM with (action, inputs, button_index). Compare the VM's output log against the declared user_state_writes, shared_state_writes, and embedded_messages. If they do not match exactly, reject the bundle.
8. Limits: Enforce per-key size limits, per-instance total limits, daily write rate limits
9. Commit: Write user state to RootPrefix::SnapUserState (56), shared state to RootPrefix::SnapSharedState (55). Forward embedded messages to snapchain for independent processing. Store nonce to prevent replay.

Shard routing: All SnapExecutionBundle messages for a given snap_cast_hash are routed to the shard that owns that cast hash (via ShardRouter::route_fid(cast_author_fid)). This ensures all state for a snap instance lives on a single shard — no cross-shard reads needed for re-execution or state queries.

Nondeterministic snaps: Snaps that use http.get/http.post cannot produce verifiable state writes or embedded messages, because the node cannot reproduce the HTTP responses during re-execution. Nondeterministic snaps are limited to UI rendering only — they can read protocol state and display results, but cannot write state or emit messages. The capabilities field must be empty for snaps that use HTTP syscalls.

Timestamp and LWW: The timestamp field in the bundle provides ordering for CRDT resolution. For shared state: LWW per (snap_cast_hash, key, fid, timestamp). For user state: LWW per (snap_cast_hash, fid, key, timestamp). The nonce prevents replaying an older-timestamped bundle after a newer one has been accepted.

6.3 Determinism Model

The SnapVM has two execution modes:

Deterministic mode (default): Given the same inputs and protocol state, the VM always produces identical output. This is the case for snaps that only use protocol state reads, local state, shared state, and crypto syscalls.

• f64 operations use IEEE 754 with round-to-nearest-even. NaN is canonicalized.
• farcaster.timestamp returns the block timestamp, not wall clock.
• No random() syscall. Deterministic randomness can be derived from crypto.sha256(cast_hash ++ fid ++ nonce).
• Map iteration order is insertion order, not hash order.
• Shared state reads are consistent at a given block height — all peers at the same height see the same shared state.

Nondeterministic mode (opt-in): Snaps that use http.get or http.post syscalls are nondeterministic — different clients may see different responses from external servers. Clients display a visual indicator for nondeterministic snaps. Nondeterministic snaps cannot be used as snap.call targets (composability requires determinism).

6.4 Gas Limits

If gas is exhausted, execution halts and the client displays an error state. The snap author may specify a custom gas_limit up to the max.

6.5 Memory Limits

7. Protobuf Additions

// snap_compute.proto

message SnapComputeEnvelope {
  bytes bytecode = 1;                       // SnapVM bytecode
  string entrypoint = 2;                    // Function name (default "main")
  uint64 gas_limit = 3;                     // Max gas per execution
  repeated string capabilities = 4;         // Declared capabilities
  repeated string exports = 5;              // Exported function names
  map<string, string> state_schema = 6;     // key -> type name
}

message SnapRegisterBody {
  string url = 1;                           // Snap URL (canonical identifier)
  bytes bytecode_hash = 2;                  // SHA-256 of bytecode
  SnapComputeEnvelope compute = 3;          // Full compute envelope
  uint64 fid = 4;                           // Author FID
}

message SnapExecutionBundle {
  bytes snap_cast_hash = 1;                 // Cast containing the snap embed
  uint64 fid = 2;                           // User's FID
  uint32 timestamp = 3;                     // Farcaster time (for LWW)
  bytes nonce = 4;                          // Random 32 bytes (unique per execution)
  SnapCapabilityApproval approval = 5;      // Pre-signed capability grant
  string action = 6;                        // "get" or "post"
  map<string, bytes> inputs = 7;            // Input field values
  uint32 button_index = 8;
  repeated SnapStateWrite user_state_writes = 9;
  repeated SnapStateWrite shared_state_writes = 10;
  repeated bytes embedded_messages = 11;    // Standalone-valid signed Messages
  bytes signer = 12;                        // Ed25519 public key
  bytes signature = 13;                     // Signs all fields including nonce
}

message SnapCapabilityApproval {
  bytes snap_cast_hash = 1;
  uint64 fid = 2;
  repeated string capabilities = 3;
  bytes signature = 4;                      // User signs (snap_cast_hash, fid, capabilities)
}

message SnapStateWrite {
  string key = 1;                           // State key
  bytes value = 2;                          // JSON-encoded value
}

enum HyperMessageType {
  // ... existing values ...
  HYPER_MESSAGE_TYPE_SNAP_REGISTER = 150;
  HYPER_MESSAGE_TYPE_SNAP_UPDATE = 151;
  HYPER_MESSAGE_TYPE_SNAP_EXECUTION = 152;
}

8. Security Model

8.1 Sandboxing and Verified Execution

The SnapVM runs on the client but its outputs are verified by the node through re-execution:

• No filesystem access
• Limited network access: only via http.get/http.post syscalls, HTTPS only, capped at 5 requests per execution, 64 KiB response limit, 5s timeout. Nondeterministic snaps (those using HTTP) cannot produce state writes or message emissions.
• No code generation (no eval, no dynamic bytecode loading except via snap.call)
• Verified outputs: All state writes and message emissions are verified by node re-execution. The VM is not trusted — the node independently runs the same bytecode and confirms the outputs match.
• Capability-gated: Side effects require pre-approved capabilities. The user signs a capability approval bound to the specific snap instance before any writes can occur.
• Nonce-bound: Each execution is bound to a unique random nonce. State writes are only valid within the context of a specific execution bundle — they cannot be extracted, replayed, or forged independently.
• User state isolation: Each user's state is scoped to (snap_cast_hash, fid) and only readable by that user's VM executions. Other users cannot access it.

8.2 Resource Exhaustion

Gas metering and memory limits prevent denial-of-service:

• Infinite loops consume gas and halt
• Memory allocation beyond limits traps
• Stack overflow (>1024 operands or >64 frames) traps
• String/array operations on oversized values trap

8.3 Cross-Snap Isolation

snap.call fetches and executes another snap's bytecode in a fresh VM context:

• The callee cannot access the caller's state or locals
• Gas is deducted from the caller's budget (nested calls share the caller's remaining gas)
• Call depth is limited to 4 to prevent unbounded recursion
• The callee can only access its own persistent state, not the caller's

8.4 Bytecode Verification

Clients validate bytecode before execution:

1. Magic bytes match "SNAP"
2. Version is supported
3. All jump targets are within function bounds
4. No overlapping function code ranges
5. Constant pool indices are in bounds
6. Bytecode size is within limits

Invalid bytecode is rejected and the snap falls back to static UI rendering (or server-driven mode if a submit action target is present).

9. Open Questions

1. Bytecode storage: Should bytecode be stored inline in the snap response (current proposal), pinned to IPFS/Arweave, or stored in the hyper trie via SNAP_REGISTER? Inline is simplest but bloats responses. Content-addressed storage enables deduplication and caching.

2. Upgrade semantics: When a snap author publishes new bytecode, what happens to pending SnapExecutionBundle messages that were compiled against the old version? Should nodes pin the bytecode version at the time of execution, or always use the latest?

3. Gas pricing: The gas costs in this proposal are placeholder values. Production gas costs should be benchmarked against real hardware to ensure consistent execution time across devices — both on client and on node (which must re-execute for verification).

4. Node re-execution cost: Every SnapExecutionBundle requires the node to re-execute the VM. Should nodes charge a protocol fee for verification, or is the gas limit sufficient to bound computational cost?

5. State divergence window: Between client execution and node verification, shared state may change (other users voted). If re-execution produces different outputs, the bundle is rejected. Should clients retry automatically, or should there be a state snapshot mechanism?

6. Compiler trust: If SnapScript is the primary authoring format, users trust the compiler to produce correct bytecode. Should compiled bytecode include a proof of compilation, or is source-code publication sufficient for auditability?

7. Cross-snap versioning: When snap A calls snap B's exported function, and snap B updates its bytecode, should snap A get the new version or the version it was compiled against?

8. Privacy via ZK: User state is currently protocol-visible (Option C). A future version could use ZK proofs to verify execution without revealing user state values. What proof system would be appropriate, and what is the performance budget?

9. Capability revocation: Once a user approves capabilities for a snap, can they revoke? Should the capability approval have an expiry timestamp?

10. Embedded message ordering: When a bundle contains multiple embedded messages (e.g., a cast and a reaction), does their ordering within the bundle matter for snapchain processing? Should they be processed atomically or independently?

10. New Proto Additions Summary

12. Parameter Summary