PVM Host Calls

Host calls are the PVM's interface to the outside world, providing system-level functionality that programs cannot implement themselves. They enable access to JAM state, cryptographic operations, I/O, and control over execution flow.

Overview

Host calls are invoked when the PVM encounters a ecalli instruction. The host call number is specified in a register, and execution suspends while the host performs the requested operation.

Register Convention:

• Input: Host call parameters in registers r7-r12
• Output: Return value in register r7
• Gas: Deducted based on operation cost

Host Call Categories

Host calls are organized by invocation context:

ID Range	Category	Available In
0-13	General	All contexts (Is-Authorized, Refine, Accumulate)
14-19	Accumulate-only	Accumulate invocation
20-	Context-specific	Varies by invocation

General Host Calls (0-13)

Available in all three PVM invocation contexts.

0: Gas

Purpose: Query remaining gas

Parameters: None

Returns: Current gas remaining

Gas Cost: 10

Usage:

ecalli 0      # Host call 0
# r7 now contains remaining gas

---

1: Fetch

Purpose: Read environment data into memory

Parameters:

• r7: Output memory address
• r8: Offset into source data
• r9: Length to copy
• r10: Data type selector
• r11: Index 1 (context-dependent)
• r12: Index 2 (context-dependent)

Returns:

• r7: Total length of requested data (or NONE if unavailable)

Gas Cost: 10 + (bytes_copied / 8)

Data Types (r10):

Value	Data	Available In
0	Protocol constants	All
1	Entropy pool	Refine, Accumulate
2	Authorization trace	Is-Authorized, Refine
3	Extrinsic (any item)	Refine
4	Extrinsic (current item)	Refine
5	Import segment (any item)	Refine
6	Import segment (current item)	Refine
7	Work-package	Refine
8	Authorizer	Is-Authorized, Refine
9	Authorization	Is-Authorized, Refine
10	Work-package context	Refine
11	All work-items (summary)	Refine
12	Specific work-item (summary)	Refine
13	Work-item payload	Refine
14	Operand tuples	Accumulate
15	Specific operand tuple	Accumulate
16	Deferred transfers	Accumulate
17	Specific deferred transfer	Accumulate

Protocol Constants (Type 0):

Returns concatenated encoding of all protocol constants:

B_I, B_L, B_S, C, D, E, G_A, G_I, G_R, G_T, 
H, I, J, K, L, N, O, P, Q, R, T, U, V,
W_A, W_B, W_C, W_E, W_M, W_P, W_R, W_T, W_X, Y

Example:

# Fetch protocol constants
r7 = buffer_address
r8 = 0  # offset
r9 = 200  # max length
r10 = 0  # constants
ecalli 1
# r7 contains actual data length

---

2: Lookup

Purpose: Read service account data or preimage

Parameters:

• r7: Service ID (or 2^64-1 for self, or preimage key)
• r8: Preimage hash address (32 bytes)
• r9: Output buffer address
• r10: Output buffer size

Returns:

• r7: Actual data length (or NONE if not found)

Gas Cost: 10 + (bytes_read / 8)

---

3: Write

Purpose: Write data to service storage

Parameters:

• r7: Storage key address (32 bytes)
• r8: Data address
• r9: Data length

Returns:

• r7: OK on success, HUH if wrong context

Gas Cost: 1000 + (data_length × 2)

Only Available: Accumulate invocation

---

4: Read

Purpose: Read data from service storage

Parameters:

• r7: Storage key address (32 bytes)
• r8: Output buffer address
• r9: Output buffer size

Returns:

