Paxeer XDocs

Deterministic Programs

Deploy and call deterministic Paxeer X programs with scoped capabilities, metered execution, governed upgrades and verifiable outputs.

One execution surface, explicit authority

Programs extend the LayerX kernel domain of Paxeer X with application logic. A program executes a validated WebAssembly artifact under the identity, capability grants, access declarations, and resource ceilings of its invoking activity. Artifact validation rejects floating-point types and instructions and enforces structural limits before interpreter execution. The same admitted activity and state produce replayable results.

Programs dispatch through kernel module 9. They do not become economic modules and never write balances directly. All monetary effects compile to authenticated 402LXP transfer sets applied by the kernel. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Paxeer uses EVM chain ID 125. A receipt is final when validators commit its covering block.

Application building blocks

Capability Application behavior
Namespaced storage Read, write, delete, and scan bounded program state; distinguish principal-scoped state from explicitly granted shared state.
Program composition Invoke another program with an explicit callee grant, narrowed capabilities, bounded depth, and response capacity.
Native value accounts Derive and register program-owned accounts for native Assets; stage authorized payments, escrow releases, swaps, and vault movements.
Receipt evidence Consume explicitly granted receipt digests and expose receipt-verified deployment, state, and balance information.
Deterministic data and arithmetic Read admitted context, verify signatures, hash bytes, perform 256-bit integer arithmetic, and consume oracle and web evidence through versioned host imports.
Bounded computation Run the deterministic interpreter, lease isolated sandbox execution, and adjudicate disputed market steps.

Deploy, call, upgrade, and retire

Deploy an artifact and interface

A deployment binds a 32-byte program ID to its WASM artifact, declared SHA-256 code hash, guest ABI version, and upgrade policy. The immutable policy has no upgrade authority. The authority policy names the principal permitted to upgrade. An optional canonical interface describes entry selectors, input and output bounds, and required capability descriptors. Artifact identity is the program ID and code hash together.

Deployment creates version 1 and emits deployment evidence. Retain and verify that receipt before treating a registry entry as proof of deployment. Snapshots retain artifacts so restored state resolves the same code.

Execute a bounded call

A CALL names the program, guest ABI, entrypoint, canonical calldata, capability grants, access declarations, response capacity, and seven resource-budget dimensions. The runtime verifies the active program record and opens the matching artifact before running guest code. Entrypoint names use letters, digits, underscores, and periods.

The Programs precompile exposes call, callWithReceipts and simulateCall, as declared in precompiles/layerxprograms/LayerXPrograms.sol. Simulation uses the same CALL payload encoding and runs against a disposable state branch. Its result includes the terminal kind, result code and canonical response frame. Simulation previews execution against the selected state; verify the submitted transaction and its committed receipt before treating an outcome as settled.

Upgrade with an explicit policy

An upgrade must match the recorded authority and current code hash, supply a new artifact and hash, and follow admitted ABI transitions. Optional hook bytes and interface replacement or removal accompany the upgrade. The version counter increments and upgrade evidence binds the old and new hashes. Immutable programs reject upgrades.

Wind down without stranding value

Lifecycle states are active, deprecated, and tombstoned. Deprecated or tombstoned programs refuse new CALL execution and upgrades. Before deprecation, the owner configures an exit route for each registered program account, including accounts with zero balances. Deprecation binds the program itself as the exit program and a future sequence deadline. Value exits remain available in deprecated and tombstoned states through the configured routes.

Authority and atomic settlement

Storage access, events, calls, transfers, receipt reads, shared storage, balance views, and program spending are separate grants. A callee cannot obtain authority beyond its parent. Identity fields remain bound; monetary ceilings only narrow. Capability escalation refuses the composition rather than committing a partial transfer set.

A program account is derived from the program ID and an exact seed. Derivation alone grants no ownership, registration, funding, or debit authority. The owner registers the account for an Asset; a principal funds it through an ordinary transfer. A ProgramSpend grant separately binds the owner program, seed, source account, Asset, destination, and maximum amount. Only the deriving program frame stages the debit, and repeated transfers consume the ceiling cumulatively.

program account = SHA-256(
  "LayerX/programs/program-account/v1\0"
  || program_id32 || seed_length:u32_be || seed
)

Metering and persistent-state occupancy