• r7: Actual data length (or NONE if key doesn't exist)

Gas Cost: 1000 + (bytes_read / 4)

---

5: Info

Purpose: Get service account metadata

Parameters:

• r7: Service ID (or 2^64-1 for self)

Returns (in registers):

• r7: Balance (low 32 bits)
• r8: Balance (high 32 bits)
• r9: Gas (low 32 bits)
• r10: Gas (high 32 bits)
• r11: Minimum balance (low 32 bits)
• r12: Minimum balance (high 32 bits)

Gas Cost: 100

---

6-13: Reserved / Crypto

Additional general host calls for cryptographic operations, historical lookups, and other system functions. See Gray Paper Appendix A for complete definitions.

Accumulate-Specific Host Calls (14-19)

Available only in Accumulate invocation context.

14: Bless

Purpose: Update privilege assignments (χ - Chi)

Parameters:

• r7: New χ_m (managing service)
• r8: Address of χ_a array (authorizations per core)
• r9: New χ_v (validator assignments service)
• r10: Address of χ_z records
• r11: Count of χ_z records

Returns:

• r7: OK on success, HUH if not privileged, WHO if invalid params

Gas Cost: 10

Only Available: When service has χ_m privilege

Purpose: The Bless host call allows the privileged managing service to update:

• χ_m: Which service manages privileges
• χ_a: Authorization requirements per core
• χ_v: Which service assigns validators
• χ_z: Gas assignments per service

---

15: Assign

Purpose: Update validator assignments (ι - Iota)

Parameters:

• r7: Address of validator data array
• r8: Count of validators (must be VALIDATOR_COUNT = 1023)

Returns:

• r7: OK on success, HUH if not privileged, WHO if invalid count

Gas Cost: 10 + (1023 × 100)

Only Available: When service has χ_v privilege

---

16: Designate

Purpose: Update core authorization queue

Parameters:

• r7: Core index
• r8: Address of authorizer hash array
• r9: Count of authorizers (max MAX_AUTH_QUEUE_ITEMS = 8)

Returns:

• r7: OK on success, HUH if not privileged, WHO if invalid params

Gas Cost: 10

Only Available: When service has χ_a[core] privilege

---

17: Checkpoint

Purpose: Create execution checkpoint for exception handling

Parameters: None

Returns: None (creates checkpoint in context)

Gas Cost: 1000

Purpose: Saves current state so that exceptions can revert to this point, similar to database transactions.

---

18: New

Purpose: Create a new service account

Parameters:

• r7: Initial balance (low 32 bits)
• r8: Initial balance (high 32 bits)
• r9: Code hash address (32 bytes)
• r10: Min-gas (low 32 bits)
• r11: Min-gas (high 32 bits)
• r12: Preimage length

Returns:

• r7: New service ID (or error code)

Gas Cost: 10,000 + cost based on initial allocations

---

19: Upgrade

Purpose: Update service code hash

Parameters:

• r7: Service ID (or 2^64-1 for self)
• r8: New code hash address (32 bytes)

Returns:

• r7: OK on success, error code otherwise

Gas Cost: 1000

---

Refine-Specific Host Calls

20: Historical Lookup

Purpose: Read historical state from past blocks

Parameters:

• r7: Block number offset
• r8: Storage key address
• r9: Output buffer address
• r10: Output buffer size

Returns:

• r7: Data length (or NONE if not found)

Gas Cost: Variable based on age and size

---

21: Invoke (Inner PVM)

Purpose: Execute child PVM instance

Parameters:

• r7: Code hash address
• r8: Input data address
• r9: Input data length
• r10: Gas limit for child
• r11: Output buffer address
• r12: Output buffer size

Returns:

• r7: Child exit status
• r8: Remaining gas
• r9: Output length

Gas Cost: Consumed by child + overhead

---

22: Export

Purpose: Add segment to export data

Parameters:

• r7: Segment data address
• r8: Segment size (must be SEGMENT_SIZE = 4096)

Returns:

• r7: Segment index

Gas Cost: 1000

---

Host Call Return Values

Standard return codes in register r7:

Constant	Value	Meaning
OK	0	Operation successful
NONE	2^64-1	Item not found
WHO	2^64-2	Invalid identifier
WHAT	2^64-3	Unknown host call
HUH	2^64-4	Insufficient privilege
LOW	2^64-5	Insufficient balance/gas
FULL	2^64-6	Buffer too small

Files

Core:

• execution/host_call.py - Main execution loop
• execution/invocations/protocol.py - Dispatch protocol

Host Call Functions:

• invocations/functions/general_fns.py - Calls 0-13
• invocations/functions/accumulate_fns.py - Calls 14-19
• invocations/functions/refine_fns.py - Calls 20-22

References

• Gray Paper: Appendix A - Virtual Machine Invocations
• Implementation: tessera/jam/execution/invocations/functions/

---

Next: Instructions | Recompilation