Declared ceiling What consumes it
CPU fuel Interpreter instructions and admitted host work.
Memory bytes Peak guest linear memory.
Storage read / write bytes Cumulative state access and mutation.
Output values / bytes Guest return values, response bytes, and refusal transport.
Table elements Peak guest table allocation.

Admission checks each ceiling and reserves fee coverage before guest execution. Persistent storage also incurs deterministic occupancy measured in protocol batches, separate from the execution meter. The signed activity budget authorizes occupancy responsibility. A namespace mandate binds the payer, byte limit, price bound and charge ceiling to the admitted activity.

byte_batches = recorded_bytes × (to_batch − from_batch)
accrued_fee = byte_batches × occupancy_byte_batch_price
amount_due = prior_arrears + accrued_fee

Occupancy settlement becomes final with its covering block commitment and uses the same native transfer primitive. New responsibility uses the admitted caller authorization; existing namespace limits retain their payer when another principal calls. Settlement evidence records amounts due, amounts paid, arrears and frozen status.

Versioned guest interfaces

Guest ABI, kernel module ABI, and wire protocol are independent version numbers. Select the guest ABI required by the artifact and its imports rather than assuming that the kernel module version describes the guest interface.

Guest ABI Host surface added
1 Storage, event emission, program calls, principal transfers, and granted receipt reads.
2 Responses and refusals; scoped storage and scanning; program transfers and funding; context and balance reads; hashing, signature verification and recovery, and 256-bit integer operations.
3 oracle_read for admitted oracle evidence.
4 web_read for admitted web evidence.
5 market_step_adjudicate for deterministic market-step verdicts.

External evidence enters through admitted protocol paths. A state transition does not dial out to an arbitrary service. Frozen ABI vectors and manifests preserve the byte contract across implementations.

Outputs you can verify

Calls return bounded response or refusal bytes and publish terminal evidence, resource usage, call-graph information, and transfer commitments. Verify the activity identity, code and state bindings, terminal, and requested commitment before using a result to release value or advance a workflow. The registry verifies program-account bindings and account records against a trusted committed chain application hash before exposing balances. The chain proof verifier is in programs/crates/layerx-programs-registry/src/chain_accounts.rs.

A granted guest receipt read returns exactly 116 bytes: receipt digest, signed result code, Asset ID, unsigned 128-bit amount, and state root. The digest must match the requested receipt. This lets a merchant program consume authenticated payment evidence instead of trusting a caller-supplied payment description.

Developer workflow

  1. Choose a guest SDK in programs/sdk/rust, programs/sdk/c or programs/sdk/assemblyscript and define the application's state, entrypoints, bounds and capability needs.
  2. Compile to WebAssembly, generate the canonical interface, and hash the artifact.
  3. Deploy with an immutable or authority upgrade policy; verify the deployment receipt.
  4. Register and fund program value accounts where the application holds Assets.
  5. Construct a CALL with the minimum grants and sufficient execution and occupancy ceilings. Simulate against the current head.
  6. Submit the signed activity and verify the committed terminal and receipt before displaying completion.

Rust reference applications include escrow, naming, LXT-721 NFTs, merchant payments, constant-product swaps, LXT-20 tokens, vaults, and web readers. C and AssemblyScript provide paid-counter examples. EVM, Solana/Anchor, and CosmWasm porting guides map familiar concepts to explicit capabilities and native transfer settlement.

Example: fixed-supply LXT-20

The LXT-20 reference is an ABI-2 program backed by one native Asset. It exposes initialize, transfer, approve, transfer_from, balance_of, allowance, total_supply, and metadata. Supply, Asset, and spend ceiling are fixed at build time. Approval of zero revokes an allowance. A recipient must approve at least once, including zero, to register its derived account in token storage, and the deployment authority must separately register that account with the native Programs account module before it can receive backing units. Arbitrary external recipient accounts are refused. This reference has no mint, burn, permit, or nested-call entrypoint.

# Canonical initialize request (hex)
4c581400012000000000

# Run from the repository root; requires the wasm32-unknown-unknown target
cargo build --manifest-path programs/sdk/rust/examples/token-lxt20/Cargo.toml \
  --target wasm32-unknown-unknown --release

Continue with bounded sandbox execution, native Assets, and payments.

Technical references: programs/Cargo.toml; programs/sdk; programs/porting; programs/crates/layerx-programs-runtime/src; programs/crates/layerx-programs-registry/src; src/modules/programs; precompiles/layerxprograms/LayerXPrograms.sol.