# Paxeer X Docs > Guides and reference for the Paxeer X network, LayerX economy, applications, agents and operations. Paxeer X connects EVM applications with LayerX identities, payments, markets, businesses, deterministic programs and verifiable settlement. PAX is the native gas token. ## Start here - [Applications. Payments. Programs. Build on Paxeer.](https://docs.paxeer.app/markdown/index.md): PAXEER X / NETWORK DOCUMENTATION - [Unified Network Architecture](https://docs.paxeer.app/markdown/unified-network.md): The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block. - [System map](https://docs.paxeer.app/markdown/system-map.md): Explore every Paxeer 7.0.0 system by kind, release change, and name, with build commands, configuration, health checks, dependencies, and documentation. - [Paxeer X and LayerX](https://docs.paxeer.app/markdown/paxeer-vs-layerx.md): The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block. - [Accounts & Unified Identity](https://docs.paxeer.app/markdown/accounts.md): An EVM address bound to a native identity on Paxeer mainnet-beta, with explicit asset accounts and financial subaccounts. - [Activities](https://docs.paxeer.app/markdown/activities.md): The signed, canonical unit of agent action across the Paxeer X execution system. - [Receipts & Proofs](https://docs.paxeer.app/markdown/receipts.md): Verify what the protocol executed, what it charged, and whether the covering block has committed. - [Network Parameters](https://docs.paxeer.app/markdown/network-parameters.md): Chain identity, denominations, source defaults, and governance controls for Paxeer mainnet-beta. - [Installation & Build](https://docs.paxeer.app/markdown/installation.md): Build the Paxeer X node, deterministic LayerX kernel, hosted services, agent tools and Programs from the unified monorepo. ## Payments & commerce - [Payments](https://docs.paxeer.app/markdown/payments.md): Build transfers, paid APIs, merchant checkout, metered usage, and subscriptions on Paxeer X with explicit approval, bounded fees, and verifiable settlement. - [Your first payment](https://docs.paxeer.app/markdown/payments-quickstart.md): Quote, commit, and verify a Paxeer X payment using the application SDK or a signed ledger transaction. - [Agent commerce](https://docs.paxeer.app/markdown/commerce.md): Connect merchant checkout, trusted shopping agents, delegated authorization, and receipt-backed payment through Paxeer X. - [Paid APIs and x402](https://docs.paxeer.app/markdown/paid-apis.md): Use x402 version 2 offers, EVM payments, and verified receipts to release paid HTTP resources on Paxeer mainnet-beta. - [Payment mandates and trusted agents](https://docs.paxeer.app/markdown/mandates.md): Authorize direct and autonomous purchases with signed AP2 mandates, exact asset bindings, and trusted-agent request verification. - [Escrow and Conditional Payments](https://docs.paxeer.app/markdown/escrow.md): Reserve funds, capture milestone payments, refund unused balances, and resolve disputes through native Paxeer X escrow. - [Streaming Payments](https://docs.paxeer.app/markdown/streams.md): Pay for elapsed time or verified usage with funded, capped streams, deterministic accrual, settlement, and cancellation. - [Funding and money movement](https://docs.paxeer.app/markdown/funding.md): Quote and commit money movements, fund managed agents, and inspect receipt evidence on Paxeer. - [Fees and payment costs](https://docs.paxeer.app/markdown/fees.md): Understand EVM gas, canonical kernel fee schedules, program occupancy, merchant prices, and fee ceilings on Paxeer. ## Agents & identity - [Agents on Paxeer X](https://docs.paxeer.app/markdown/agents.md): Give autonomous software a verifiable identity, explicit authority, bounded spending, and an evidence trail for every network action. - [Agent runtime](https://docs.paxeer.app/markdown/agent-runtime.md): Run the agent daemon, enrol an identity, connect MCP runtimes, and preserve policy and receipt continuity across restarts. - [Agent-to-Agent Payments](https://docs.paxeer.app/markdown/a2a.md): Discover a payment agent, submit structured tasks and reconcile each outcome with Paxeer X protocol evidence. - [Identity, Ownership and Credentials](https://docs.paxeer.app/markdown/identity.md): Connect human ownership, agent identities, hosted sessions and scoped signing authority across Paxeer X. - [Agent Budgets and Approvals](https://docs.paxeer.app/markdown/agent-budgets.md): Fund bounded agent activity, delegate spending authority, review exact actions and reconcile verified results. - [Account funding & key custody](https://docs.paxeer.app/markdown/custody.md): Fund accounts on the merged network, bind owner identities, and understand signing-key custody in the Human interface. - [Human interface](https://docs.paxeer.app/markdown/human-interface.md): Manage your Paxeer identity, balances, agents, approvals, and recovery through receipt-backed journeys. ## Markets & assets - [Spot Exchange](https://docs.paxeer.app/markdown/spot-exchange.md): Trade asset pairs on Paxeer X with deterministic order books, price-time matching, escrowed liquidity, and immediate two-leg settlement. - [Market Makers](https://docs.paxeer.app/markdown/market-makers.md): Provide exchange liquidity and operate independent asset ramps with bound quotes, authorized payments, durable reconciliation, and receipt-gated settlement. - [Perpetual Futures](https://docs.paxeer.app/markdown/perpetuals.md): Trade long and short exposure through the native order book, USDL cross margin, governed market parameters and committed transaction receipts. - [Oracles & Market Risk](https://docs.paxeer.app/markdown/oracle-risk.md): Understand how Paxeer X accepts signed price observations, rejects stale or anomalous inputs, and applies market-specific risk limits. - [Assets and issuance](https://docs.paxeer.app/markdown/assets.md): Register assets, control issuance, move value, and connect business instruments to payments and markets across Paxeer X. - [Launchpad](https://docs.paxeer.app/markdown/launchpad.md): Create fixed-supply instruments, open virtual-reserve markets, trade with explicit limits, and direct accumulated fees. - [Settlement & committed evidence](https://docs.paxeer.app/markdown/settlement.md): Verify signed execution, transaction inclusion, and committed block evidence on Paxeer X. ## Build applications - [XDK developer toolkit](https://docs.paxeer.app/markdown/xdk.md): Build Paxeer X applications in seven languages with native activities, human journeys, agent tools, exchange integrations, and local proof verification. - [SDK quickstarts](https://docs.paxeer.app/markdown/sdk-quickstarts.md): Register a principal, fund an account, submit a signed transaction, and verify execution evidence with the Paxeer X SDKs. - [Local Protocol Emulator](https://docs.paxeer.app/markdown/emulator.md): Inspect local protocol state with explicit signing identities, account prefunding, time controls and snapshots. - [Developer funding and allocations](https://docs.paxeer.app/markdown/developer-funding.md): Request a bounded development allocation, track its signed treasury transfer, and verify the funded account before your first Paxeer payment. - [Cosmos SDK Fork](https://docs.paxeer.app/markdown/sdk.md): Paxeer X’s in-tree Cosmos SDK fork with Paxeer X-specific modifications and extensions. - [Deterministic Programs](https://docs.paxeer.app/markdown/programs.md): Deploy and call deterministic Paxeer X programs with scoped capabilities, metered execution, governed upgrades and verifiable outputs. - [Bounded Sandboxes](https://docs.paxeer.app/markdown/sandbox.md): Lease isolated deterministic computation with explicit resource ceilings, receipt-backed lifecycle transitions, metered snapshots, and resumable execution. - [Programs Developer Workspace](https://docs.paxeer.app/markdown/program-workspace.md): Build deterministic Paxeer X programs with runtime crates, language SDKs, fixtures, policies and reproducible development workflows. - [Bounded Storage Scans](https://docs.paxeer.app/markdown/storage-scan.md): Iterate Paxeer X program state with deterministic ordering, explicit page budgets, scope-bound continuation cursors, and metered canonical results. - [Services and agreements](https://docs.paxeer.app/markdown/services.md): Publish paid capabilities, agree on deliverables, attest execution, and resolve delivery through the Paxeer X service lifecycle. - [Build with Foundry](https://docs.paxeer.app/markdown/foundry.md): Compile and test the in-tree Solidity contracts with Forge, then inspect a Paxeer deployment with Cast. - [Build with Hardhat](https://docs.paxeer.app/markdown/hardhat.md): Use the repository's Hardhat 2 project to compile contracts and interact with a development node. - [Build a Frontend](https://docs.paxeer.app/markdown/building-a-frontend.md): Connect a browser wallet to Paxeer with React and viem, show PAX balances, and read contracts at a consistent block. - [Python Quickstart](https://docs.paxeer.app/markdown/python.md): Connect to Paxeer with web3.py, read PAX balances and ERC-20 state, and inspect transaction receipts without a signing key. - [Query the EVM](https://docs.paxeer.app/markdown/querying-evm.md): Read Paxeer balances, contract state, receipts, and bounded event ranges with JSON-RPC, Cast, and viem. - [Debug Transactions](https://docs.paxeer.app/markdown/debugging-transactions.md): Diagnose reverted or missing Paxeer transactions with receipts, calldata, gas checks, traces, and reproducible local tests. - [Contracts](https://docs.paxeer.app/markdown/contracts.md): Build Solidity applications on Paxeer X and integrate wrapped PAX, token pointers, and native precompile interfaces. ## APIs & tools - [Platform API](https://docs.paxeer.app/markdown/platform-api.md): Accounts, balances, history, assets, registration, funding and consensus evidence over the hosted gateway, plus the Agent API for policy-governed writes. - [MCP tools](https://docs.paxeer.app/markdown/mcp.md): Connect assistants to verified Paxeer X state and policy-governed wallet and token operations through 22 scoped MCP tools. - [Command-Line Workflows](https://docs.paxeer.app/markdown/cli.md): Operate Paxeer X identities, native assets, payments, deterministic Programs and agent transports with the layerx CLI. - [Webhooks](https://docs.paxeer.app/markdown/webhooks.md): Receive signed Paxeer X events with durable delivery, per-subject ordering, bounded retries, and cursor-based replay. - [Event subscriptions](https://docs.paxeer.app/markdown/subscriptions.md): Build durable agent consumers with scoped visibility, acknowledged cursors, explicit gap recovery, and verified receipt references. - [Program Registry](https://docs.paxeer.app/markdown/registry.md): Resolve proof-verified program deployments, versioned interfaces and reproducible source in the hosted registry. - [Program Discovery](https://docs.paxeer.app/markdown/discovery.md): Discover registered programs and resolve current interfaces, lifecycle, accounts and signed deployment provenance. - [Public RPC endpoints](https://docs.paxeer.app/markdown/public-rpc.md): The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block on EVM chain ID 125. - [JSON-RPC API](https://docs.paxeer.app/markdown/json-rpc.md): Paxeer's EVM JSON-RPC interface with standard Ethereum compatibility and Paxeer-specific enhancements. - [Unsupported JSON-RPC Methods](https://docs.paxeer.app/markdown/json-rpc-unsupported.md): Ethereum JSON-RPC methods that are explicitly unsupported on Paxeer EVM. - [REST & gRPC APIs](https://docs.paxeer.app/markdown/rest-grpc.md): Cosmos SDK REST and gRPC interfaces for Paxeer chain modules and administration. ## Network architecture - [LayerX Kernel](https://docs.paxeer.app/markdown/layerx-kernel.md): The deterministic C17 execution core of Paxeer X: one signed activity, one canonical history, and one reproducible result. - [Sequencing & Finality](https://docs.paxeer.app/markdown/sequencing.md): Follow a signed transaction through ordered execution, receipt verification, and BFT block commitment. - [Consensus](https://docs.paxeer.app/markdown/consensus.md): Consensus service wiring, application execution, trusted headers, and validator signing state. - [Finality & Commitment](https://docs.paxeer.app/markdown/finality.md): Follow transactions executed and ordered by the LayerX kernel inside paxd, from signed execution receipts to blocks checked and committed by validators. - [Checkpoints](https://docs.paxeer.app/markdown/checkpoints.md): Block commitment, trusted state-sync checkpoints, and the disabled checkpoint anchor interface. - [Web Search and xweb](https://docs.paxeer.app/markdown/xweb.md): Search the web, fetch content, and consume attested API results from agents and Solidity contracts. - [Sidiora](https://docs.paxeer.app/markdown/sidiora.md): The SID asset on Paxeer X: native balances, its stable ERC-20 address, bridge-controlled supply, and sponsored or native gas payments. - [Engine](https://docs.paxeer.app/markdown/engine.md): Paxeer's EVM execution engine, transaction processing, and state transition management. - [Design for Parallel Execution](https://docs.paxeer.app/markdown/parallelization.md): Reduce shared-state contention in Paxeer contracts, preserve on-chain invariants, and measure gas separately from throughput. - [EVM Module](https://docs.paxeer.app/markdown/evm.md): Native EVM execution, address association, receipts, pointers, and precompile integration on chain ID 125. - [Storage](https://docs.paxeer.app/markdown/storage.md): State commitment, historical queries, receipt retention, and backend configuration in Paxeer. - [Receipts & Proofs](https://docs.paxeer.app/markdown/proofs.md): Verify Paxeer outcomes independently with signed receipts, native state witnesses, custody proofs, and mirror archives. - [Data Availability](https://docs.paxeer.app/markdown/data-availability.md): Read block availability through the agent runtime and verify supplied batch archives with the proof library. ## Cross-network - [Bridging and balances](https://docs.paxeer.app/markdown/bridge.md): Move assets between registered external chains and Paxeer with attestor signatures, asset limits, and replay protection. - [Interoperability](https://docs.paxeer.app/markdown/interop.md): Connect agent payments, commerce mandates, card and bank rails, and external chains to Paxeer X through evidence-backed adapters. - [Ethereum & Solana Mirrors](https://docs.paxeer.app/markdown/mirrors.md): Publish Paxeer X batch archives to external chains and verify committed receipt evidence independently of a hosted gateway. - [Interchain (IBC)](https://docs.paxeer.app/markdown/interchain.md): Connect Paxeer X to other chains through IBC packets, native token transfers, and the attested bridge. ## Precompiles & WASM - [Precompiles](https://docs.paxeer.app/markdown/precompiles.md): Call native Paxeer X capabilities from the EVM with the correct addresses, ABIs, permissions, and token units. - [WASM](https://docs.paxeer.app/markdown/wasm.md): CosmWasm contract lifecycle, deployment permissions, and calls between Paxeer’s EVM and WebAssembly runtimes. - [WASM Runtime](https://docs.paxeer.app/markdown/wasm-runtime.md): Understand Paxeer’s in-tree CosmWasm virtual machine, Go and Rust boundary, native library builds, and gas accounting. - [WASM Bindings](https://docs.paxeer.app/markdown/wasmbinding.md): Use Paxeer custom messages and queries from CosmWasm, including token creation, EVM calls, address association, and native module reads. ## Protocol modules - [Paxeer X Modules](https://docs.paxeer.app/markdown/modules.md): Native execution, markets, issuance, and data modules in modules/, including retired settlement-compatibility directories. - [Epoch Module](https://docs.paxeer.app/markdown/modules/epoch.md): Time-based hooks and epoch lifecycle management for coordinating periodic chain operations. - [Mint Module](https://docs.paxeer.app/markdown/modules/mint.md): Scheduled native token release through epoch hooks, with daily amounts derived from the remaining supply and governed release dates. - [Oracle Module](https://docs.paxeer.app/markdown/modules/oracle.md): Navigate the retired EVM Oracle API and the native interfaces for exchange rates, voting parameters, and price observations. - [Store Module](https://docs.paxeer.app/markdown/modules/store.md): A single cached-context helper in modules/store/ — not a registered chain module. - [Token Factory Module](https://docs.paxeer.app/markdown/modules/tokenfactory.md): Creation and admin management of native token denominations with creator-namespaced denoms. ## Operate & secure - [Run a Node](https://docs.paxeer.app/markdown/run-node.md): Initialize a Paxeer X node, choose its role, connect to a network, and verify synchronization. - [Configuration](https://docs.paxeer.app/markdown/configuration.md): The current paxd configuration files, node modes, RPC settings, and storage controls. - [Operators Guide](https://docs.paxeer.app/markdown/operators.md): Manage paxd nodes, whose LayerX kernel executes and orders transactions and builds blocks, and the validators that check and commit them. - [Network operations](https://docs.paxeer.app/markdown/network-operations.md): Operate paxd nodes with the LayerX kernel that executes and orders transactions and builds blocks for validators to check and commit. - [Chain History & Archives](https://docs.paxeer.app/markdown/relay-archive.md): Read retained chain history from full or archive nodes and verify exported receipt evidence. - [Troubleshoot a Node](https://docs.paxeer.app/markdown/node-troubleshooting.md): Diagnose Paxeer X sync stalls, peer failures, RPC errors, database locks, and AppHash mismatches before changing node state. - [Docker Development](https://docs.paxeer.app/markdown/docker.md): Local Docker clusters, state-sync RPC nodes, and monitoring for Paxeer X development and testing. - [Security and trust boundaries](https://docs.paxeer.app/markdown/security.md): Verify signed execution receipts from the LayerX kernel inside paxd and the blocks it builds that validators check and commit. - [Validators and commitment](https://docs.paxeer.app/markdown/guarantors.md): The LayerX kernel executes and orders transactions and builds blocks; validators check and commit them. Verify execution receipts and commitment evidence. - [Governance](https://docs.paxeer.app/markdown/governance.md): Authorized module proposals, scoped pauses, and constrained proxy upgrades on Paxeer. - [Admin & HPX](https://docs.paxeer.app/markdown/admin-hpx.md): Runtime administration, the HPX node distribution, and operational controls for Paxeer X. ## For agents - [Full documentation](https://docs.paxeer.app/llms-full.txt): every page in one Markdown file. - [MCP endpoint](https://docs.paxeer.app/api/mcp): Streamable HTTP. Tools: search_docs, read_section, read_page, list_rpc_methods, get_rpc_method, list_systems, get_system. - [OpenRPC document](https://docs.paxeer.app/specs/openrpc.json): the hosted gateway JSON-RPC contract. - Each page is also served as Markdown at https://docs.paxeer.app/markdown/.md, and each generated answer at https://docs.paxeer.app/a//md. --- URL: https://docs.paxeer.app/a2a # Agent-to-Agent Payments Discover a payment agent, submit structured tasks and reconcile each outcome with Paxeer X protocol evidence. ## A payment agent with explicit boundaries The A2A transport exposes a JSON-RPC payment agent bound to one hosted environment. Its agent card declares served skills and enforced gateway scopes. The runtime never signs: a payment is a caller-signed EIP-1559 transaction that the runtime forwards, and verified receipts establish the monetary outcome. ## Install the runtime ``` layerx environment use beta layerx auth set --environment beta layerx install a2a --environment beta --key operator layerx a2a start layerx a2a status ``` Use an already configured beta profile and an existing key named operator. The identity session is read from stdin by `auth set`. Installation provisions a gateway key, stores its secret in credential storage, and starts the managed runtime. Payment mode grants `activity:write` and `receipt:read`. The optional `--source-account` and `--asset` flags must be supplied together as 32-byte hex identifiers. The submitted transaction determines the payment contents. The listener is restricted to loopback and defaults to port `9433`. ### Read-only and credential rotation ``` layerx install a2a --environment beta --read-only layerx a2a stop # Rotate the installed credentials. layerx install a2a --environment beta --key operator --rotate ``` Read-only installation grants `receipt:read`. A separate installation-local Bearer protects incoming task requests. It lives in the owner-only authorization file; the hosted gateway credential remains in secure credential storage. Agent-card discovery is public on the loopback listener. ## Discover the agent card ``` GET /.well-known/agent-card.json # Compatibility discovery path: GET /.well-known/agent.json ``` The card uses A2A protocol version `0.3.0` and preferred transport `JSONRPC`. It includes URL, software version, JSON input/output modes, skill descriptors, the `layerxLocalBearer` security scheme and an environment extension containing environment, deployment mode and scopes. Read this card before choosing a skill. | Skill | Inputs | Authority and evidence | | --- | --- | --- | | `receipt.get` | `activity_id`, a `0x`-prefixed 64-hex transaction hash. | Requires receipt read scope; fetched via `pax_sequencerReceipt`. Verification requires independently pinned receipt keys; the gateway does not verify it for you. | | `activity.submit` | `raw_transaction` only: a caller-signed EIP-1559 transaction as `0x02…` hex. | Requires activity write scope; submitted unchanged via `eth_sendRawTransaction`. The runtime constructs and signs nothing. | | `faucet.request` | DID and public key. | Requires an explicit hosted faucet endpoint through --faucet-endpoint on a2a serve and a stored identity session for the active environment. | ## Send a structured task ``` curl --http1.1 "$A2A_ENDPOINT" \ -H "Authorization: Bearer $A2A_AUTHORIZATION" \ -H "Content-Type: application/json" \ --data-binary ' {"jsonrpc":"2.0","id":1,"method":"message/send","params":{ "message":{ "kind":"message","role":"user","messageId":"receipt-check-01", "contextId":"treasury-reconciliation", "parts":[{"kind":"data","data":{ "skill":"receipt.get","arguments":{"activity_id":"0x<64-hex-transaction-hash>"} }}] } }}' ``` Set the example shell variables to the installed listener URL and its local authorization credential. Curl supplies the Host and Content-Length headers. HTTP requests carry an explicit Content-Length and one JSON body. A data part contains `skill` and `arguments`; a text part may contain the same object serialized as JSON. The server admits only skills in its card. It generates task and artifact IDs and retains the submitted message in task history. ### Payment arguments ``` {"skill":"activity.submit","arguments":{ "raw_transaction":"0x02" }} ``` `raw_transaction` is the sole argument. There are no destination, amount, account-sequence, validity-window, fee-limit, or idempotency-key arguments: destination, amount, nonce, and fees are whatever the caller signed into the transaction. The returned hash must match the raw transaction, and the caller retains it for receipt lookup. ## Track task state and protocol state ``` {"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":""}} {"jsonrpc":"2.0","id":3,"method":"tasks/cancel","params":{"id":""}} ``` | Task state | Meaning | Next step | | --- | --- | --- | | `completed` | The skill returned its result. | Inspect the artifact and verify the monetary outcome evidence. | | `submitted` | Gateway state is acknowledged or pending. | Retain the existing transaction hash and reconcile its receipt. | | `unknown` | The gateway outcome is uncertain. | Look up the original transaction before submitting another write. | | `rejected` | The gateway refused the operation or skill execution failed. | Read the task status message and resolve its cause. | The task artifact carries the skill result as a data part. A completed transport task does not independently establish final settlement. Submitted protocol activities cannot be canceled by this transport; terminal tasks also cannot be canceled. The runtime persists a bounded task ledger and retains unresolved transaction identities across restarts. When started with a matching receipt policy through --receipt-policy, it reconciles pending tasks against verified receipts at startup. Preserve transaction hashes and receipt evidence for application records. ## Capabilities, errors and policy The card declares streaming, push notifications and transition-history capabilities as false for this JSON-RPC runtime. Use `tasks/get` and receipt reads. Unsupported streaming, resubscription, and push-configuration requests return `-32004`, as does `tasks/cancel` on a submitted or unknown task; canceling a terminal task returns `-32002`. Unknown methods or unserved skills return `-32601`; invalid arguments return `-32602`; missing tasks return `-32001`. Malformed JSON returns `-32700`, a request without a method returns `-32600`, and internal failures return `-32603`. Task-ledger admission refusals return `-32005`. Missing or incorrect incoming Bearer credentials return HTTP 401. Use owner policy, capability scope and [budget and approval controls](https://docs.paxeer.app/agent-budgets) to bound agent spending. MCP routes tool calls through an enrolled daemon binding; this A2A runtime forwards caller-signed transactions under its installed gateway credential. See [API authority and commitment levels](https://docs.paxeer.app/platform-api), [identity](https://docs.paxeer.app/identity) and [CLI workflows](https://docs.paxeer.app/cli). --- URL: https://docs.paxeer.app/accounts # Accounts & Unified Identity An EVM address bound to a native identity on Paxeer mainnet-beta, with explicit asset accounts and financial subaccounts. Paxeer X presents a unified account while preserving distinct cryptographic roles on one network. An EVM account uses secp256k1. A LayerX identity uses Ed25519 and the key-derived identifier `did:layerx:<64 hex characters of the public key>`. An on-chain binding connects the two, and named LayerX accounts hold native assets, issued assets, escrow, budgets, streams, and margin. ## One secret, two keys A BIP-39 English mnemonic and optional passphrase produce a 64-byte seed. The same account index selects a matching EVM account and LayerX identity. | Key | Derivation | Path | | --- | --- | --- | | Paxeer EVM | BIP-32 secp256k1 | `m/44'/60'/0'/0/i` | | LayerX identity | SLIP-0010 Ed25519 | `m/44'/19544'/i'/0'` | The index is below 2³¹ and is identical on both paths. LayerX derivation is entirely hardened. Coin type `19544` is the fixed version-1 branch value `0x4c58`, the ASCII bytes LX. Rust, TypeScript, Python, and the CLI use shared derivation vectors. ``` # Read the mnemonic through standard input or a file. layerx wallet derive --index 0 < phrase.txt layerx wallet derive --mnemonic-file phrase.txt --passphrase-file pass.txt # Bind the derived pair using the configured Paxeer RPC. layerx wallet derive --bind --rpc < phrase.txt ``` Derivation prints the EVM address and DID. Private-key export requires the explicit `--export-private-keys ` option; it creates an owner-readable file and refuses to overwrite an existing file. ### External-wallet derivation A browser wallet that keeps its seed private can derive the LayerX key from a fixed EIP-712 signature. The domain is `Paxeer X Network`, version `1`, with the connected chain identifier. The primary type is `LayerXKeyDerivation`; the message binds purpose, warning, address, index, and version. ``` seed = HKDF-SHA256( ikm = canonical signature r || s || v, salt = "paxeer-x-network/layerx-account-key/v1", info = "LX:ACCOUNT-KEY:v1" || chainId_u256_be || address_20_bytes || index_u32_be, L = 32 ) ``` The SDK normalizes the signature to low-s form with v equal to 27 or 28, verifies that it recovers the requested signing address, asks the wallet twice, and compares the canonical signatures. A mismatch refuses derivation with `wallet_signature_not_deterministic`. A signer mismatch refuses with `wallet_signer_mismatch`. The derivation signature is itself secret: anyone holding it can derive the LayerX key. The message names the authorized origin, selected by `ACCOUNT_DERIVATION_ORIGIN` in the TypeScript SDK. Keep the signature out of application logs and storage. A self-hosted origin changes the message and the resulting key, so the chosen origin remains stable for recovery. ``` import { deriveFromBrowserWallet, autoBindLayerX } from '@sidiora/layerx-sdk/browser' const account = await deriveFromBrowserWallet(window.ethereum, { chainId: 125, address, }) await autoBindLayerX(window.ethereum, account, 125) ``` ## Binding both identities The address precompile at `0x0000000000000000000000000000000000001004` records mutual consent. 1. Read `layerXBindNonce(address)` and `getUnifiedAccount(address)`. 2. If the derived DID is already bound, return the existing binding without sending another transaction. 3. If a different DID is bound, refuse with `bound_to_different_did`. Changing identity requires the owner’s deliberate `unbindLayerX`. 4. Sign the domain-separated `LX:PAXEER-BIND:v1` preimage containing chain identifier, EVM address, and nonce with the LayerX key. 5. Call `bindLayerX(didPublicKey, signature)` from the EVM address. The transaction supplies EVM consent and the Ed25519 signature supplies LayerX consent. After binding, the hosted gateway method `px_resolveAccount` resolves the EVM address and DID to the same unified account. It is part of the gateway's `px_` API, defined by its OpenRPC contract. Obtain the gateway URL and credentials from the operator. The CLI bind flow requires EVM chain ID 125. Seed-based helpers construct a signed EIP-1559 transaction; browser-wallet binding uses `eth_sendTransaction` with the pending EVM nonce on that chain. ## Named financial accounts Native escrow, budget, margin, and stream commitments hold value in separate accounts. Each module authorizes transfers from its own accounts. | Namespace | Role | | --- | --- | | `agent::main` | The identity’s native-asset account. | | `agent::asset:` | A separate account for an issued asset. | | `agent::budget:` | Budget-controlled value. | | `agent::escrow:` | Escrow-held value. | | `agent::stream:` | Stream-controlled value. | | `agent::margin:` | Position margin. | | `system:liquidity:` | Market liquidity. | | `system:funding::long\|short` | Protocol-3 market funding accounts. | | `system:insurance`, `system:fees` | Insurance pool and fee treasury. | | `system:paxeer-reserve`, `system:paxeer-withdrawals` | System reserve and withdrawal identifiers recognized by the account namespace decoder. | | `module:asset:value:` | Asset issuance account records. | ### Canonical identifiers ``` account_id32 = SHA-256( "LX:ACCOUNT:v1" || u32_be(name_length) || name_bytes ) ``` The hash above derives ordinary named accounts. A module value name ends in its existing 32-byte account ID as 64 lowercase hex characters, which is decoded directly. Hexadecimal identifiers in names use lowercase text; asset and protocol-3 object identifiers use 64 hex characters. Signed Escrow OPEN, Budget CREATE, and Stream OPEN derive subaccounts from the signed actor DID and object identifier. Signed Perps MARKET_CREATE derives market liquidity and funding accounts. System accounts are created by genesis or authorized governance. ## Authority and sequence ownership An owner’s ordinary signature or session key cannot directly debit a budget, escrow, margin, or stream subaccount. The owning escrow authority, budget allowance, or protocol-module capability authorizes release. This makes the account boundary enforce the financial commitment. | Counter | Scope | | --- | --- | | Activity `account_sequence` | The actor DID’s identity counter. | | Transfer-set `actor_sequence` | The designated sequence account, normally the debited record and therefore per DID and asset. | | Send, mint, and burn | Send advances the source account counter; mint uses the issuance account counter; burn uses the source asset account counter. | An EVM transaction also carries its own sender nonce, read with eth_getTransactionCount at pending. A new per-asset account starts at zero independently of the main account’s counter. Account identifiers are protocol namespace values, not arbitrary application strings. Agent SDK type boundaries reject identifiers outside the supported namespace. ## Recovery and supported wallet paths The same phrase, passphrase, and index restore the same key pair. External-wallet recovery requires the same account, chain, index, origin, and deterministic signing message; the existing binding returns `already_bound`. Wallets with nondeterministic signatures cannot use signature derivation. Smart-contract accounts whose signatures do not recover to the account address are refused on this path. An existing independently generated Ed25519 identity remains valid and can bind manually, though it cannot be re-derived from the EVM secret. Mnemonic derivation accepts the English BIP-39 list. Rotating a derived LayerX key breaks the original derivation link; selecting the next account index preserves a reproducible new pair. ## Continue reading - [Identity, grants, and recovery](https://docs.paxeer.app/identity) - [Issued assets](https://docs.paxeer.app/assets) - [Activity sequences](https://docs.paxeer.app/activities) - [Paxeer precompiles](https://docs.paxeer.app/precompiles) - [Escrow accounts](https://docs.paxeer.app/escrow) - [Budget accounts](https://docs.paxeer.app/agent-budgets) --- URL: https://docs.paxeer.app/activities # Activities The signed, canonical unit of agent action across the Paxeer X execution system. The kernel represents native operations as activities with an actor, authority, payload, sequence, and receipt. Public clients submit signed EVM transactions to node JSON-RPC; native precompiles invoke the kernel within those transactions. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Kernel state changes commit with the node's blocks, and a receipt is final when validators commit its block. ## The exact envelope The `lxp_activity` structure carries exactly twelve fields. Omitting, repeating, or introducing an undeclared field makes an envelope malformed. LXC/1 uses canonical binary encoding, fixed-width big-endian integers, and no floating-point values or unordered maps. Trailing bytes are refused. | Field | Meaning | | --- | --- | | `protocol_version` | The execution rules. Version 1 is the base format, 2 includes occupancy, and 3 includes state commitment. | | `network_id` | The exact execution network; prevents cross-network replay. | | `activity_type` | A 32-bit module and operation discriminator. | | `actor_did` | The identity whose authority and sequence authorize the action. | | `authority` | Authority bytes resolved by the execution path; the standalone Ed25519 verifier requires a 32-byte public key. | | `account_sequence` | The actor identity’s exact next expected counter. | | `timestamp_bound` | `not_before` and `not_after` bounds checked against batch time. | | `idempotency_key` | A 32-byte retry key carried by the operation; admission refuses a key marked as already present in its context. | | `fee_limit` | The maximum authorized deterministic fee, represented as `lxp_u128`. | | `payload_hash` | A 32-byte domain-separated commitment to the canonical payload. | | `payload` | The module’s canonical operation body. | | `signature` | The standalone verifier checks a 64-byte Ed25519 signature over the canonical signing digest, excluding this field. EVM calls authenticate through their transaction authority. | ### Module and ordinal ``` activity_type = (module_id << 16) | operation_ordinal module_id = lxp_activity_module_id(activity_type) operation_ordinal = lxp_activity_type_ordinal(activity_type) Programs module: 0x09 Governance migration budget: 0x0007000a Governance programs fee: 0x0007000b ``` The ordinal is module-specific. Use the operation encoding for the target module rather than treating every payload as a transfer. The governance header defines only the two activity types above for module `0x0007`. The compile-time `LXP_PROTOCOL_VERSION` default is 2; applications explicitly select the protocol version enabled by their execution environment. ## Admission and execution 1. Check protocol version, network, and payload binding in that order. 2. Check the batch-time validity window. 3. Require a valid signature under the resolved authority. 4. Enforce the exact account sequence, check the admission context for a reused idempotency key, and require a spendable fee limit. 5. Compute the fee and validate and execute the module operation within the state journal. 6. Commit successful effects or roll back failed module effects; produce the applicable receipt and bookkeeping. | Outcome | Application consequence | | --- | --- | | Malformed or wrong-network envelope | No admission, sequence consumption, or execution fee. | | Payload binding mismatch | Refused before authority evaluation. | | Sequence too low or too high | Replay or gap refusal. Recover the actor’s current identity counter before preparing new work. | | Fee exceeds the limit | The requested effects are not applied. | | Admitted execution failure | Module effects roll back; the sequence, global position, and applicable fee bookkeeping persist. | | Reused idempotency key | Admission refuses a key marked as already present. Reconcile the original transaction and receipt before preparing another action. | ## Submitting and recovering Submit caller-signed EIP-1559 bytes with `eth_sendRawTransaction` at the node root endpoint. Its EVM chain ID is `125` (`0x7d`). The hosted gateway API is the `px_` family defined in `services/platform/hosted/gateway/openrpc.json`, including account resolution and receipt-key discovery. Public nodes expose `pax_sequencerReceipt` for transaction receipt progress. 1. Prepare the target precompile call and read the sender's pending EVM nonce. 2. Sign the EIP-1559 transaction with currently valid EVM authority. 3. Submit the signed bytes through eth_sendRawTransaction and retain the transaction hash. 4. Verify the receipt against independently trusted receipt keys and check its result before reporting success. 5. Track finality with `pax_sequencerReceipt`: `submitted`, then `receipted`, then `committed`. A receipt is final only at `committed`. If the outcome is unknown, recover the original result before preparing another economic action. ### Keep the two sequence systems separate The native envelope’s account sequence belongs to the actor DID; it is separate from the EVM sender nonce. Transfer sets also carry an actor sequence for their designated sequence account, usually the debited asset record. A per-asset account can start at zero while its owner identity already has a long activity history. Read the correct counter for each protocol structure. ## Native codec interfaces `lxp_activity_encode` and `lxp_activity_decode` handle canonical bytes; `lxp_activity_id` identifies those bytes; `lxp_activity_signing_preimage` produces the signing commitment. Envelope, payload-hash, and signature verification are exposed through `lxp_activity_check_envelope`, `lxp_activity_verify_payload_hash`, and `lxp_activity_verify_signature`. ## Continue reading - [Accounts and sequence ownership](https://docs.paxeer.app/accounts) - [Identity and delegated authority](https://docs.paxeer.app/identity) - [Receipts and result verification](https://docs.paxeer.app/receipts) - [Kernel execution](https://docs.paxeer.app/layerx-kernel) - [Module operations](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/admin-hpx # Admin & HPX Runtime administration, the HPX node distribution, and operational controls for Paxeer X. **Admin:** `admin/` **HPX:** `tools/hpx/` ## Operating the unified network The HPX distribution installs and manages the Paxeer mainnet-beta paxd node. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. The node includes the EVM and native kernel on one network. EVM chain ID 125 identifies this network, and a receipt is final when validators commit its block. Runtime logging administration is separate from economic and security administration. Chain governance controls native parameter and admin messages through `modules/layerxgov/`. Module configuration follows the authorization model implemented by that module. Monitor consensus health, block progress, transaction receipts, node connectivity, and the state of the modules used by your applications. The [parameter reference](https://docs.paxeer.app/network-parameters), [settlement lifecycle](https://docs.paxeer.app/settlement), and [kernel architecture](https://docs.paxeer.app/layerx-kernel) explain those responsibilities. Application operators integrate through the [platform API](https://docs.paxeer.app/platform-api). ## Admin gRPC Service The Admin service provides runtime log level control for `paxd` without restarting the node. It runs on a dedicated loopback-only gRPC server for security. ### Configuration Enable in `app.toml`: ``` [admin_server] admin_enabled = true # admin_address defaults to a loopback listener on port 9095. ``` The configured **admin_address** must contain a numeric loopback IP and port, such as an `IPv4` or `IPv6` loopback listener. The default port is 9095. The enabled server validates this at startup. ### gRPC Methods | Method | Request | Response | Purpose | | --- | --- | --- | --- | | `SetLogLevel` | `pattern`, `level` | `pattern`, level and affected count | Change log level for loggers matching pattern | | `GetLogLevel` | `logger` | `logger` and level | Get current log level for a logger | | `ListLoggers` | `prefix` (optional) | List of loggers | List all loggers and their levels | ### SetLogLevel Pattern Matching The `pattern` parameter supports: - **Exact match:** `"evm"` (sets log level for the EVM logger only) - **Glob:** `"evm*"` (sets log level for all loggers starting with "evm") - **All loggers:** `"*"` (sets log level for every logger) ### Log Levels | Level | Purpose | | --- | --- | | `debug` | Verbose debugging information | | `info` | General operational information | | `warn` | Warning messages (potential issues) | | `error` | Error messages (failures) | ### Example: Using grpcurl with the protocol definition ``` # Run from the repository root; set ADMIN_ENDPOINT to the loopback listener. # List all loggers grpcurl -plaintext -import-path api -import-path sdk/third_party/proto \ -proto pax/admin/v0/admin.proto "$ADMIN_ENDPOINT" \ paxprotocol.paxchain.admin.v0.AdminService/ListLoggers # Set EVM logger to debug grpcurl -plaintext -import-path api -import-path sdk/third_party/proto \ -proto pax/admin/v0/admin.proto -d '{"pattern":"evm","level":"debug"}' \ "$ADMIN_ENDPOINT" \ paxprotocol.paxchain.admin.v0.AdminService/SetLogLevel # Get log level for a specific logger grpcurl -plaintext -import-path api -import-path sdk/third_party/proto \ -proto pax/admin/v0/admin.proto -d '{"logger":"evm"}' \ "$ADMIN_ENDPOINT" \ paxprotocol.paxchain.admin.v0.AdminService/GetLogLevel ``` ### Security The Admin service is loopback-only by design: - The server applies no application authentication; access is bounded by loopback. - Cannot be bound to external interfaces - Must access from the same machine as `paxd` To use the same client through SSH, set the example shell variables to your forwarding specification and SSH login: ``` ssh -N -L "$ADMIN_FORWARD" "$NODE_LOGIN" ``` **Proto:** `api/pax/admin/v0/admin.proto` **Implementation:** `admin/server.go`, `admin/service.go`, `admin/config.go` ## HPX: Paxeer Node Distribution HPX provides the installer, node manager, and peer registry for Paxeer mainnet-beta (`hyperpax_125-1`). Nodes run a native `paxd` binary under systemd. Release artifacts are served by the HPX mirror. ### Chain Identifier `hyperpax_125-1` (Cosmos-style, EVM chain ID `125`) ### Install a Node ``` # From the repository root on a supported Linux node sudo bash tools/hpx/get-hpx.sh ``` The installer: 1. Downloads and verifies the HPX CLI against `checksums.txt` 2. Places `hpx` in `/usr/local/bin/` and offers to run setup ### Setup a Node ``` # Set node type (fullnode or validator) export HPX_TYPE=fullnode # Run setup hpx setup ``` The setup flow: 1. Downloads `paxd`, `libwasmvm` runtimes, genesis, and configuration 2. Verifies all artifacts against `checksums.txt` 3. Installs artifacts under `/root/.paxeer/`, overridable with HPX_HOME 4. Configures systemd service 5. Starts `paxd` ### HPX CLI Commands | Command | Purpose | | --- | --- | | `hpx status` | Show node sync status | | `hpx info` | Show node configuration | | `hpx logs` | Tail `paxd` logs | | `hpx` | Interactive menu | | `hpx start` / `hpx stop` / `hpx restart` | Control the `paxd` systemd service | | `hpx validator keygen` | Generate this node's operator account | | `hpx validator stake` | Submit create-validator from the funded operator account | | `hpx validator status` | Show validator state | | `hpx update` | Update `paxd` and libraries | | `hpx peers show` | Show known peers | | `hpx peers refresh` | Fetch latest peer list from registry | | `hpx register` | Request registration with the peer registry | | `hpx statesync` | Enable state-sync for fast bootstrap | | `hpx remove` | Uninstall the node service and optionally remove its data | ### Node Types | Type | Purpose | Config | | --- | --- | --- | | `fullnode` | Non-validating full node (RPC, indexing) | `/config/fullnode/` | | `validator` | Validating node (must register validator key) | `/config/validator/` | ### Public Registry The HPX registry in `tools/hpx/registry/` serves mirror artifacts and peer discovery through these routes: | Endpoint | Purpose | | --- | --- | | `GET /healthz` | Registry liveness, chain identity and software identity | | `GET /checksums.txt` | SHA-256 checksums for all artifacts | | `GET /chain-info.json` | Chain IDs, binary version and digest, seed peers and release metadata | | `GET /paxd` | Native `paxd` binary | | `GET /lib/libwasmvm..so` | Declared `libwasmvm` runtime artifacts; versioned names are listed below | | `GET /genesis.json` | Chain genesis file | | `GET /config//` | Node configuration files (`config.toml`, `app.toml`) | | `GET /api/myip` | Caller's public IP address | | `POST /api/register` | Register a peer with a fresh challenge and signed node-ownership proof | | `GET /api/peers` | JSON list of registered peers | | `GET /api/peers.txt` | Text list of peer addresses (Tendermint format) | | `GET /api/nodes` | Detailed node metadata | | `GET /api/statesync` | Current state-sync trust parameters | ### Artifact Publishing To publish a new `paxd` release or chain configuration: ``` # From the monorepo root sudo tools/hpx/publish.sh ``` This script: 1. Collects `paxd` from `build/paxd` together with build provenance and the version manifest 2. Collects native libraries from `wasm-runtime/` and `wasm/x/wasm/artifacts/` 3. Collects genesis and chain configuration from `/root/.paxeer/config/` (or `$SRC_CFG`); HPX_SEED_PEERS supplies at least three distinct seeds 4. Stages artifacts in `/srv/hpx/artifacts/releases//` 5. Generates `checksums.txt` 6. Atomically moves `current` symlink to new release The publisher validates the binary identity and all required inputs before updating the served release. ### Registry Runtime The registry service under `tools/hpx/registry/` is distributed in these forms: 1. Linux executables for x86-64 and AArch64 2. GitHub release assets with SHA-256 checksum files 3. A GHCR image for Linux amd64 and arm64 After publishing artifacts and setting HPX_SEED_PEERS, HPX_STATESYNC_RPC and HPX_STATESYNC_RPC_SERVERS, deploy the registry: ``` sudo tools/hpx/hosting/deploy.sh ``` This script: 1. Downloads and verifies the registry executable selected by HPX_SOURCE_REVISION or the registry source identity in Git 2. Installs it as a systemd service (loopback-only) 3. Obtains a TLS certificate for the origin configured in `tools/hpx/hosting/deploy.sh` 4. Configures Nginx reverse proxy with rate-limiting Registry state is persisted at `/srv/hpx/data/registry.json`. ### Registry Authentication Registration requires a fresh challenge and an Ed25519 node-ownership proof. An optional registration token adds another requirement: ``` # Set HPX_REGISTER_TOKEN in the protected deployment environment. # Set HPX_TOKEN for the node manager when the registry requires it. sudo tools/hpx/hosting/deploy.sh ``` When configured, the registry also requires an `X-HPX-Token` header on `POST /api/register`. Obtain a challenge with GET /api/register/challenge before signing the node registration. ### Using an Alternate Mirror Set `HPX_MIRROR` only when operating an explicitly trusted alternate mirror: ``` export HPX_MIRROR="" hpx setup ``` **Warning:** The mirror must serve the same artifact structure and checksums. Untrusted mirrors can serve malicious binaries. ### Native Libraries HPX distributes architecture-specific `libwasmvm` runtimes: - `libwasmvm.x86_64.so` — x86-64 Linux - `libwasmvm.aarch64.so` — AArch64 Linux - `libwasmvm152..so` — version 1.5.2 for x86_64 and aarch64 - `libwasmvm155..so` — version 1.5.5 for x86_64 and aarch64 The node manager detects the host architecture and installs all three runtime variants for that architecture. ### State Sync New nodes can bootstrap from a recent state snapshot instead of replaying full history: ``` hpx statesync ``` This fetches trust parameters from `/api/statesync` and updates `config.toml` to enable state-sync. ### Uninstall ``` hpx remove ``` This stops `paxd` and removes the node service and peer-refresh units. A separate confirmation controls deletion of `/root/.paxeer/`, or the configured HPX_HOME. **Source:** `tools/hpx/README.md`, `tools/hpx/hosting/` --- URL: https://docs.paxeer.app/agent-budgets # Agent Budgets and Approvals Fund bounded agent activity, delegate spending authority, review exact actions and reconcile verified results. ## A funded ceiling for autonomous work Paxeer X budgets give an owner a bounded way to fund delegated work. A budget binds an account, asset, purpose, funding amount, period allowance and expiry. Delegates receive spending authority within that ceiling. The owner can change policy, remove delegates or close the budget as the assignment changes. A budget is a funded ceiling over spending. Account balances, capability permissions, approval holds and budget allowances remain distinct controls. An agent must satisfy every applicable control before its action proceeds. ## Choose the enforcement boundary | Control | Enforcement | Use | | --- | --- | --- | | `ProtocolBudget` | Native protocol validation. | Funded spending ceilings and delegated authority checked during execution. | | `DaemonLimit` | The agent daemon. | Local automation limits for activity routed through that daemon. | | Capability | Scoped agent authorization. | Activity, asset, counterparty, amount, rate, purpose and expiry restrictions. | | Approval hold | The daemon preparation workflow. | Human review of a particular disclosed activity before release. | Route all relevant traffic through the daemon when relying on a daemon limit or approval hold: bypassing that daemon bypasses those controls. Approval releases a prepared action and grants no additional protocol authority. ## Configure a budget | Field | Meaning | | --- | --- | | `budget_id`, `budget_account` | 32-byte budget identity and account binding. | | `asset_id`, `purpose_hash` | The funded asset and committed purpose reference. | | `amount` | Initial funding amount. | | `per_period_limit` | Maximum permitted spend in a budget period. | | `period_length`, `period_start` | Period duration and initial period boundary in milliseconds of protocol batch time. | | `rollover_policy`, `carry_cap` | No rollover, or capped carry-forward of allowance. | | `expiry`, `revocation_sequence` | Expiry in milliseconds of protocol batch time, and the revocation counter. | | `source_account`, `source_sequence` | Version 2 funding source and its replay-protected debit sequence. | Amounts and limits use unsigned 128-bit values at the protocol boundary. Agent API amounts, sequences, limits and timestamps travel as decimal strings. Budget creation takes expiry in seconds; returned protocol records expose period_length_ms, period_start_ms, and expiry_ms in milliseconds. Native budgets support up to 16 delegates. The rollover constants are `LX_BUDGET_ROLLOVER_NONE = 1` and `LX_BUDGET_ROLLOVER_CAPPED = 2`. ### Example policy Consider a procurement agent with 1,000 asset units funded, a 200-unit period ceiling, no rollover and a fixed expiry. A 60-unit purchase consumes both funding and current-period allowance. Adding funding increases available funds; it does not remove the period ceiling. A second delegate shares the budget ceiling rather than receiving an independent copy of it. Choose asset-unit scaling before encoding values. With six decimal places, 60 units encodes as `60000000`. The example describes policy values; obtain the asset precision from its registered metadata. ## Native budget activities Budget is module `3`. Its ten activity types occupy `0x0003xxxx`. Canonical payloads begin with a big-endian two-byte version prefix. | Activity | Type | Purpose | | --- | --- | --- | | `LX_BUDGET_CREATE` | `0x00030001` | Create a funded budget and its period policy. | | `LX_BUDGET_FUND` | `0x00030002` | Add funds, preserving policy limits. | | `LX_BUDGET_AMEND` | `0x00030003` | Amend period limit, carry cap, expiry and rollover. | | `LX_BUDGET_DELEGATE_ADD` | `0x00030004` | Add a permitted delegate. | | `LX_BUDGET_DELEGATE_REMOVE` | `0x00030005` | Remove a delegate. | | `LX_BUDGET_SPEND` | `0x00030006` | Transfer the specified amount to a recipient within the budget. | | `LX_BUDGET_CLOSE` | `0x00030007` | Close using the required revocation sequence. | | `LX_BUDGET_DEFUND` | `0x00030008` | Withdraw funding from a budget. Payload: 50 bytes. | | `LX_BUDGET_REVOKE` | `0x00030009` | Revoke a budget. Payload: 42 bytes. | | `LX_BUDGET_DELEGATE_SPEND` | `0x0003000a` | Spend as a delegate under a per-spend and total delegate capability. Payload: 114 bytes (version, budget, recipient, amount, and a 32-byte idempotency key). | ### Canonical spend payload ``` version:u16be = 1 budget_id:bytes32 recipient:bytes32 amount:u128be Total: 82 bytes ``` Create supports version 1 at 211 bytes and version 2 at 251 bytes. Fund supports version 1 at 50 bytes and version 2 at 58 bytes. Version 2 create appends the source account and source sequence; version 2 fund appends the source sequence. Period maintenance uses the protocol batch timestamp to roll due periods. ## Agent API workflow 1. Use `budget.create` with the intended enforcement mode and establish the permitted agent capability. A `ProtocolBudget` create requires the signed `BudgetAuthorization`; that authorization is refused for a `DaemonLimit`. 2. Use `budget.fund` to add funds to a protocol budget. Funding requires the signed authorization carrying its preparation reference and signature; funding a `DaemonLimit` is refused, because a daemon limit holds no funds. 3. Inspect state with `budget.reconciliation` before scheduling new spending. The `budget.state` read returns the budget record, proven head and balance. 4. Prepare the action with actor, authority, account sequence, timestamp bound, idempotency key, fee limit, payload and payload hash. 5. Review the returned disclosure, then sign and submit the exact preparation. 6. Track the submission and reconcile its verified receipt with the budget and account state. 7. Use `budget.revoke` and capability revocation when the assignment ends. Protocol-budget revocation requires BudgetAuthorization for the exact prepared revoke activity. Protocol spending uses the native budget activity and protocol validation. Daemon budget objects carry their enforcement mode explicitly. Keep receipt evidence attached to reconciled spending so local scheduling decisions follow committed results. ## Approve the exact action An approval record contains `approval_id`, tenant, the held structured activity disclosure, canonical bytes digest, hold reason, creation time, expiry and state. Review actor, authority, counterparties, amounts, asset, fee limit, expiry and idempotency key alongside the canonical digest. | Operation | Behavior | | --- | --- | | `approval.list` | Find approval records in the authorized scope. | | `approval.get` | Inspect one held action and its disclosure. | | `approval.approve` | Release the exact preparation bound to the reviewed digest. | | `approval.reject` | Reject the held action. | Decision operations carry an `idempotency_key`. Approval states are `Held`, `Granted`, `Rejected`, `Expired` and `Defective`; all except Held are terminal. A modified activity requires its own preparation and review. Approval does not override a missing delegate grant, expired capability or exhausted budget. ## Reconcile before retrying Submission states include Prepared, Signed, Queued, Submitted, Unknown, Executed, Committed, Failed and Expired. `Unknown` is a pending state requiring reconciliation. Executed and Committed results carry a receipt reference. Use `track` or `wait` to inspect evidence and the rung actually reached (`submitted`, `receipted`, or `committed`) before making a new economic attempt. ### Common refusals | Refusal | Response | | --- | --- | | `LXP_ERR_BUDGET_PERIOD_CAP`, `LXP_ERR_BUDGET_ALLOWANCE_EXCEEDED` | Inspect period policy and remaining allowance; amend only with owner authority. | | `LXP_ERR_INSUFFICIENT_BUDGET_FUNDS` | Reconcile funds and fund the budget if appropriate. | | `LXP_ERR_UNAUTHORIZED_DELEGATE`, `LXP_ERR_UNAUTHORIZED_DEBIT` | Check delegate, owner and funding-source bindings. | | `LXP_ERR_BUDGET_REVOKED`, `LXP_ERR_EXPIRED` | Stop spending under that authority. | | `LXP_ERR_STALE_REVOCATION`, `LXP_ERR_SEQUENCE_REUSED`, `LXP_ERR_SEQUENCE_GAP` | Refresh verified revocation and sequence state before preparing again. | **Technical references:** `include/layerx/lx_budget.h`; `src/modules/budget/`; `services/agent/schema/agent-api/` identity, write and approval contracts. See [identity and delegated credentials](https://docs.paxeer.app/identity) for owner authority, session revocation and recovery. --- URL: https://docs.paxeer.app/agent-runtime # Agent runtime Run the agent daemon, enrol an identity, connect MCP runtimes, and preserve policy and receipt continuity across restarts. The Paxeer X agent runtime connects autonomous software to LayerX activity execution through a controlled daemon boundary. `layerx-agentd` owns sessions, capabilities, approval holds, local limits, and durable evidence. MCP exposes those controls as tools. Actions reach the node as signed EIP-1559 transactions that call native precompiles; the hosted agent boundary serves verified execution receipts. ## Runtime components | Component | Responsibility | Trust boundary | | --- | --- | --- | | `layerx-agentd` | Identity enrolment, session authentication, capability checks, local policy, and evidence verification. | Protected tenant store, human owner, and daemon credentials. | | `layerx-mcp` | Daemon-bound tool catalogue for reads and actions. | One session and capability; no separate MCP write authority. | | `layerx mcp serve` | Serve the bound catalogue over standard input and output. | Protected daemon binding document. | | `layerx-agent-boundary` | TLS receipt lookup and signed deployment evidence. | Separate gateway, registry, and webhook credential planes. | ## 1. Configure the network profile Only the profile name is positional. To configure a profile, supply the endpoint, network identifier, and receipt trust anchor together. Omitting all three reuses a configured profile. Supply either a literal trust anchor or a trust-anchor file. The CLI retains the implementation name `layerx`. ``` layerx environment use beta \ --endpoint \ --network-id \ --sequencer-trust-anchor # The trust anchor may instead be read from a file: # --sequencer-trust-anchor-file ``` The profile names are `emulator`, `beta`, and `production`. Non-loopback endpoints use HTTPS. A profile controls CLI network access. The daemon configuration uses `node_endpoint` or `LAYERX_NODE_ENDPOINT` for the node root HTTP(S) URL. ## 2. Enrol the daemon identity Configure the agent DID, tenant, authority, capability, session identity, and binding output under the daemon's `LAYERX_AGENT_MCP_*` settings. Setting `LAYERX_AGENT_MCP_BINDING_ROOT` enables binding publication. The daemon resolves the DID through the human authority, registers the identity, restores the named capability, opens a session, and publishes the runtime binding before accepting requests. These are daemon lifecycle operations, not a `layerx` session-opening command. A publication failure closes the newly opened session; restart restores the named session and its matching document instead of creating duplicate credentials. | Binding artifact | Contents | Protection | | --- | --- | --- | | `binding.json` | Mode, tenant, store, audit root, session and capability references, daemon endpoint, credential file paths, local limit context, the protected Unix listener socket and admitted peer UIDs, and an optional web-search sidecar reference. | Owner-only binding directory and file access. | | `session-token` | OS-random session Bearer token. | Separate protected file; excluded from host configuration. | | `daemon-bearer` | Daemon transport authentication. | Separate protected file; excluded from the binding document. | Binding directories use mode `0700` and files use `0600`. Existing secret files are refused instead of overwritten. A different binding at an existing publication path is also refused. ## 3. Install the runtime connection Install MCP after daemon enrolment publishes its binding. Supported hosts are `layerx`, `claude-code`, `claude-desktop`, `cursor`, and `vscode`. Repeat `--host` to install into multiple runtimes. ``` layerx install mcp --host claude-code \ --daemon-binding /absolute/path/to/binding.json # Restrict the installed tool surface to reads. layerx install mcp --host cursor --read-only \ --daemon-binding /absolute/path/to/binding.json # Run the same stdio server directly. layerx mcp serve --daemon-binding /absolute/path/to/binding.json ``` The installer opens and validates the same document used at serve time. Relative explicit paths become absolute. Without an explicit binding path, installation resolves `mcp/binding.json` beside the CLI configuration. Host launch configuration holds the executable, arguments, and an empty process environment; secret material stays in protected daemon files. MCP installation uses the binding's session and capability. It does not provision a gateway credential or ask for a source account, asset, signing seed, or network profile. The read-only flag narrows the declared binding mode. Tool discovery exposes only scopes admitted by the bound session. ## 4. Admit an action Each action passes session authentication, capability evaluation, policy, rate and quota limits, deadlines, and budget reservation before submission. Capability checks evaluate expiry, activity type, counterparty, asset, amount, rate, and purpose. An approval hold retains the exact canonical preparation and its reservation until an authorized decision or expiry. Use the [agent action lifecycle](https://docs.paxeer.app/agents) to prepare, review, sign, submit, and track. Requests carry stable idempotency keys. Repeating an identical mutation returns its original result; changing the body under the same key produces an idempotency conflict. ## Submission and receipt recovery Submit the signed EIP-1559 transaction to the node with `eth_sendRawTransaction`. Retain its transaction hash and the daemon preparation and submission references. The hosted boundary retrieves signed receipts by transaction hash and verifies them against its configured receipt keys. | Interface | Use | | --- | --- | | `eth_sendRawTransaction` | Submit a signed EVM transaction to the node. | | `GET /v1/receipts/{id}` | Retrieve the signed receipt associated with a transaction hash. | | `pax_sequencerReceipt` | Read the node receipt and its reported evidence rung. | | `eth_getTransactionReceipt` | Read the EVM execution status, logs, and block reference. | | `eth_call` | Read or simulate a precompile or contract call without committing it. | | `eth_getProof` | Retrieve account and storage proof material at a block. | | `eth_getBlockByNumber` | Retrieve a block for a selected height or tag. | | `eth_chainId` | Check the EVM chain identifier, `0x7d` for chain 125. | The receipt route is served by the hosted agent boundary; the JSON-RPC methods are served by the node. The boundary's Bearer planes are separate from daemon sessions and from CLI gateway credentials. Keep transport-specific credentials with their intended boundary. ## Evidence and write readiness Receipt trust keys are configured independently of incoming proof data. The hosted boundary verifies the receipt signature, its authorized key interval, transaction hash, and signing identity. The Agent API distinguishes execution evidence from committed-block evidence; a receipt is final when validators commit its block. `tenant.readiness` reports `transport_ready`, `verified_reads_ready`, `writes_admitted`, and an optional recovery reason. Writes are admitted exactly when no recovery reason is present, which requires transport and a genuine state-proven account read for the authenticated tenant. Readiness is tenant-scoped; an HTTP connection alone does not establish recovered spending authority. After a process failure, restore durable holds, verify receipts, and resolve uncertain spends before opening writes. An unresolved reservation remains held. Local limits enforce daemon policy; bypassing the daemon bypasses those limits. Protocol-enforced authority and cryptographic receipt evidence remain separate from local accounting. ## Operate and revoke Monitor preparation age, open approvals, held budget, unresolved submissions, stream gaps, and verification failures. The hosted boundary's `/livez` reports process liveness; `/readyz` additionally probes node receipt lookup. Loss of the node can leave liveness healthy while readiness fails. Revoke a capability or close a session to withdraw agent access. Revoking a capability revokes its whole parent subtree and fails its unsubmitted preparations. Preserve audit and receipt records so a revoked agent's historical actions remain traceable. **Reference:** `services/agent/crates/layerx-agentd/src/enrolment.rs`, `session.rs`; `services/agent/schema/agent-api/identity.kvx`; `tools/platform/cli/src/install/mcp.rs`; `services/platform/hosted/agent-boundary/src/main.rs`. --- URL: https://docs.paxeer.app/agents # Agents on Paxeer X Give autonomous software a verifiable identity, explicit authority, bounded spending, and an evidence trail for every network action. Paxeer X agents submit signed EIP-1559 transactions to native precompiles on chain 125. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. An agent reads state, prepares a transaction, reviews its effects, obtains a signature, and tracks the resulting evidence. The agent daemon supplies tenant isolation, session controls, policy, and runtime integration. ## Choose an agent integration | Integration | Use it for | Authority path | | --- | --- | --- | | Agent API | A custom service that needs preparation, signing, submission, reads, approvals, and event subscriptions. | Tenant-bound daemon session and explicit capability. | | MCP | Expose network tools to an assistant or development runtime. | Daemon binding, session, and capability; tools use the Agent API. | | A2A | Submitting a caller-signed transaction and reading receipts from another agent. | Hosted gateway key; the caller signs, the runtime never signs. | | Native programs | Deterministic application logic called by an agent. | Signed program activities, execution receipts, and program registry evidence. | Start with [Agent runtime](https://docs.paxeer.app/agent-runtime) for daemon enrolment and runtime installation, or [Native programs](https://docs.paxeer.app/programs) for application execution. ## Identity and registration An agent DID identifies the actor. An authority reference identifies the grant under which it acts. A tenant scopes records, credentials, and policy. These are separate from the runtime client name and from the session used to authenticate a request. Registration binds the agent to a verified owner; a self-declared DID alone does not confer permission. | Operation | Required context | Purpose | | --- | --- | --- | | `agent.register` | tenant, agent_did, authority_ref, client, policy_version, owner_address, binding_consent, fee_limit | Register the agent under its verified authority. Returns `AuthorityResponse`. | | `session.open` | context, grant_id, registration_payload, expiry_sequence, purpose, fee_limit | Open a tenant-bound authenticated session. Returns `AuthorityResponse`. | | `session.refresh` | session_id, context | Refresh the session within its authority and policy. | | `session.close` | session_id, context | Close access and invalidate session use. | | `session.list` | context | Inspect sessions visible to the authenticated owner. | For `agent.register`, `owner_address` is the 40-hex EVM address that signs the transaction and `binding_consent` is the 128-hex owner-signed Ed25519 consent, verified against the chain ID and current bind nonce. For `session.open`, `grant_id` and `purpose` are 64-hex values, `registration_payload` is the canonical session grant matching the grant ID, and `expiry_sequence` is a nonzero decimal. The session context itself includes tenant, agent DID, authority reference, permitted activity types, expiry, client, and policy version. ## Define what an agent may do A capability names every permission dimension explicitly. Missing dimensions are invalid; an empty set denies that dimension. Use `capability.create` to issue a bounded capability, `capability.attenuate` to derive a narrower child, `capability.list` to inspect it, and `capability.revoke` to withdraw access. Create, attenuate, and revoke each require an `idempotency_key`; a keyless create is refused before the owner is called. Revoking a capability revokes its whole parent subtree in one durable write, and unsubmitted preparations bound to a revoked record end in `Failed` with a capability-revocation reason. | Dimension | Decision it controls | | --- | --- | | activity_types | Which native operations the agent can prepare. | | counterparties | Which counterparties may participate. | | assets | Which assets the agent may use. | | amount_ceilings | Maximum authorized quantities per asset. | | rate_ceilings | Action counts within explicit time windows. | | purpose_constraints | The permitted purpose commitments. | | expiry | The last permitted authorization period. | Attenuation never widens authority: child sets are subsets, amount ceilings do not increase, expiry does not move later, and rate windows remain at least as restrictive. Capabilities restrict an existing protocol grant; they do not manufacture a new protocol authority. ## The action lifecycle 1. **Read.** Obtain account sequence, balance, and relevant module state. 2. **Prepare.** Supply `activity_type`, `actor`, `authority`, `account_sequence`, `not_before`, `not_after`, `idempotency_key`, `fee_limit`, `payload`, and `payload_hash` to the daemon wire API. 3. **Review.** Inspect the disclosure decoded from the unsigned canonical bytes: actor, authority, activity type, counterparties, amounts, asset, fees, expiry, and idempotency key. 4. **Sign.** Sign the returned transaction preimage with secp256k1 and bind the 65-byte signature to the preparation reference. The wire signature is 130 lowercase hexadecimal characters. 5. **Submit.** Submit that preparation, signature, and `signer_public_key`, retaining the submission reference. 6. **Track.** Use `track` or `wait` to observe evidence and the reached rung. ``` prepare → Prepared { preparation_ref, unsigned_canonical_bytes, signing_preimage, disclosure, expiry } sign(preparation_ref, signature) → Signed submit(preparation_ref, signature, signer_public_key) → TrackedSubmission { state, evidence, rung, transitions } track(submission_ref) → state + evidence + rung wait(submission_ref, requested_rung, deadline) → actual_rung ``` Submissions move through Prepared, Signed, Queued, Submitted, Unknown, Executed, Committed, Failed, or Expired. Unknown is a pending outcome that requires reconciliation. Executed and Committed carry a receipt reference. Preserve the original idempotency key while resolving an uncertain submission. ## Budgets and human approval Budget controls distinguish protocol-enforced budgets from daemon-enforced limits. A daemon limit reserves capacity before an activity proceeds; an unresolved outcome retains its hold until evidence resolves the result. The daemon consumes protocol evidence; it does not mint balances from local accounting. See [agent budgets](https://docs.paxeer.app/agent-budgets) for the native budget activities and funding rules. Human approval binds an exact prepared activity and its canonical disclosure digest. Approval releases that preparation; rejection releases its reservation; expiry never implies approval. A changed disclosure is defective and requires a new review. Approval is a daemon restriction and does not enlarge protocol authority. ## Read, observe, and verify Read operations cover balances, accounts, module state, history, batches, checkpoints, and proof bundles. A batch identifies a block height; a checkpoint contains a CometBFT commit and validator set. Portable proof bundles bind the raw transaction, signed execution receipt, EVM receipt inclusion, and CometBFT commit. Availability fetch and offline export support evidence portability. Projection returns an estimate and is distinct from a verified read. Evidence is reported as a rung: `submitted`, `receipted`, or `committed`. Submitted is an acknowledgement, receipted verifies execution, and committed verifies inclusion in a committed block. Request the rung the decision needs with `wait`; when the deadline elapses it returns the rung actually reached rather than an error. Subscriptions are scoped by tenant, agent, and capability. Filters narrow agents, accounts, activity types, modules, assets, counterparties, and result classes. Delivery is at least once; deduplicate using `deduplication_id`, acknowledge cursors, and handle Gap and Truncated events explicitly. ## Design a reliable agent - Use a dedicated identity and the narrowest capability for each workload. - Require review for actions outside a routine policy; show canonical effects to the approver. - Separate daemon policy records from cryptographically verified network receipts. - Retain preparation, submission, activity, and receipt references across process restarts. - Treat transport loss and deadlines as uncertainty, then reconcile before authorizing a replacement action. **Reference:** `services/agent/schema/agent-api/identity.kvx`, `write.kvx`, `stream.kvx`, `read.kvx`, `errors.kvx`; `services/agent/crates/layerx-agentd/src/session.rs`, `capability/`, `approval/`, `budget/`. --- URL: https://docs.paxeer.app/assets # Assets and issuance Register assets, control issuance, move value, and connect business instruments to payments and markets across Paxeer X. ## One network, several asset surfaces Paxeer X combines native bank denominations, EVM token interfaces, and the LayerX Asset registry. Choose the authority and settlement path that match the instrument. A token name is display metadata: the registered asset identifier, bank denomination, or contract address identifies the actual balance authority. | Surface | Identity | Primary use | | --- | --- | --- | | LayerX registered asset | 32-byte asset ID and issuer DID | Authorized issuance, account transfers, and supply-bound receipts. | | Native bank asset | Bank denomination | Native transfers, tokenfactory issuance, module settlement. | | ERC-20 interface | EVM address | Wallet and contract integration, including native-asset pointers. | | Launchpad instrument | ERC-20 token and pool addresses | Fixed-supply issuance and a virtual-reserve trading market. | Agents create and operate businesses, and trade instruments those businesses issue. The business, its instrument, and the agent acting for it have separate identities. A token balance does not by itself define business ownership, revenue rights, or a legal claim: those terms belong to the instrument and its associated agreement. Read [Launchpad](https://docs.paxeer.app/launchpad) for issuance into a curve market and [Exchange](https://docs.paxeer.app/spot-exchange) for market execution. ## Register a LayerX asset The Asset module is module `1`. Registration records the issuer, symbol, name, decimals, supply cap, custody reference, and salt. Amounts are unsigned integer counts of the smallest unit; decimals only affect presentation. For example, an asset with six decimals represents 12.5 display units as `12500000` base units. | Field | Rule | | --- | --- | | Symbol | 1–16 ASCII bytes. | | Name | 1–32 bytes of valid UTF-8. | | Decimals | At most 38. | | Supply cap | Unsigned 128-bit integer; zero permits supply up to the unsigned 128-bit maximum. | | Issuer kind | 1 for native issuance; 2 for Paxeer custody. | | Custody reference | At most 128 bytes; empty for native issuance. | ### Identifiers and accounts ``` native_asset_id = SHA-256("LX:ASSET:v1" || issuer_did_id32 || salt32) account_id = SHA-256("LX:ACCOUNT:v1" || u32_be(name_length) || name_bytes) agent::main agent::asset: ``` Hexadecimal text inside canonical account names is lowercase. Custody-backed assets use the supplied custody asset ID rather than deriving a native ID. Registration creates the asset record and an issuance account named `module:asset:value:`. A module value account decodes its embedded identifier rather than hashing the full name. Duplicate asset IDs are rejected. ## Issue, transfer, and retire units 1. Register the asset under the issuing DID and record its asset ID. 2. Open a per-asset account for the actor receiving or holding units. 3. Mint a positive base-unit amount to a matching asset account, with issuer authorization and available issuance units. 4. Send units from an actor-owned account to the recipient account. 5. Burn units from an actor-owned account when retiring supply. Mint moves units from the issuance account to the destination. Burn returns units to issuance. The module checks account ownership, asset identity, available balance, and supply invariants before updating balances. A nonzero supply cap limits issuance. Supply before and after are bound into asset transition receipts. | Ordinal | Operation | Authority or effect | | --- | --- | --- | | 1 | Register | Create the canonical asset and issuance account. | | 2 | Pause | Recorded issuer pauses asset operations. | | 3 | Unpause | Recorded issuer restores asset operations. | | 4 | Account open | Open the actor's account for the asset. | | 5 | Send | Transfer units from an actor-owned source. | | 10 | Mint | Issuer-authorized transfer from issuance to an asset account. | | 11 | Burn | Return units from an actor-owned account to issuance. | ## Account transfers and spending limits A send names its source account, destination account, asset, positive base-unit amount, and idempotency key. The source belongs to the actor. Both accounts hold the same asset, and the source must have enough units. The signed context binds the transfer fields. An agent can apply daemon capabilities and local limits when preparing payments. Keep the permitted asset, counterparty, and maximum amount explicit. [Payments](https://docs.paxeer.app/payments) describes payment integration and [x402](https://docs.paxeer.app/paid-apis) covers metered service collection. ## Pause controls and custody metadata Only the recorded issuer pauses or unpauses an asset. A pause blocks send, mint, burn, and account opening. Custody-kind registration records the supplied asset identifier and custody reference. The seven operations above define the active Asset dispatcher. The [Bridge](https://docs.paxeer.app/bridge) page describes the separate bridge surface. ## Discover balances and verify context `px_listAssets` on the hosted gateway selects up to 16 registry records in registration order. Its optional `cursor` is a canonical positive signed-64-bit decimal row ID. Follow `next_cursor` until it is null. The response includes `height`, `assets`, `joined_limit: 16`, and `order: "registration"`. For one native asset, call `getAsset` on the ledger precompile at `0x101A` through `eth_call`. `px_getBalances` resolves an EVM address or bound DID and reads bank balances for that EVM address. The Rust SDK's `estimate_fee()` calls `eth_estimateGas` and returns a gas estimate. Asset metadata reads are pinned to the returned block height. Unavailable metadata leaves name, symbol, decimals, and supply null. A successful ledger read also includes `paused` and `verification: "authenticated_committed_snapshot"`. Independent inclusion proofs require additional evidence. Match the height, asset identifier, issuer, pause state, and base-unit amount before signing. ## Continue building Use [Tokenfactory](https://docs.paxeer.app/modules/tokenfactory) for native denomination administration, [Pointers](https://docs.paxeer.app/contracts) for cross-runtime token interfaces, and [Launchpad](https://docs.paxeer.app/launchpad) for fixed-supply curve markets. --- URL: https://docs.paxeer.app/bridge # Bridging and balances Move assets between registered external chains and Paxeer with attestor signatures, asset limits, and replay protection. ## Choose the asset path External-chain bridging moves value between a foreign vault and a Paxeer bank denomination. Paxeer mainnet-beta uses EVM chain ID 125. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. A successful Paxeer receipt is final when validators commit its block. An external payout also requires the destination chain receipt. | Boundary | Asset backing | Acceptance evidence | | --- | --- | --- | | External chain ↔ Paxeer X | Foreign-chain vault or Solana custody program | Threshold attestor signatures, registered chain and asset, caps, unique source event | | Transfers within Paxeer | Native bank balances and derived sub-accounts | Successful transaction execution in a committed block | ## External-chain connectors The external bridge uses `PaxeerXVault` on EVM chains and a custody program on Solana. Its Paxeer X interface is the `LayerXBridge` precompile at `0x0000000000000000000000000000000000001016`. Governance controls chain registration, vault identity, finality depth, attestor sets, per-asset limits, and pause state. Default bridge genesis contains no registered chains, attestors or asset caps. Governance registers and enables each chain, sets the attestor threshold, and registers asset limits before deposits can be accepted. The connector configurations are under contracts/bridge/evm/chains/ and contracts/bridge/solana/chains/solana/. Read the active on-chain configuration for the selected chain before depositing. | Connector | Chain identifier | Native counterpart | | --- | --- | --- | | Ethereum | 1 | ETH | | Base | 8453 | ETH | | Arbitrum | 42161 | ETH | | Optimism | 10 | ETH | | BNB Chain | 56 | BNB | | Polygon | 137 | POL | | Avalanche | 43114 | AVAX | | HyperEVM | 999 | HYPE | | Solana | 91600046870081 | SOL; also Sidiora (SID) | Resolve the registered vault and asset configuration for the selected connector before depositing. Solana uses chain-specific encodings for its keys, mints, and transaction identities; the SID asset identifier is declared explicitly in its connector configuration. Do not treat a Solana chain identifier as an EVM RPC chain ID. ### Deposit from an external chain Each step below presumes the chain and asset have been registered by governance. 1. Choose the registered chain, asset, amount, and Paxeer EVM recipient encoded as a left-padded bytes32 value. Check pause state and the asset's per-transaction and in-flight limits. 2. Lock the asset in the configured foreign vault. EVM native-coin deposits use `depositNative(bytes32 paxeerRecipient)`. 3. The relayer observes the deposit after the connector's configured finality depth. Attestors sign the deposit digest binding chain, vault, transaction hash, log index, recipient, asset, and amount. 4. Submit `bridgeIn` with the event and threshold signatures. The precompile credits the bridged denomination and emits `BridgeIn`. 5. Retain the source event and Paxeer X receipt. The source tuple `(chain, txHash, logIndex)` is consumable once. ### Withdraw to an external chain `bridgeOut(chain, asset, amount, recipient)` burns the caller's bridged denomination and returns a nonce. The `BridgeOut` event identifies the outbound transfer. Attestors sign the foreign vault's release digest, and the relayer submits the release to the destination custody contract. Track both the Paxeer X burn and foreign release; a burn receipt alone is not the destination payout receipt. ### Precompile reference ``` interface ILayerXBridge { function bridgeIn(uint64 chain, address vault, bytes32 txHash, uint64 logIndex, bytes32 recipient, address asset, uint256 amount, bytes[] calldata signatures) external returns (string memory denom); function bridgeOut(uint64 chain, address asset, uint256 amount, address recipient) external returns (uint64 nonce); } ``` Use `getChain`, `getAttestors`, `getCap`, `isPaused`, and `isNullified` for preflight and reconciliation. Inbound signatures are 65-byte `r || s || v` signatures over the raw bridge digest, with low s, v equal to 27 or 28, and strictly ascending signer addresses. Signing a prefixed personal message produces different evidence. ## Read bridge configuration The bridge ABI is in precompiles/layerxbridge/LayerXBridge.sol. Its view methods expose the chain registration, attestor set, caps and replay state used by the keeper. 1. Read the registered vault, finality depth and enabled flag for the selected chain. 2. Read the current attestor identities and signature threshold. 3. Read the asset denomination, per-transaction cap and in-flight supply cap. 4. Check pause and source-event replay state before submitting a deposit. ### Signature acceptance The inbound digest binds the remote chain, registered vault, source transaction hash, log index, Paxeer recipient, asset and amount. The recipient is a nonzero EVM address in the low 20 bytes of a bytes32 value, with its high 12 bytes zero. The signature format is specified in modules/layerxbridge/ATTESTATION.md. The inbound domain is PAXEERX_BRIDGE_IN_V1; the EVM outbound domain is PAXEERX_BRIDGE_OUT_V1. Attestors sign the raw Keccak-256 digest. Each accepted signature must recover a current attestor, and the recovered addresses must be strictly ascending. ## Track an external withdrawal A successful bridgeOut burns the caller's bridged denomination and advances the registered chain's outbound nonce. The foreign vault releases the corresponding asset after checking its outbound signatures, cap, pause state and replay protection. 1. Preserve the Paxeer transaction hash, chain, asset, recipient, amount and outbound nonce. 2. Obtain signatures for that exact transfer using the registered foreign custody configuration. 3. Submit the release and wait for the destination chain receipt. 4. Reconcile the Paxeer burn with the foreign release event before reporting payout. | Condition | Result | | --- | --- | | Bridge is paused | Inbound and outbound transfers are refused | | Chain is unregistered or disabled | Transfers for that chain are refused | | Source event has already been credited | A second inbound credit is refused | | Transfer exceeds its per-transaction cap | The transfer is refused | ## Recovery and reconciliation Reconcile a timed-out deposit against its original source event. The bridge exposes `isNullified` to check whether the inbound event has been consumed. For EVM withdrawals, the foreign vault consumes a nullifier derived from the Paxeer transaction hash and outbound nonce. Keep the foreign deposit, Paxeer credit, Paxeer burn and destination release as separate records. Inspect the existing transfer before retrying. Native account funding uses bank transfers within Paxeer; it does not require a separate custody deposit or checkpoint settlement step. ## Continue building Read [interoperability](https://docs.paxeer.app/interop) for foreign protocol connectors, [the unified architecture](https://docs.paxeer.app/paxeer-vs-layerx) for execution and settlement responsibilities, and [precompiles](https://docs.paxeer.app/precompiles) for EVM integration. --- URL: https://docs.paxeer.app/building-a-frontend # Build a Frontend Connect a browser wallet to Paxeer with React and viem, show PAX balances, and read contracts at a consistent block. Start with one clear interaction: connect a wallet and display its PAX balance. viem separates public reads from wallet requests, so your page can load chain state before asking for a signature. ## Use the application workspace The frontend in apps/launchpad/web uses Next.js, React, viem and Wagmi. From the repository root, install the launchpad workspace dependencies and run its web application. ``` cd apps/launchpad pnpm install pnpm dev ``` Configure `apps/launchpad/web/.env.local` with `NEXT_PUBLIC_PAXEER_RPC_URL` set to a browser-accessible node root. Next.js exposes `NEXT_PUBLIC_` values to visitors: use a public browser endpoint and keep provider credentials on a server. The launchpad RPC selector gives NEXT_PUBLIC_RPC_URL and NEXT_PUBLIC_RPC_URL_FALLBACK precedence over this value. ## Define Paxeer once The chain definition in `apps/launchpad/web/src/core/wallet-sdk/client.ts` makes the chain ID and native currency explicit. For `hyperpax_125-1` the endpoint must answer `eth_chainId` with `0x7d` (125). The node mapping in `modules/evm/config/config.go` also defaults unmapped chain names to 125. Check the endpoint and wallet `id` before requesting a signature. ``` import { createPublicClient, defineChain, http } from "viem"; import { getPaxeerRpcUrl } from "@/core/rpc"; const rpcUrl = getPaxeerRpcUrl(); export const paxeer = defineChain({ id: 125, name: "Paxeer X Network", nativeCurrency: { name: "PAX", symbol: "PAX", decimals: 18 }, rpcUrls: { default: { http: [rpcUrl] } }, }); export const publicClient = createPublicClient({ chain: paxeer, transport: http(rpcUrl), }); ``` ## Connect and display a balance Use this example as a client component alongside `apps/launchpad/web/src/core/wallet-sdk/client.ts`. It requests accounts only after a click, adds Paxeer if the wallet does not know the chain, and clears old results whenever the account or network changes. ``` "use client"; import { useEffect, useRef, useState } from "react"; import { createWalletClient, custom, formatEther, type EIP1193Provider } from "viem"; import { paxeerWalletChain as paxeer, getPublicClient } from "@/core/wallet-sdk/client"; const publicClient = getPublicClient(); function injectedProvider() { return (window as Window & { ethereum?: EIP1193Provider }).ethereum; } export default function App() { const [result, setResult] = useState(); const [error, setError] = useState(); const [busy, setBusy] = useState(false); const requestId = useRef(0); const connecting = useRef(false); const mounted = useRef(true); const selection = useRef<{ account?: string; chainId?: number }>({}); useEffect(() => { mounted.current = true; const provider = injectedProvider(); const reset = () => { requestId.current += 1; setResult(undefined); setError(undefined); selection.current = {}; }; const accountsChanged = (accounts: string[]) => { if (accounts[0]?.toLowerCase() !== selection.current.account) reset(); }; const chainChanged = (chainId: string) => { if (Number(chainId) !== selection.current.chainId) reset(); }; provider?.on("accountsChanged", accountsChanged); provider?.on("chainChanged", chainChanged); return () => { mounted.current = false; requestId.current += 1; provider?.removeListener("accountsChanged", accountsChanged); provider?.removeListener("chainChanged", chainChanged); }; }, []); async function connect() { if (connecting.current) return; connecting.current = true; requestId.current += 1; setBusy(true); setError(undefined); setResult(undefined); let readId: number | undefined; try { const provider = injectedProvider(); if (!provider) throw new Error("Open this page in a wallet browser or install an EVM wallet."); if (await publicClient.getChainId() !== 125) throw new Error("RPC endpoint is not Paxeer chain 125."); const wallet = createWalletClient({ chain: paxeer, transport: custom(provider) }); const [requestedAccount] = await wallet.requestAddresses(); selection.current.account = requestedAccount?.toLowerCase(); if (await wallet.getChainId() !== 125) { try { await wallet.switchChain({ id: 125 }); } catch (cause) { const failure = cause as { code?: number; cause?: { code?: number } }; if (failure.code !== 4902 && failure.cause?.code !== 4902) throw cause; await wallet.addChain({ chain: paxeer }); await wallet.switchChain({ id: 125 }); } } if (!mounted.current) return; selection.current = { account: requestedAccount?.toLowerCase(), chainId: 125 }; // Begin the read after the wallet has completed account and chain selection. const id = ++requestId.current; readId = id; const [account] = await wallet.getAddresses(); if (!account) throw new Error("No wallet account selected."); if (await wallet.getChainId() !== 125) throw new Error("Select Paxeer in your wallet."); if (id !== requestId.current || !mounted.current) return; selection.current = { account: account.toLowerCase(), chainId: 125 }; const balance = await publicClient.getBalance({ address: account }); if (id === requestId.current && mounted.current) { setResult(account + ": " + formatEther(balance) + " PAX"); } } catch (cause) { if (mounted.current && (readId === undefined || readId === requestId.current)) { setError(cause instanceof Error ? cause.message : "Wallet request failed."); } } finally { connecting.current = false; if (mounted.current) setBusy(false); } } return (

Paxeer wallet

{result}

{error &&

{error}

}
); } ``` Run `pnpm dev` from apps/launchpad, open the web application, and connect an EVM wallet. The initial connection waits for account and network selection before reading. Later selection changes clear the old result and invalidate a read in flight; click again to refresh. This example reads balances without sending a transaction. ## Read a deployed wrapped-token balance Use the WPAX contract address produced by [Foundry](https://docs.paxeer.app/foundry) or [Hardhat](https://docs.paxeer.app/hardhat). The interface comes from `contracts/src/WPAX.sol`; pass the deployment address and account to this example helper. ``` import { getAddress, parseAbi } from "viem"; import { getPublicClient } from "@/core/wallet-sdk/client"; export async function readWrappedBalance(contractAddress: string, owner: string) { const publicClient = getPublicClient(); if (await publicClient.getChainId() !== 125) throw new Error("Unexpected chain"); const address = getAddress(contractAddress); const blockNumber = await publicClient.getBlockNumber(); const bytecode = await publicClient.getCode({ address, blockNumber }); if (!bytecode || bytecode === "0x") throw new Error("No contract at this address"); const balance = await publicClient.readContract({ address, abi: parseAbi(["function balanceOf(address) view returns (uint256)"]), functionName: "balanceOf", args: [getAddress(owner)], blockNumber, }); return { blockNumber, balance }; } ``` ## Build a complete transaction experience - For writes, simulate the exact call with the selected account, request the wallet signature, then wait for the receipt. - Show separate states for signature requested, submitted, confirmed, and failed. A returned transaction hash means submission, not successful execution. - Refresh affected queries after a successful receipt and keep the hash available for inspection. - For ERC-20 amounts, read the token’s decimals and use `parseUnits`/`formatUnits`. Native PAX uses 18 decimals; arbitrary tokens may differ. - On mobile, support an in-wallet browser or add a wallet connector that supports your application’s target devices. For a larger React application, Wagmi adds connector lifecycle and query hooks on top of viem. Retain the same custom Paxeer chain definition and separate public reads from wallet requests. References: [viem custom chains](https://viem.sh/docs/chains/introduction), [clients and transports](https://viem.sh/docs/clients/intro), and [contract reads](https://viem.sh/docs/contract/readContract). **Paxeer source:** `apps/launchpad/web/src/core/wallet-sdk/client.ts`, apps/launchpad/web/src/core/rpc.ts, modules/evm/config/config.go (ChainIDMapping), and rpc/state.go (GetBalance and GetCode). --- URL: https://docs.paxeer.app/checkpoints # Checkpoints Block commitment, trusted state-sync checkpoints, and the disabled checkpoint anchor interface. ## Block commitment The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Paxeer mainnet-beta uses EVM chain ID 125. A receipt is final when validators commit its block; a separate checkpoint submission is not part of application settlement. - `SubmitCheckpoint`, `SubmitAvailabilityAttestation`, and `SubmitEquivocation` in modules/layerxanchor/keeper/ unconditionally return a module-retired error. - The `0x1014` precompile disables writes when `v7.0` is active and disables every selector when `v7.0-anchor-store-delete` is active. - The ABI below declares the checkpoint read signatures. These calls do not provide a settlement path on the merged network. For the live ordering and evidence path, see [Sequencing & Finality](https://docs.paxeer.app/sequencing). Custody operations are covered under [Custody](https://docs.paxeer.app/custody). ## What a block header binds Consensus headers identify the chain and block, link the block history, and commit transaction, validator and application data. The header and commit types are defined in consensus/types/block.go. | Commitment | Fields | What a consumer checks | | --- | --- | --- | | Domain | Chain ID and block version | The header belongs to the expected chain and block format. | | Ordering | Height and previous block ID | The height and previous-block reference continue the trusted chain. | | State transition | Previous-height application hash and result hash | The commitment covers the state after the preceding height; match the proof height accordingly. | | Record commitments | Transaction data hash and evidence hash | The block data and evidence match their header commitments. | | Validator authority | Validator and next-validator hashes | The validator sets agree with the trusted consensus history. | | Consensus | Timestamp, proposer and last commit | Header time and validator signatures satisfy the consensus verification rules. | Obtain commitments from verified block headers and validator commits. A root copied from an unverified response is not a trust anchor. The light client in consensus/light/ verifies headers against a trusted validator set and trust period. ## Transaction and block flow 1. A signed transaction is submitted to the node and checked for mempool admission. 2. The kernel seals the block it has built. 3. Validators evaluate the proposal under the configured consensus protocol. 4. The application executes the ordered transactions and records their results. 5. Consensus commits the block and the application commits its state. 6. Applications read the transaction receipt and check its status and committed block identity. | Stage | Evidence | Established property | | --- | --- | --- | | Submitted | Transaction hash | The transaction has a reconciliation identity. | | Proposed | Proposed block | The transaction has a proposed position in the block. | | Executed | Application result | The transaction has an execution outcome. | | Committed | Consensus commit | The block and its receipts are final. | | Successful | Successful transaction receipt | The committed transaction executed successfully. | ## Validator signatures and state sync The light client verifies headers using trusted validator information. Non-adjacent verification checks trusted-set overlap and requires more than two-thirds of the new validator voting power to sign the new header. Trust-period and clock-drift checks also apply. State sync uses an independently trusted block height and hash with application snapshots. Snapshot production is configured in app.toml under [state-sync]; snapshot consumption is configured in config.toml under [statesync]. Configure the joining node with trusted RPC servers and a valid trust period. ## Checkpoint read ABI The checkpoint anchor address is `0x0000000000000000000000000000000000001014`. These signatures are declared in precompiles/layerxanchor/LayerXAnchor.sol. With the store-delete upgrade active, every selector returns a disabled-module error. ``` interface ICheckpointReads { function latestFinalized() external view returns (uint64 batchNumber, bool exists); function statusOf(uint64 batchNumber) external view returns (uint8); function finalizedStateRoot(uint64 batchNumber) external view returns (bytes32 stateRoot, bool finalized); function finalizedReceiptRoot(uint64 batchNumber) external view returns (bytes32 receiptRoot, bool finalized); function checkpointBatch(bytes32 checkpointId) external view returns (uint64 batchNumber, uint8 status); } ``` The ABI declares status values `0`, `1`, and `2` for unknown, submitted and final. The declarations `checkpoint(batchNumber)` and `checkpointGuarantors(batchNumber)` describe checkpoint records. They do not supply live block finality. The interface file is `precompiles/layerxanchor/LayerXAnchor.sol`. ## Checkpoint write availability The anchor ABI declares `openChallenge(batchNumber, kind, evidenceHash)` with kind `0` for fraud and `1` for availability, and declares `finalize(batchNumber)`. These write selectors are disabled on the merged network; application receipt finality comes from the BFT block commit. The anchor declaration `submitEquivocation(evidenceA, evidenceB)` is also disabled. Validator equivocation is handled by the consensus evidence and slashing modules. ## Consumer verification checklist 1. Verify endpoint TLS trust and the expected Paxeer chain identity. 2. Verify the block header and validator commit against an independent trust anchor. 3. Check the transaction hash, block identity and committed height. 4. Read the transaction receipt and check whether execution succeeded. 5. Verify state proofs against the application commitment for the requested height. 6. Check application authorization, asset units and replay protection for the operation. 7. Retain verified evidence and reconcile the resulting events and balances. For EVM transactions, read `eth_getTransactionReceipt` and inspect `status` and `blockHash`. A submission hash identifies a transaction; successful execution in a committed block establishes the application result. Continue with [settlement evidence encodings](https://docs.paxeer.app/settlement), [native account funding](https://docs.paxeer.app/custody), [Paxeer consensus](https://docs.paxeer.app/consensus), and [native EVM interfaces](https://docs.paxeer.app/precompiles). --- URL: https://docs.paxeer.app/cli # Command-Line Workflows Operate Paxeer X identities, native assets, payments, deterministic Programs and agent transports with the layerx CLI. ## The Paxeer X developer CLI The CLI source is tools/platform/cli/. The binary is named `layerx`. Use `layerx --help` for the command's current flags. Global `--json` emits one structured object: success contains `ok`, `kind`, `message` and `data`; failure contains `ok: false` and `error.code` with `error.detail`. Use these fields in automation instead of parsing presentation text. ## Bind an environment ``` layerx environment list layerx environment current layerx environment use beta --endpoint "" --network-id --sequencer-trust-anchor-file ``` Profiles are `emulator`, `beta` and `production`. Configure a hosted API base URL, native network ID and receipt-signing trust anchor together when binding a new profile. This profile is separate from the node JSON-RPC root selected by --rpc. Reusing a configured profile needs only its name. Non-loopback HTTP endpoints are refused; use HTTPS. The native network ID is distinct from EVM chain ID 125. ### Configuration and credential storage `LAYERX_CONFIG` selects a config file. Otherwise the CLI uses `$XDG_CONFIG_HOME/layerx/config.json` or `$HOME/.config/layerx/config.json`. Public metadata and endpoints live in config; keys, hosted tokens and gateway credentials live in credential storage. The OS keyring is the default. ``` # Headless Linux: select the encrypted file store before key creation. export LAYERX_CREDENTIAL_STORE=file read -r -s -p 'Credential passphrase: ' LAYERX_CREDENTIAL_PASSPHRASE export LAYERX_CREDENTIAL_PASSPHRASE layerx --json key create operator layerx key default operator layerx --json key list # auth set reads the session token from standard input. layerx auth set --environment beta layerx --json auth status --environment beta ``` The file store requires a 12–16,384 byte passphrase and encrypts the vault beside the configuration using AES-256-GCM and PBKDF2-HMAC-SHA256. Preserve the vault and its passphrase securely. Store selection has no automatic fallback or migration. Seeds and tokens supplied to import commands are read from stdin and never belong in shell arguments or public configuration. ## Register and inspect an identity ``` layerx key show operator layerx register --key operator --gateway-endpoint "" layerx account get layerx wallet list layerx wallet balance --gateway-rpc "" ``` Registration signs the tenant binding and accepts a response only when its tenant, subject and signer key match. An imported key establishes local custody; registration and funding are separate steps. `layerx faucet --key operator --service-endpoint ` requests an approved bounded beta allocation using the stored identity session. ## Virtual chains ``` layerx --rpc "$PAXEER_RPC_URL" chains list layerx --rpc "$PAXEER_RPC_URL" chains show layerx --rpc "$PAXEER_RPC_URL" chains create --name --tier --fee-share-bps <0-5000> --evm-key-file ``` `layerx chains` lists, inspects and creates virtual chains on the chain registry. Like wallet, token, program and `receipt get` commands it accepts the global `--rpc` and `--gateway-credential` flags; the node RPC URL must use the root path `/`. Set PAXEER_RPC_URL in your shell to that node URL for these examples. The tier is starter, growth or pro. Creation requires an EVM key file (for example from `wallet derive --export-private-keys`) or `LAYERX_EVM_KEY_FILE`. ## Wallets and native assets | Command | Workflow | | --- | --- | | `wallet create `, `wallet import ` | With the emulator transport, create a key, register its identity and open its main account (optional `--did`). Import stores a 32-byte hexadecimal seed from stdin without registering an account. | | `wallet derive` | Derive the EVM account and native identity from one BIP-39 phrase read from stdin or a file. | | `wallet balance`, `wallet list` | Inspect DID accounts through --gateway-rpc, or verify --proof-snapshot with --proof-policy; list local public wallet metadata. | | `wallet open-account` | Open a wallet's native account for a specified asset. | | `wallet send`, `token transfer` | Prepare native transfers with recipient, asset, amount and signing policy. | | `token create` | Register a native asset with symbol, name, decimals, salt and optional supply cap. | | `token mint`, `token burn` | Issue into an existing asset account or return units to issuance. | | `token info `, `token list` | Read metadata and the ascending native asset registry. | | `wallet estimate-fee`, `wallet watch`, `wallet receipt` | Estimate fees from unsigned EIP-1559 transaction bytes at pending (requires `--from`), receive a notification, and verify receipt evidence for a transaction hash at the submitted, receipted or committed level. Supply --receipt-policy for verified receipt evidence. | Global `--rpc` selects the node root. Hosted px_ queries use an explicitly configured service URL through `--gateway-rpc`; `--gateway-credential` selects a stored gateway alias. Use independently trusted receipt policy, explicit fee limits and current sequences for monetary writes. Native asset amounts are integer units rather than floating-point display amounts. ## Quote and commit a payment ``` layerx --json payment test --from --to --currency --amount 1000 --idempotency-key treasury-payment-0001 ``` This workflow requests a quote through `/v1/moves/quote` and commits through `/v1/moves`. Keep the key stable for retries. The payment command returns the quote and commit journey; independently verify receipt bytes before treating the outcome as settled. ## Fetch and verify receipts ``` layerx --json --rpc "$PAXEER_RPC_URL" receipt get <0x-transaction-hash> layerx --json receipt verify --receipt receipt.hex --batch-id --asset --previous-state-root --resulting-state-root --sequencer-public-key ``` `receipt get` fetches a sequencer receipt by its 0x-prefixed transaction hash. Supply the receipt file as hex text or raw bytes and obtain batch facts through an independently trusted source. Verification is local and requires no node or gateway. The command reports `verified: true` only after checking the canonical outcome against the supplied facts. To check committed transaction evidence, use wallet receipt with --wait committed and --receipt-policy; Paxeer finality comes from the block commit. A timeout or pending response retains the original transaction hash: look it up again rather than submitting a new payment. ## Build and operate Programs ``` layerx new treasury-program layerx program build --manifest-path treasury-program/Cargo.toml layerx --rpc "$PAXEER_RPC_URL" program discover layerx --rpc "$PAXEER_RPC_URL" program interface get layerx --rpc "$PAXEER_RPC_URL" program registry get ``` Build compiles WASM and enforces deterministic runtime policy locally. Discovery reads the program registry through eth_call at pending and requires the program to be active. Interface reads check the canonical interface encoding and digest. These reads do not establish committed deployment evidence. Bindings generation checks interface digest and code hash and produces typed SDK and guest bindings; supply verified deployment evidence and trust history according to `layerx program bindings --help`. | Command family | Operation | | --- | --- | | `program deploy`, `program upgrade` | Validate and submit artifacts with lifecycle authorization and receipt verification. | | `program interface publish` | Publish a canonical interface bound to program code. | | `program simulate` | Execute against current state with sealed non-commit evidence. | | `program call` | Sign and submit an EIP-1559 call to a deployed program; render a receipt-verified typed result. | | `program wind-down route`, `deprecate`, `tombstone`, `exit` | Route owned accounts, define an exit deadline, retire code and exit account positions. | | `program registry mirror-source`, `program registry list` | Publish a build plan and source archive to the configured mirror, or list deployment events. Mirroring returns the deployed code hash and source digest. | Deploy, upgrade and wind-down writes require --receipt-policy and `--program-id`, a required `--evm-key-file`, and `--fee-limit` (default `0`). Interface publication takes the program ID positionally and also requires an artifact, interface, key file, receipt policy and idempotency key. The `program interface publish` command requires `--idempotency-key`. Calls also bind fuel, ABI, memory and capability requirements. Receipt verification binds the returned activity, sequencer, state root, ABI and terminal payload before rendering typed success. Simulation explicitly establishes `committed: false`. ## Connect agent transports ``` layerx install mcp --host cursor --daemon-binding layerx mcp serve --daemon-binding layerx install a2a --environment beta --key operator --source-account <64-hex-source-account> --asset <64-hex-asset-id> layerx a2a start layerx a2a status layerx a2a stop ``` MCP installation reads the binding document produced by agent-daemon enrollment and serves its tool catalogue over stdin/stdout. The transport carries no signing seed or gateway credential. Supported host names are `layerx`, `claude-code`, `claude-desktop`, `cursor` and `vscode`. Use `--read-only` for a read-only MCP installation. A2A installation targets a hosted environment, provisions a scoped gateway credential in secure storage and serves the agent card and task interface on loopback. The default listener uses loopback port `9433`. Managed start, status and stop use the installed runtime configuration. ## Local development and workspace operations `layerx emulator provision` creates sequencer seed and trust-anchor files; `layerx emulator up --sequencer-seed-file ` runs the local gateway around real protocol transitions. Bind the emulator profile to its advertised identity before use. `layerx workspace` opens the visual workspace on a TTY. Its `modules`, `doctor`, `install`, `build`, `test` and `all` commands support repeatable module operations; use dry-run and explicit module selection for automation. ## Read failures before retrying Check the JSON error code. Network or sequencer trust mismatches require correcting the profile. Credential failures require the selected store and session. Receipt verification and ABI mismatches require resolving the evidence or interface. Policy and capability refusals require appropriate authorization. Retry uncertain writes only with their original identity, and retain existing activity IDs for reconciliation. Continue with the [platform API reference](https://docs.paxeer.app/platform-api), [identity model](https://docs.paxeer.app/identity) and [Programs runtime](https://docs.paxeer.app/wasm-runtime). --- URL: https://docs.paxeer.app/commerce # Agent commerce Connect merchant checkout, trusted shopping agents, delegated authorization, and receipt-backed payment through Paxeer X. ## One commerce journey, explicit authority at every step The commerce adapters under services/interop/crates/ connect protocol requests to the network payment path: a merchant advertises its capabilities, an agent identifies the intended operation, the payer supplies bounded authorization, and the payment plane produces verifiable settlement evidence. Checkout and order experiences use that evidence to report a completed purchase. | Protocol or integration | Role | Result | | --- | --- | --- | | UCP | Merchant profiles, capability negotiation, checkout completion, and order reads. | A checkout outcome and an order tied to verified payment evidence. | | AP2 | Signed payment and checkout mandates with evaluated constraints. | An authorized payment mapped to a typed payment intent. | | Visa Trusted Agent Protocol | Signed agent identity and browse or pay intent verification. | A verified agent credential handed to the merchant authority path. | | Express and FastAPI | Paid-resource release, fulfillment persistence, and webhook processing. | A resource associated with its canonical receipt and request digest. | ## Merchant discovery and capability negotiation The UCP adapter uses revision `2026-04-08`. A merchant profile declares REST services, payment handlers, and supported capabilities. A platform profile is negotiated against it before checkout completion. The checkout capability is `dev.ucp.shopping.checkout`; order reads use `dev.ucp.shopping.order`. Negotiation binds the selected payment handler by digest, so checkout completion carries the payment configuration that the participants agreed to use. Publish a merchant profile with the supported protocol revision and HTTPS service endpoint. Have the buying platform negotiate its capabilities before it submits a payment. Preserve the negotiated result alongside the checkout for subsequent order verification. ## Complete a checkout 1. Prepare the checkout identifier, uppercase three-letter currency, and positive total in ISO-4217 minor units. Configure the merchant currency-to-asset binding and exact conversion to atomic asset units. 2. Bind the checkout to the LayerX asset and recipient, negotiated payment handler, and a stable UCP idempotency key. 3. Submit completion through `POST /v1/http/ucp/checkouts/complete`. 4. The payment plane executes the typed payment intent. Pending or refused execution produces the corresponding checkout outcome. 5. For executed payment, verify the signed canonical receipt, transaction identity, logs and checkout binding. Return the completed order only after that evidence passes verification. At the adapter boundary, the completion request has the following fields. These fields are declared by the Rust submission type in services/interop/crates/layerx-ucp/src/lib.rs: ``` CheckoutSubmission { checkout_id, currency, // [u8; 3], ISO-4217 code total_minor, // u128, positive minor-unit amount layerx_asset, // [u8; 32] layerx_recipient, // [u8; 32] idempotency_key, // UcpIdempotencyKey negotiated, // NegotiatedCapabilities } ``` Submission validation also requires a nonzero LayerX asset, a nonzero recipient, and a nonzero negotiated payment-handler digest. A submission that fails validation is refused before payment execution. ### Retries and completion states The gateway binds an idempotency key to a digest of the submitted request. Repeated attempts retain their payment identity. An execution already settled by receipt must present consistent order evidence on a retry; a pending response cannot replace previously verified settlement. | Checkout status vocabulary | Meaning in the purchase journey | | --- | --- | | `Incomplete` | The checkout still requires information. | | `RequiresEscalation` | The flow requires escalation before completion. | | `ReadyForComplete` | The checkout is ready for completion submission. | | `CompleteInProgress` | Completion awaits a payment result. | | `Completed` | Verified payment evidence supports the order. | | `Canceled` | The checkout is canceled. | ## Read an order with its evidence An order combines merchant-owned metadata, including its order identifier and HTTPS permalink, with verified settlement evidence. `UcpAdapter::read_order_with_config` checks the negotiated order capability, validates metadata and the merchant currency binding, and re-verifies the stored signed receipt and logs against the transaction and original checkout. Reading an order is a read operation; it does not debit balances or execute a second payment. ## Release paid resources The Express and FastAPI integrations connect settlement to merchant fulfillment. The integrations live in sdk/integrations/express/ and sdk/integrations/fastapi/. Their fulfillment repository receives a proposed record and a resource-release function. Persist the idempotency key, request digest, canonical receipt, and returned resource together. On repeat delivery, return the existing record only when its request digest matches; a different digest produces a fulfillment conflict. The Express example uses exclusive file creation (`wx`) for fulfillment records. The FastAPI example serializes fulfillment by key and persists records through atomic replacement. Choose a durable fulfillment repository and webhook delivery store for services that run across restarts or multiple workers. Keep fulfillment identity consistent with the payment operation. ## Plan the merchant integration 1. Define the merchant profile, payment handler, asset mapping, and recipient. 2. Choose the buying-agent credential and [mandate authorization](https://docs.paxeer.app/mandates) policy. 3. Persist checkout submissions, idempotency keys, and merchant order metadata. 4. Store signed canonical receipts, transaction hashes, logs, receipt-key authorizations and merchant currency bindings for checkout completion and order reads. 5. Connect fulfillment and webhook delivery to durable application records. Use [EVM applications](https://docs.paxeer.app/evm) for contract-facing experiences and [the SDK](https://docs.paxeer.app/sdk) for network integration. Commerce adapters preserve protocol-specific identities while submitting typed payment operations. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Paxeer mainnet-beta receipts are final when validators commit their blocks. --- URL: https://docs.paxeer.app/configuration # Configuration The current paxd configuration files, node modes, RPC settings, and storage controls. ## Configuration across the unified network The chain configuration below controls `paxd`. Hosted service configuration is maintained separately under `services/platform/hosted/` and the component workspaces. Paxeer mainnet-beta uses EVM chain ID 125. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Configure hosted dependencies for that network and preserve their service-specific authorization settings. | Surface | Configure | Boundary | | --- | --- | --- | | Core boundary | Network ID, node and replica connections, TLS material, and separate admin credentials | Core and admin listeners are separate planes | | Gateway | Public TLS, upstream dependencies, receipt verification, request policy, and shared coordination storage | Public application ingress | | Registry | Published service identities, network records, route destinations, and signing policy | Discovery records identify the authorized network services | | Node | Consensus identity, peer topology, execution, storage retention, and API listeners | Block commitment establishes receipt finality | | Agent and Human | Provider destinations, identity and approval policy, key-management channels, and receipt dependencies | User-facing authorization reaches protected provider boundaries | Generate `config.toml` and `app.toml` using `paxd` as shown below, then review the configured listeners and storage settings. Persistent data and runtime socket directories are distinct. Keep administrative listeners and signer channels off public ingress; route applications through the [gateway API](https://docs.paxeer.app/platform-api). See [on-chain parameters](https://docs.paxeer.app/network-parameters) for governance-controlled economic settings. ## Configuration Files `paxd init --chain-id ` generates configuration under `~/.paxeer/config/`. An explicit `--home` changes that location. Generate files using the binary revision you will run, then edit the settings you need. | File | Purpose | | --- | --- | | `config.toml` | Consensus, P2P, mempool, consensus RPC, state-sync client, and validator signer | | `app.toml` | Application APIs, EVM RPC, execution, snapshots, and storage | | `client.toml` | CLI node, chain, output, and keyring defaults | | `genesis.json` | Initial chain identity, consensus parameters, and application state | ## Node Modes ``` paxd init my-node --chain-id hyperpax_125-1 --mode full ``` | Mode | Application profile | History | | --- | --- | --- | | `full` | API, gRPC, EVM RPC, and KV transaction index | 100,000 recent SS versions and consensus blocks by default | | `archive` | Full-node services; consensus mode is written as `full` | SS and block retention set to zero, meaning keep available history | | `validator` | API, gRPC, EVM RPC, SS queries, and transaction indexing disabled by this profile | State needed to validate and execute | | `seed` | Discovery profile with a 1,000-connection setting; public application APIs disabled | Peer discovery role | The default init mode is `full`. It binds consensus RPC and P2P to all interfaces. Validator and seed profiles retain the base loopback listeners; configure the intended peer topology explicitly. **Source:** `daemon/paxd/cmd/init.go`; `node/params/config.go` — `SetTendermintConfigByMode`, `SetAppConfigByMode`, `SetEVMConfigByMode`. ## Consensus and P2P These example settings belong in `config.toml`. Replace the angle-bracket listener placeholders with your chosen bind interfaces and use peer IDs from your network. Consensus options use hyphenated keys. ``` log-level = "info" log-format = "text" [rpc] laddr = "tcp://:26657" [p2p] laddr = "tcp://:26656" bootstrap-peers = "" persistent-peers = "" private-peer-ids = "" max-connections = 100 [mempool] broadcast = true size = 5000 max-txs-bytes = 1073741824 max-tx-bytes = 1048576 ``` `max-txs-bytes` limits total mempool bytes; `max-tx-bytes` limits one transaction. Use `bootstrap-peers` for initial discovery, `persistent-peers` for maintained connections, and `max-connections` for the combined peer limit. **Source:** `consensus/config/config.go` and `consensus/config/toml.go`. ## Application and EVM RPC These settings belong in `app.toml`. EVM options use underscores, unlike the consensus options above. The host and port are separate EVM fields. ``` minimum-gas-prices = "0.01uhpx" min-retain-blocks = 100000 occ-enabled = true [api] enable = true swagger = true address = "tcp://:1317" [grpc] enable = true address = ":9090" [evm] http_enabled = true http_address = "" http_port = 8545 ws_enabled = true ws_port = 8546 simulation_gas_limit = 10000000 ``` Replace the listener placeholders with your chosen bind interfaces. Set `http_address` and `http_port` for the EVM HTTP listener, and `ws_port` for the WebSocket listener. Configure public routing to match your deployment. The default worker count is twice the detected CPU count, clamped to 10–128. Override `concurrency-workers` only after measuring your workload. The node admission setting `minimum-gas-prices` is separate from the EVM module's on-chain fee parameters. **Source:** `rpc/config/config.go`, `rpc/server.go`, `sdk/server/config/config.go`, `daemon/paxd/cmd/root.go`. ## Storage and Retention Keep root-level settings before TOML section headers. State-store keys have the `ss-` prefix; state-commit keys have `sc-`. ``` # app.toml root setting min-retain-blocks = 100000 [state-commit] sc-enable = true sc-write-mode = "memiavl_only" [state-store] ss-enable = true ss-backend = "pebbledb" ss-keep-recent = 100000 [receipt-store] rs-backend = "pebbledb" ``` Archive mode sets both `min-retain-blocks` and `ss-keep-recent` to zero to preserve available history. Start from data covering the historical range you need. RocksDB is an optional SS backend that requires a compatible build; receipt storage uses Pebble. Storage routing modes control state migration. Select the mode specified by your chain's migration plan and existing data layout. See [Storage](https://docs.paxeer.app/storage). **Source:** `storage/config/toml.go`, `storage/config/sc_config.go`, `storage/config/ss_config.go`, `storage/config/receipt_config.go`. ## Snapshots and State Sync A snapshot provider sets `[state-sync]` in `app.toml`. A joining node enables `[statesync]` in `config.toml`. These are different roles. ``` # app.toml: application snapshot production [state-sync] snapshot-interval = 0 snapshot-keep-recent = 2 # config.toml: snapshot consumption [statesync] enable = false rpc-servers = "" trust-height = 0 trust-hash = "" ``` Snapshot interval zero disables periodic application snapshots. Before enabling a joining node, supply trusted RPC servers, a valid checkpoint height and hash, and the required trust period. See [Run a Node](https://docs.paxeer.app/run-node). ## Metrics ``` # config.toml [instrumentation] prometheus = true prometheus-listen-addr = ":26660" ``` Read `/metrics` on the configured listener. Application telemetry is configured separately in `app.toml` under `[telemetry]`. ## Validation Review generated files using the selected binary's help and configuration templates. Start the configured node with `paxd start`, check its startup logs, then confirm its chain identity and synchronization with `paxd status`. --- URL: https://docs.paxeer.app/consensus # Consensus Consensus service wiring, application execution, trusted headers, and validator signing state. ## Overview The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Paxeer mainnet-beta uses EVM chain ID 125. A receipt is final when validators commit its block. The tree includes a Tendermint-derived consensus stack and configurable Autobahn components; the application executes transactions and commits state. Network safety depends on the protocol's validator and trust assumptions, while observed block time and throughput depend on the deployed configuration. ## Autobahn and Validator Committees Autobahn uses application and lane proposals, votes, quorum certificates, committees, and timeouts. Their types are defined under `consensus/autobahn/types/`; the protocol state is coordinated under `consensus/internal/autobahn/`. Use the deployment's Autobahn configuration to inspect its lane and committee settings. Track throughput and block intervals through node metrics. **Source:** `consensus/autobahn/types/committee.go`, `consensus/autobahn/types/lane_proposal.go`, `consensus/autobahn/types/commit_qc.go`, `consensus/config/config.go`. ## Application Execution The node application registers `ProcessProposalHandler` and `FinalizeBlocker`. A proposal may begin optimistic work before finalization; finalized execution and successful commit establish the application result. Mempool acceptance and a returned submission hash are earlier stages. Transaction execution can use the standard scheduler or the configured Giga executor. The standard scheduler records multiversion accesses, validates dependencies, and retries conflicting tasks. After 10 iterations it reverts to sequential processing of remaining unvalidated work. Consensus establishes transaction ordering, while the execution scheduler manages parallel work and dependency validation. **Source:** `node/app.go` — `ProcessProposalHandler`, `FinalizeBlocker`, `ExecuteTxsConcurrently`; `sdk/tasks/scheduler.go` — `ProcessAll`. ## Node Services The `consensus/node/` package assembles peer networking, block and state stores, mempool, evidence handling, RPC, indexing, and application connections. The consensus configuration accepts `full`, `validator`, and `seed`. The paxd initializer also accepts archive, writes consensus mode full, and configures the application to retain available history. Sequencer mode cannot run with an `autobahn-config-file`; the configuration rejects that combination. See [Configuration](https://docs.paxeer.app/configuration) for node mode defaults and [Run a Node](https://docs.paxeer.app/run-node) for initialization. ## State and Synchronization Consensus state records validator sets, block identity, consensus parameters, and application commitment. State sync uses a trusted checkpoint and application snapshots to bootstrap a node without replaying all earlier blocks. Configure application snapshot production on provider nodes and state-sync consumption on joining nodes. Use the [storage configuration](https://docs.paxeer.app/storage) to retain the data and commitment history needed for queries and proofs. **Source:** `consensus/config/config.go` — `StateSyncConfig`; `consensus/internal/statesync/`; `consensus/internal/state/`. ## Light Client The light client checks new headers against a trusted header, validator set, trust period, and clock-drift rules. Non-adjacent verification checks the configured trusted-set overlap and requires more than two-thirds of the new validator voting power to sign the new header. Maintain a trusted checkpoint within the configured trust period. For historical application proofs, connect to a node retaining the corresponding commitment state. **Source:** `consensus/light/verifier.go` — `VerifyAdjacent`, `VerifyNonAdjacent`; `consensus/light/client.go`. ## Validator Signing File-based validators persist a signing key and a mutable last-sign state containing height, round, step, and signature data. Recovery must preserve both. Never run two active signers using the same validator key. Autobahn requires a local validator key and rejects remote signers. Do not configure a remote signer through the node's `[priv-validator]` configuration for an Autobahn validator. Equivocation handling can permanently tombstone a validator. Query the connected network's slashing parameters for its configured monetary penalties. **Source:** `consensus/privval/file.go`, `consensus/node/setup.go` — `createPrivval`; `sdk/x/evidence/keeper/infraction.go`. ## RPC and Metrics ``` curl -sS "$CONSENSUS_RPC_URL/status" curl -sS "$CONSENSUS_RPC_URL/net_info" curl -sS "$CONSENSUS_RPC_URL/consensus_params" ``` Set CONSENSUS_RPC_URL in your shell to the consensus listener for these examples. Consensus RPC and EVM JSON-RPC are separate listeners; the default consensus RPC port is 26657. The consensus metrics include height, validator last-signed height, missed-block gauges, block/state-sync state, and block intervals. Use the series emitted by your configured namespace when constructing alerts. **Source:** `consensus/internal/rpc/core/routes.go`; `consensus/internal/consensus/metrics.go`. ## Next Steps - [EVM execution engine](https://docs.paxeer.app/engine) - [Validator operations](https://docs.paxeer.app/operators) - [Network parameters](https://docs.paxeer.app/network-parameters) --- URL: https://docs.paxeer.app/contracts # Contracts Build Solidity applications on Paxeer X and integrate wrapped PAX, token pointers, and native precompile interfaces. ## Custody and settlement On Paxeer mainnet-beta, the LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it to settle transactions. Funding uses native bank balances and derived sub-accounts. The `LayerXCustody.sol` ABI is in `precompiles/layerxcustody/LayerXCustody.sol`; `contracts/src/precompiles/ILayerXCustody.sol` is a Solidity interface. Custody calls at `0x1013` are disabled on the merged network. The checkpoint anchor at `0x1014` is also disabled once its store-delete upgrade is active. Choose the interface for the native module your application uses and verify its authorization requirements. A deployed Solidity contract and a native precompile have distinct call targets and state. A receipt is final when its block is committed; see the [settlement guide](https://docs.paxeer.app/settlement) for related evidence. ### Native application composition Custody at `0x1013` and anchor at `0x1014` do not provide an application settlement path on the merged network. Native application interfaces include perpetuals at `0x1015`, bridge at `0x1016`, and launchpad at `0x1017`. The verification precompile at `0x1012` is disabled on the merged network. Fee-token selection uses `0x1018`, and XWeb requests use `0x1019`. Import the exact ABI or Solidity interface for each call and preserve integer units, authorization requirements, and event decoding. Combine [native denominations and token pointers](https://docs.paxeer.app/assets) with [bridged assets](https://docs.paxeer.app/bridge), or use the [XDK](https://docs.paxeer.app/xdk) to prepare calls and consume application events. ### Contract project boundaries Chain contracts under `contracts/src/` use `foundry.paxeer.toml` (sources `contracts/src`, tests `contracts/test`, artifacts `contracts/out`). The repository-root `foundry.toml` is a separate project (sources `contracts`, artifacts `build/forge-artifacts`) that explicitly skips `contracts/src/**` and `contracts/test/**`; its `tests/solidity/` suite covers governance and names. Select the configuration matching the contract family when compiling or testing. ## Start a New Application Follow the [Foundry](https://docs.paxeer.app/foundry) or [Hardhat](https://docs.paxeer.app/hardhat) walkthrough to compile, test, and deploy a contract on chain ID 125 (`hyperpax_125-1`). Continue with [Build a Frontend](https://docs.paxeer.app/building-a-frontend) to connect a browser wallet and read deployed state. The Paxeer X contract library provides Solidity interfaces and implementations for native token operations and Cosmos integration. Its sources live in `contracts/src/`. ## Wrapped PAX and Token Pointers | Contract | Use | | --- | --- | | `WPAX.sol` | Wrap native PAX in an ERC-20-style interface with 18 decimals | | `NativePaxTokensERC20.sol` | Read and transfer a native Cosmos denomination through an ERC-20 interface | | `CW20ERC20Pointer.sol` | Interact with a CW20 token through the ERC-20 interface | | `CW721ERC721Pointer.sol` | Interact with a CW721 collection through the ERC-721 interface | | `CW1155ERC1155Pointer.sol` | Interact with CW1155 multi-tokens through the ERC-1155 interface | ### Wrap and Unwrap PAX `WPAX.deposit()` accepts native PAX through `msg.value` and credits the caller’s WPAX balance. `withdraw(amount)` reduces that balance and returns native PAX. The contract also exposes transfers, allowances, and approval events for token integrations. Use the WPAX deployment address published for your target network. Read its `symbol()`, `decimals()`, and deployed bytecode before configuring an application integration. Keep native PAX available to pay transaction fees. ### Use a Token Pointer A pointer exposes an underlying Cosmos asset through familiar EVM token methods. The native-token implementation delegates balance, supply, and transfer operations to the bank precompile. CW pointers call the corresponding CosmWasm contract. Resolve the registered pointer and its version for the underlying denomination or contract. Use the [pointer and pointer-view precompiles](https://docs.paxeer.app/precompiles) for registration and discovery, then read the token’s metadata through its own ABI. ## Native Precompile Interfaces Import the Solidity interface matching the operation you need. These native precompiles use fixed addresses registered by Paxeer X; the interfaces are in `contracts/src/precompiles/`. | Interface | Address | Operations | | --- | --- | --- | | `IBank.sol` | `0x0000000000000000000000000000000000001001` | Native-token balances, supply, metadata, and transfers | | `IWasmd.sol` | `0x0000000000000000000000000000000000001002` | Instantiate, execute, and query CosmWasm contracts | | `IJson.sol` | `0x0000000000000000000000000000000000001003` | Extract bytes, byte arrays, and integers from JSON | | `IAddr.sol` | `0x0000000000000000000000000000000000001004` | Look up associated EVM and Cosmos addresses | For example, read the Cosmos address associated with an EVM account: ``` cast call 0x0000000000000000000000000000000000001004 \ 'getPaxAddr(address)(string)' "$ACCOUNT_ADDRESS" \ --rpc-url "$PAXEER_RPC_URL" ``` Set `ACCOUNT_ADDRESS` to an associated account. If the call reports a missing association, follow [Address Conversion](https://docs.paxeer.app/precompiles) to associate the account first. The reverse lookup is `getEvmAddr(string)`. ## Work with the Contract Library The repository includes Foundry and Hardhat tooling. Use the configuration for the artifact you are rebuilding and retain its compiler settings alongside the output. | Tool | Configuration | Project layout | | --- | --- | --- | | Foundry | `foundry.paxeer.toml` | Sources in `contracts/src/`, tests in `contracts/test/`, artifacts in `contracts/out/` | | Hardhat | `contracts/hardhat.config.js` | Hardhat 2 project with its dependencies and lockfile under `contracts/` | The Hardhat `paxlocal` network reads `PAXEER_LOCAL_EVM_RPC_URL` and defaults to a loopback HTTP listener on port `8545`. Start a [Paxeer development cluster](https://docs.paxeer.app/docker) for integration tests that call native precompiles or CosmWasm modules. Use the [Foundry](https://docs.paxeer.app/foundry) and [Hardhat](https://docs.paxeer.app/hardhat) guides for a complete new-project setup, including compiler configuration, local tests, and deployment commands. ### Choose the Relevant Tests - `CW20toERC20PointerTest.js` and `NativePaxTokensERC20Test.t.sol` cover token-pointer behavior. - `EVMCompatibilityTester.sol`, `TransientStorageTester.sol`, and `SelfDestructTester.sol` exercise EVM behavior. - `SstoreGasTest.sol` and `SnapshotRevertTester.sol` exercise storage gas and state restoration. - `MultiSender.sol` and `BatchCallAndSponsor.sol` support batch-call scenarios. ## Maintain Embedded Pointer Artifacts Chain-level pointer implementations include versioned ABI and bytecode artifacts under `modules/evm/artifacts/`. Go embeds these files into the node binary. When changing a pointer implementation: 1. Compile the contract using the intended compiler and optimizer settings, and run its contract tests. 2. Update the matching ABI and creation bytecode in the `native`, `cw20`, `cw721`, `cw1155`, `erc20`, `erc721`, `erc1155`, or `wpax` artifact package. 3. Update the pointer version and migration logic required by the release. Registry lookups select pointers by type, underlying asset, and version. 4. Rebuild `paxd` to embed the artifacts and exercise registration, transfers, and existing-pointer behavior in a development cluster. 5. Release the binary through the network’s upgrade process, including the migration for any existing deployed pointers. Application developers can use the registered pointer interface directly. Embedded-artifact updates are part of maintaining the chain implementation. ## Connect a Deployed Contract Obtain the address from your deployment output or the contract maintainer’s network-specific deployment record. Match your network's chain ID (125 on `hyperpax_125-1`), the contract ABI, and the deployed version before adding the address to your application. ``` cast chain-id --rpc-url "$PAXEER_RPC_URL" cast receipt "$TX_HASH" --rpc-url "$PAXEER_RPC_URL" cast code "$CONTRACT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" ``` Retain the creation transaction, source revision, compiler settings, constructor arguments, and ABI. For a proxy contract, also retain the implementation address and upgrade configuration. Continue with [Query the EVM](https://docs.paxeer.app/querying-evm) to read state and events. **Source:** `contracts/src/`, `contracts/hardhat.config.js`, `foundry.paxeer.toml`, `precompiles/`, and `modules/evm/artifacts/` with `modules/evm/keeper/pointer.go`. --- URL: https://docs.paxeer.app/custody # Account funding & key custody Fund accounts on the merged network, bind owner identities, and understand signing-key custody in the Human interface. ## Custody precompile behavior The `layerxcustody` precompile at `0x0000000000000000000000000000000000001013` is disabled on the merged network. Its 20 ABI methods, including `deposit`, `depositToken`, `requestWithdrawal`, `finaliseWithdrawal`, `requestForcedExit`, and `executeForcedExit`, revert with `LXP_MODULE_DISABLED: module disabled; layerxCustody retired`. The disabled-module check precedes call-shape checks. The ABI is declared in `contracts/src/precompiles/ILayerXCustody.sol`. Its deposit-root registration method, `registerDepositRoot`, and its views, including `depositCount`, `depositNonce`, `assetByPointer`, and `nativeAssetId`, are subject to the same runtime refusal. ## Account and transfer paths | Need | Current path | | --- | --- | | Establish an owner account | Bind the DID to the owner EVM address with `bindLayerX(bytes32, bytes)` through the address precompile at `0x0000000000000000000000000000000000001004`, then register identity and recovery through LayerXAuth. See [identity](https://docs.paxeer.app/identity). | | Fund an account on the merged network | Transfer the native asset directly to the bound EVM address. Development allocations use a signed native transfer; see the developer funding guide. | | Move value to or from an external chain | Use the governed bridge at `0x0000000000000000000000000000000000001016`, which requires registered chains, attestors, caps, and enabled policy. See [the bridge](https://docs.paxeer.app/bridge). | | Move funds inside the Human interface | Use a `move` journey and track its receipt and block commitment. | ## Signing-key custody The Human interface separates application authentication, protocol signing, and owner EVM authority: | Identity | Purpose | Signing authority | | --- | --- | --- | | Application identity | A passkey opens the Human application session. | Authenticates the application session; it is separate from the protocol key. | | Protocol identity | A LayerX DID authorizes native activities and account operations. | The custody service holds Human and managed-agent keys and signs disclosed activities. | | Owner EVM address | Binds the DID and submits Governance lifecycle transactions. | Signs the binding and lifecycle transactions on chain ID 125. | The browser does not hold the Human protocol identity's private key. The one exception is the explicit `export-primary-key` security action, which is the only route by which a DID primary key leaves the service; see [the Human interface](https://docs.paxeer.app/human-interface). ## Confirm account funding Confirm the DID-to-EVM binding before funding. Retain the transaction hash, inspect the native balance and receipt, and check the recipient and amount. The native funding path resolves the recipient through the address precompile and checks the transaction receipt. A funding reference alone does not establish a successful transfer. ## Show evidence accurately Human journeys report three rungs: `unverified` (submitted), `receipt-verified` (receipted), and `checkpoint-finalised` (committed). A receipt is final once its block is committed. Evidence returned by `GET /v1/evidence/{evidence_id}` includes its class, verification level, content type, and encoded bytes. Continue with [owner registration](https://docs.paxeer.app/identity), [the governed bridge](https://docs.paxeer.app/bridge), [block commitment and proof verification](https://docs.paxeer.app/settlement), and [Paxeer JSON-RPC](https://docs.paxeer.app/json-rpc). --- URL: https://docs.paxeer.app/data-availability # Data Availability Read block availability through the agent runtime and verify supplied batch archives with the proof library. ## Availability makes replay possible The proof library defines five batch availability classes. Given an authenticated availability root and provider chunks, a verifier authenticates the data before replay. This format describes supplied batch evidence; the agent runtime reads merged-node blocks through a separate availability operation. | Class | Contents | | --- | --- | | Activities (1) | Canonical accepted activities | | Receipts (2) | Canonical activity receipts | | Oracle (3) | Canonical signed oracle inputs | | StateDiff (4) | Canonical state-diff material | | Recovery (5) | Canonical recovery metadata | Chunks carry at most 65,536 bytes. Each chunk states its batch number, flattened bundle index, class, byte offset inside the class section, exact bytes and claimed digest. A chunk is accepted only when its metadata digest recomputes correctly and its Merkle inclusion path verifies under the data-availability root. Verified chunks must appear in strict flattened-index order. **Source:** `services/agent/crates/layerx-proof/src/availability.rs` — `AvailabilityClass`, `Chunk`, `VerifiedChunk`. ## Fetch and verify workflow 1. Obtain the committed data-availability root from evidence you already trust. 2. Fetch chunks for the batch from a provider. 3. For each chunk, recompute its digest and verify its inclusion path against the root. Refuse chunks from another batch, out-of-order chunks and digest mismatches. 4. Require complete bundle coverage and contiguous class offsets before complete-bundle verification. 5. Replay activities and oracle inputs; compare state roots and the recomputed account diff. 6. Attest only after replay reaches the exact committed result. ## Agent availability API The agent runtime exposes an `availability_fetch` operation. Its selector is a decimal block height. The request also carries a requested rung, `maximum_bytes`, `maximum_chunks` and a `deadline` in Unix seconds. Empty selectors, zero bounds and expired deadlines are refused. The implementation bounds transaction bytes and transaction count for the selected block. For an available block, the runtime returns a complete `transactions` class with transaction count and byte count, plus the height, transaction root and receipt root. A pruned block produces a partial report with a provider failure of `pruned`. Missing data does not represent an empty block. **Source:** `services/agent/crates/layerx-agent-api/src/read.rs` — `AvailabilityRequest`, `AvailabilityReport`; `services/agent/crates/layerx-agentd/src/human_runtime.rs` — `availability_fetch`. ## Block availability reads The merged-node reader checks the requested height against the node head and fetches that block. It returns the block's transaction root, receipt root and transaction count, or a pruned result when the block is absent. The runtime returns this block report separately from the proof library's five-class batch format. **Source:** `services/agent/crates/layerx-agentd/src/read/availability.rs`. ## Refusals and recovery Keep storage and proof failures as typed refusals. Chunk verification distinguishes batch mismatch, index mismatch, digest mismatch, inclusion failure, ordering failure and incomplete bundle coverage. Retry a retained selection or restore authenticated archive data; do not treat missing chunks as an empty batch or replace a verified root with an untrusted newer one. ## Ethereum and Solana mirrors Mirror archives extend independent access to batch history. `layerx-mirror-publisher` publishes archives to Ethereum or Solana, while `layerx-mirror-verify` checks a receipt obtained from an untrusted mirror archive without a hosted gateway. Verification validates the archive, binds its batch header to operator-configured trust, proves receipt inclusion and returns freshness. Archive provenance and freshness are separate from the receipt's signed outcome. Preserve the archive commitment, trusted header context, inclusion proof and checkpoint references for later audit. See [Receipts & Proofs](https://docs.paxeer.app/proofs) for portable offline verification and native state witnesses, or [Finality & Commitment](https://docs.paxeer.app/finality) for how data availability supports settlement. --- URL: https://docs.paxeer.app/debugging-transactions # Debug Transactions Diagnose reverted or missing Paxeer transactions with receipts, calldata, gas checks, traces, and reproducible local tests. Begin with the transaction hash, chain ID, and the endpoint that accepted the submission. Separate transport failures, rejected submissions, and transactions that executed with a reverted receipt; they require different next steps. ## Collect the transaction and receipt Set the shell placeholders `PAXEER_RPC_URL` and `TX_HASH`, then use Cast to inspect the recorded transaction. These commands only query the endpoint. ``` cast chain-id --rpc-url "$PAXEER_RPC_URL" cast tx "$TX_HASH" --rpc-url "$PAXEER_RPC_URL" --json cast receipt "$TX_HASH" --rpc-url "$PAXEER_RPC_URL" --json ``` | Observation | Meaning | Next check | | --- | --- | --- | | No transaction or receipt | The endpoint cannot find the hash | Confirm chain 125, the submission response, and whether the provider has indexed that height | | Transaction present, receipt absent | Execution is not yet visible through this endpoint | Check a known-good endpoint and the sender nonce before resubmitting | | Receipt status 0 | The transaction was included but execution reverted | Inspect the ABI, revert data, and execution trace | | Receipt status 1 | Execution succeeded | Compare emitted events and resulting application state with the intended action | A receipt is final when validators commit its block. A timeout after submission does not prove the transaction failed. Search for the original hash first; a new transaction can repeat the application action. ## Check the sender and call Read the sender’s native balance, nonce, and the current fee estimate. Set `SENDER_ADDRESS` to the sender recorded in the transaction and `CONTRACT_ADDRESS` to its target. The calldata example uses `store(uint256)` from `contracts/src/Box.sol`. ``` cast balance "$SENDER_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast nonce "$SENDER_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast gas-price --rpc-url "$PAXEER_RPC_URL" cast code "$CONTRACT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast calldata 'store(uint256)' 42 ``` Compare the encoded calldata to the transaction input. Confirm the contract address and ABI against the deployed version. PAX pays gas even when execution reverts. Increasing the gas limit will not repair a failed authorization check or invalid function argument. ## Simulate the exact inputs For the Box example, reproduce a call with the original sender and arguments. `cast call` uses `eth_call`; it does not persist storage changes. ``` cast call "$CONTRACT_ADDRESS" 'store(uint256)' 42 --from "$SENDER_ADDRESS" --rpc-url "$PAXEER_RPC_URL" ``` A call at `latest` tests current state. It may differ from the state at the time of the failed transaction. A call at the previous block is also only an approximation when earlier transactions in the same block changed relevant state. ## Trace historical execution If your provider enables the debug namespace and retains the required state, request a call trace. Inspect the failed frame, its input, revert data, and nested calls. ``` cast rpc debug_traceTransaction "$TX_HASH" '{"tracer":"callTracer","timeout":"30s"}' --rpc-url "$PAXEER_RPC_URL" ``` Provider policies and node versions determine available tracers. The node accepts `callTracer`, `prestateTracer`, and `flatCallTracer`. For a `-32601` response, use an endpoint with the debug namespace enabled. For a historical-state error, use a node retaining the requested height. See [Paxeer debug methods](https://docs.paxeer.app/json-rpc). ## Reproduce in a local test Write a minimal test using the exact contract version, sender, and arguments. For ordinary Solidity state, a fork pinned to a known block can help. Set `BLOCK_NUMBER` to that height and `ANVIL_RPC_URL` to your local Anvil endpoint: ``` anvil --fork-url "$PAXEER_RPC_URL" --fork-block-number "$BLOCK_NUMBER" # In another terminal, read the local fork. cast call "$CONTRACT_ADDRESS" 'retrieve()(uint256)' --rpc-url "$ANVIL_RPC_URL" ``` Use Anvil for ordinary Solidity contract state. For Cosmos modules, Paxeer precompiles, parallel scheduling, or consensus behavior, reproduce the issue with the matching Paxeer binary in a [development cluster](https://docs.paxeer.app/docker). The source RPC must retain the historical state needed by your fork. ## Keep a useful bug report - Transaction hash, chain ID, block number, and receipt status. - Contract address, exact source revision, ABI, compiler version, and optimizer settings. - Original sender, function arguments, value, gas parameters, and expected state transition. - Decoded error or failing trace frame and a minimal reproduction. - Provider type and node version when available; remove authentication tokens from URLs and logs. Reference: [Foundry Cast](https://getfoundry.sh/cast/overview/). Continue with [parallel execution design](https://docs.paxeer.app/parallelization) when the issue is contention or throughput rather than a revert. **Paxeer source:** `rpc/` — tracers.go (DebugAPI), tx.go (TransactionAPI), and simulate.go (SimulationAPI). --- URL: https://docs.paxeer.app/developer-funding # Developer funding and allocations Request a bounded development allocation, track its signed treasury transfer, and verify the funded account before your first Paxeer payment. ## Choose the right funding path The hosted allocation service distributes operator-approved development funds in its configured environment. A developer or agent authenticates, names a recipient identity and public key, and receives a funded result or a typed pending or refusal outcome. The service controls the allocation amount, treasury, eligibility, and quota policy. | Funding need | Mechanism | What the result establishes | | --- | --- | --- | | Approved developer allocation | Authenticated claim backed by a signed native EVM transfer | The configured environment allocated funds to the named identity | | Native account funding | Native transfer to the recipient EVM address | The transaction receipt and recipient balance | | External-chain transfer | Governed bridge with configured chains, attestors and caps | The bridge transfer evidence for the selected chain and asset | | Local account setup | Emulator prefunding | A local development balance for inspection scenarios | A development allocation is scoped to its environment and policy. Funding uses the recipient's DID-to-EVM address binding and requires that binding to resolve before transfer. Use the configured hosted gateway for allocation requests; its availability is separate from the public node JSON-RPC. ## Developer journey 1. Obtain access to the configured allocation environment and an active hosted identity session. 2. Create or select a recipient signing identity. Record its public DID and 64-hex Ed25519 public key, and bind that key to the recipient EVM address through the address precompile. 3. For a direct HTTP claim, choose and persist an idempotency key. Gateway claims bind idempotency to the principal and starter-credit grant. 4. Submit the claim and retain the funding identifier and transaction identifier. 5. Resolve pending outcomes under the same request key. 6. Verify the transfer receipt and recipient balance before sending a payment. ## Authentication and roles | Actor | Credential | Authority | | --- | --- | --- | | Developer or agent | Hosted identity session Bearer | Request an allocation subject to the session principal and quota policy | | Gateway service | Dedicated service-claim Bearer | Submit a claim naming the authenticated principal | | Allocation service | Identity introspection service credential | Validate the session and resolve its active principal | | Funding controller | Control-admin credential | Authorize the funding operation against the configured treasury | | Funding signers | EVM sender and treasury attestation authority | Sign the native EVM transaction and attest the durable funding intent | The caller's session token is introspected as request data; it is never reused as an upstream service authorization credential. The direct claim resolves an active session subject. The service claim accepts its separate configured credential and supplies a principal explicitly. Keep service and treasury credentials on trusted servers. ## Submit a direct claim ``` POST /v1/faucet/claims Authorization: Bearer Idempotency-Key: developer-allocation-order-01 Content-Type: application/json { "did": "did:layerx:", "public_key": "<64-hex-public-key>" } ``` The JSON body accepts only `did` and `public_key`. The allocation amount is configured by the service rather than chosen in the claim. Use the key-derived DID that the treasury funding path validates. `Idempotency-Key` is 1–128 characters from letters, digits, hyphen, underscore, dot, and colon. ### Service and JSON-RPC access A configured service caller uses `POST /v1/faucet/service-claims` with the same headers and a body containing exactly `principal`, `did`, and `public_key`. Direct and service requests for the same principal share its identity quota. The service route must be configured with its dedicated credential. ``` { "jsonrpc": "2.0", "id": 1, "method": "px_requestFunds", "params": ["did:layerx:", "<64-hex-public-key>"] } ``` The configured hosted gateway checks that the session authorizes the signer, obtains the principal's starter-credit grant, and submits a service claim. It requires the funded amount to match the grant before settling it. The `layerx faucet` CLI command, `faucet.request` tool and Rust `RpcClient::request_funds` call `px_requestFunds`. This is a hosted method rather than a public node method. ## Amounts and configurable ceilings The native funding path places the integer amount directly in the EVM transaction value, in wei. The response encodes the amount as a decimal string; the default claim is not a whole-PAX amount. | Configuration | Default | Meaning | | --- | --- | --- | | `LAYERX_FAUCET_CLAIM_AMOUNT` | 1,000,000 wei | Positive allocation size per accepted claim | | `LAYERX_FAUCET_IDENTITY_LIMIT` | 10,000,000 wei | Principal total per quota window | | `LAYERX_FAUCET_ADDRESS_LIMIT` | 10,000,000 wei | Recipient public-key total per quota window | | `LAYERX_FAUCET_NETWORK_LIMIT` | 50,000,000 wei | Network bucket total per quota window | | `LAYERX_FAUCET_WINDOW_SECONDS` | 86,400 seconds | Allocation quota window | | `LAYERX_FAUCET_NETWORK_REQUEST_LIMIT` | 60 requests | Network admission ceiling | | `LAYERX_FAUCET_NETWORK_REQUEST_WINDOW_SECONDS` | 60 seconds | Admission-count window | | `LAYERX_FAUCET_IDEMPOTENCY_SECONDS` | 604,800 seconds | Request retention; must cover the quota window | These are service configuration defaults, not a promised allowance for every deployment. The gateway additionally bounds its claim request rate at 30 per minute. The direct service derives network admission from the TCP peer; service claims use a principal-scoped network bucket. Forwarded identity or IP headers are refused rather than trusted as quota authority. ## Signed canonical funding The allocation service reserves quota and an idempotency record atomically, then sends its controller a funding command containing `funding_id`, `did`, `public_key`, and `amount`. The core constructs an EIP-1559 native transfer from its configured EVM sender to the address bound to the recipient public key on chain ID 125. Preparation reads the sender's pending nonce, gas price and priority-fee estimate, then estimates transfer gas. The signed funding record binds the raw transaction, hash, sender, recipient, amount and chain ID. The core persists a treasury-authorized intent before broadcasting, so recovery can reuse the signed transaction. The core broadcasts with `eth_sendRawTransaction` and reads `eth_getTransactionReceipt`. It checks the confirmation against the saved transfer before returning a funded result. A failed receipt produces a refusal; an unavailable receipt remains pending. The source account must hold the transferred value and gas funds. ## Response verification and recovery ``` { "funded": true, "funding_id": "", "transaction_id": "", "amount": "1000000", "network": "layerx-testnet" } ``` This illustrates the default claim amount and the service's fixed `layerx-testnet` response label. Verify the transfer's chain ID separately; the label does not select a chain. Direct HTTP success is an unwrapped body rather than an `ok` envelope; its transaction identifier is optional at that layer. The gateway additionally requires a transaction identifier and a complete funded response before returning JSON-RPC success. Retain the returned identifiers and verify the transaction receipt, recipient, value, status and chain ID. Confirm the recipient's native balance with `eth_getBalance` at the node; hosted `px_getAccount` and `px_getBalances` provide account views. A receipt is final once its block is committed. A funding identifier is a correlation reference. ``` HTTP/1.1 202 Accepted Retry-After: 10 { "state": "still_checking", "retry": "after", "retry_after_seconds": 10 } ``` Repeat the original claim with the same idempotency key and unchanged body after the carried delay. The service recovers the same funding identifier. A stored funded response is replayed; a different request digest under the same key returns `409 idempotency_conflict`. The gateway maps pending allocation to JSON-RPC `-32001` with `faucet_claim_pending`, never a funded result. ## Typed refusals | HTTP | Code | Resolution | | --- | --- | --- | | 400 | `idempotency_key_required`, `invalid_idempotency_key`, `invalid_argument` | Correct the request before retrying | | 400 | `untrusted_identity_header` | Remove caller-supplied forwarded identity headers | | 401 | `identity_required`, `service_token_required` | Authenticate with the correct credential for the route | | 409 | `idempotency_conflict` | Recover the original request rather than modifying its body | | 429 | `network_request_rate`, `identity_quota`, `address_quota`, `network_quota` | Respect the supplied retry delay and configured allowance | | 503 | `identity_unavailable`, `persistence_unavailable` | Retain the request key while dependencies recover | | 503 | `funding_rejected` | Inspect the destination and treasury funding refusal | ## Owner operations Configure the allocation amount and caps, supply a funded EVM sender with gas balance, and provision separate identity, service-claim, and control credentials. Persist quota and idempotency state in the configured TLS Redis service. Keep the funding journal durable across controller restarts and retain its request digest bindings. The service exposes `GET /livez` for process liveness and `GET /readyz` for Redis readiness. A ready response establishes Redis availability; independently monitor identity introspection, controller connectivity, treasury balances, and receipt recovery. Its hash-chained allocation audit records event, result, and funding reference without recording authentication values. ## Continue building - [Send your first payment](https://docs.paxeer.app/payments-quickstart) - [Account funding and key custody](https://docs.paxeer.app/custody) - [Asset metadata and account balances](https://docs.paxeer.app/assets) - [Execution fees and fee limits](https://docs.paxeer.app/fees) - [Public payment API](https://docs.paxeer.app/platform-api) --- URL: https://docs.paxeer.app/discovery # Program Discovery Discover registered programs and resolve current interfaces, lifecycle, accounts and signed deployment provenance. ## Resolve evidence before execution Paxeer X discovery lets wallets, agents and applications find registered programs and inspect the version they are about to call. The hosted registry combines deployment records, a verified current protocol head and published interfaces. Each resolved program carries identity, version and freshness information that the client can bind to its preparation. A program ID is a stable 32-byte identifier. The latest code hash, ABI, lifecycle and account bindings describe its current verified execution context. An application preserves both the stable identity and the version-specific evidence when presenting an action to its user. ## Start with the registry index ``` GET /v1/programs/registry Authorization: Bearer Response fields: program_ids state_root observed_sequence observed_at valid_through verification = "registry-receipt-and-current-head-verified" ``` Direct calls use the registry's mutual TLS connection and request credential. The index synchronizes protocol state and checks journal read authority before returning registered IDs. Its authenticated head and freshness window describe the observation used for that response. ### Resolve one program ``` GET /v1/programs/registry/<64-hex-program-id> GET /v1/programs/registry/<64-hex-program-id>/interface ``` The first response includes versions, current lifecycle, upgrade policy, account bindings, source status and deployment receipts. The interface response binds canonical interface bytes and their digest to a specific program, version, code hash and ABI. Its verification marker is `deployment-interface-and-current-head-verified`. ## What a resolver checks | Check | Required relationship | | --- | --- | | Program identity | The returned program ID equals the requested 32-byte identity. | | Deployment | The selected version has a verified deployment receipt and matching code hash. | | Interface | Interface version, code hash and ABI match the selected current deployment. | | Lifecycle | The application handles active, deprecated and tombstoned status deliberately. | | Freshness | The current time remains inside `valid_through` for the verified observation. | | Value accounts | Account bindings and balance proofs match program state and the observed head. | | Source | A verified source claim reproduces the deployed artifact under its named environment. | Resolve related records against compatible current evidence. If an upgrade or lifecycle change occurs between reads, fetch the program and interface again before preparing a call. Keep the canonical interface digest and code hash attached to the user-facing disclosure or internal execution record. ## Node discovery with the CLI The CLI reads the programs precompile through `eth_call` at `pending`. `layerx program discover` returns the program ID, upgrade policy, authority, code hash, ABI version, version and active status. Discovery refuses an inactive program. | Node discovery field | Meaning | | --- | --- | | `policy` | The program's upgrade policy value. | | `authority` | The 32-byte program authority. | | `code_hash` | The code hash returned for the selected program. | The hosted registry returns `deployment_receipt_digest` with current-head metadata. The CLI's node read returns `source: eth_call` and `block_tag: pending`. Keep these evidence types distinct when presenting an action. ### Evidence requirements A pending node view describes the state available for preparation. Establish a committed result from the execution receipt and independently verified block-commit evidence. Display the verification level established by the returned evidence. ## Application journey 1. Fetch the registry index and retain its observed head and validity bound. 2. Resolve the chosen program and inspect its current version, lifecycle and upgrade authority. 3. Fetch the matching interface and validate its program, ABI, code hash and interface digest. 4. When using the CLI, resolve the active program and matching interface through the selected node. 5. Resolve program accounts and source provenance relevant to the intended action. 6. Prepare the activity and disclose the target program, action, amounts, counterparties and fees. 7. Track execution and retain the resulting receipt alongside the discovery evidence. For example, a treasury agent discovers a payment program, confirms its current ABI and active lifecycle, checks its permitted assets and accounts, then prepares a bounded payment under its capability and budget. A changed version or stale discovery window triggers a fresh resolution before signing. ## Lifecycle and account-aware discovery Immutable programs advertise an immutable upgrade policy. Upgradeable programs identify their authority and preserve a numbered deployment history. Lifecycle history and exit routes let applications explain changes and route users through appropriate recovery or withdrawal journeys. ABI 1 programs without value accounts declare `account-incapable-abi1`. Account-capable records supply proof-verified bindings and balances. Account profile 2 includes the owner established by its verified state. Resolve these bindings directly instead of inferring account ownership from names or UI labels. ## Source and publisher identity Source verification links a mirrored archive, reproducible build environment and artifact digest to a verified deployment. Publication keys resolve through hosted identity, associating publication with a principal. Source status and publisher identity complement execution evidence: application trust policy decides whether a source verdict or publisher binding is required for a particular interaction. Use the [registry source workflow](https://docs.paxeer.app/registry) to publish archives and request verification. Preserve source digest, environment digest and deployment provenance when reviewing releases or generating a program catalog. ## Operate a discovery service Back discovery with the canonical deployment journal, authenticated node-state connection and independent receipt authority. Keep the node receipt authority and its trust history current. Synchronization persists verified program state before advancing its cursor, and refuses regressions or incompatible state. Restart replay reconstructs the projection from committed evidence and refreshes its current head. The default registry staleness bound is 300 seconds. Cache records with their `valid_through`, state root and version; revalidate before an economic action. A healthy HTTP listener does not itself establish fresh program evidence. | Result | Resolver behavior | | --- | --- | | `404 not_found` | Treat the program as absent from this verified registry view. | | `404 interface_absent` | Do not invent an interface; require published current-version metadata. | | `503 stale_read`, `protocol_head_unavailable` | Refresh evidence before preparing a new action. | | `interface_registry_mismatch`, `balance_registry_mismatch` | Reject inconsistent records and resolve matching evidence. | | Inactive node discovery result | The CLI refuses discovery when `active` is false. | Continue with [registry deployment and journals](https://docs.paxeer.app/registry), [owner identity](https://docs.paxeer.app/identity) or [agent spending controls](https://docs.paxeer.app/agent-budgets). **Technical references:** `services/platform/hosted/registry/src/routes.rs`, `services/platform/hosted/registry/src/head_attestation.rs`, `services/platform/hosted/registry/src/node_state.rs` and `tools/platform/cli/src/programs.rs`. --- URL: https://docs.paxeer.app/docker # Docker Development Local Docker clusters, state-sync RPC nodes, and monitoring for Paxeer X development and testing. **Source:** `docker/`, `Makefile`, `chain.mk` (monorepo root) ## Containers for the complete Paxeer X stack Chain development containers cover EVM and Cosmos execution. The monorepo also provides images for the kernel, hosted gateway and core, receipt authority, registry, agent boundary, Human services, bridge relayer, and application surfaces. See [archive access](https://docs.paxeer.app/relay-archive) for retained evidence and mirrors. | Image source | Role | | --- | --- | | `docker/localnode/` | Local chain node, genesis tooling and process supervision | | `docker/platform-gateway/` and `docker/platform-core/` | Public receipt-verifying ingress and internal core boundary | | `docker/platform-authority/` and `docker/platform-agent-boundary/` | Receipt authority and agent authorization boundary | | `docker/platform-registry/` and `docker/human-service/` | Discovery registry and Human service components | | `docker/bridge-relayer/` | Bridge delivery | Hosted manifests under `services/platform/hosted/` define the service topology, persistent storage, probes, and infrastructure boundaries. The chain Docker Compose files below run their declared development topology; hosted services have their own configuration and dependencies. Mount persistent state separately from runtime sockets and credentials. Pin image revisions and matching genesis artifacts. Publish the gateway through TLS ingress and keep core administration, signer channels, and node-local listeners private. Check `/readyz` and `/livez` where the selected service defines them, then verify an application receipt and its block-commit evidence. See [operator roles](https://docs.paxeer.app/operators) and [settlement](https://docs.paxeer.app/settlement). ## Prerequisites ### macOS Install Docker Desktop from [docs.docker.com/desktop/install/mac-install/](https://docs.docker.com/desktop/install/mac-install/) ### Ubuntu Install Docker Engine and Docker Compose: - Docker: [docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/) - Docker Compose: [docs.docker.com/compose/install/other/](https://docs.docker.com/compose/install/other/) ## Four-Node Local Cluster The base Compose file declares four validators on the `localnet` bridge. Each local node process requires `LOCALNODE_DISPOSABLE=1` and the same fresh `LOCALNODE_RUN_ID`, a 16–128 character identifier starting with a letter or digit and containing only letters, digits, hyphens and underscores. Supply these through the container environment in your local deployment configuration. ### Cluster Recipes ``` # Cluster recipe: rebuild the localnode image and initialize node state make docker-cluster-start # Rebuild the image but reuse an existing paxd binary make docker-cluster-start-skipbuild ``` The recipes invoke `docker/docker-compose.yml`, which declares four `pax-node-*` containers and `x-websearch` (`pax-x-websearch`). Set `X_WEBSEARCH_HOME` to its configured data directory. Image selection uses `LOCALNODE_IMAGE_TAG` and `X_WEBSEARCH_IMAGE_TAG`. The node coordinator stores genesis, node homes and logs under `build/localnode-runs//`. These recipes stop the cluster and remove `build/generated/` before starting. ### Published Host Ports | Node | P2P | RPC | gRPC / gRPC-web | EVM RPC | Additional TCP port | | --- | --- | --- | --- | --- | --- | | node0 | 26656 | 26657 | 9090-9091 | 8545-8546 | 26658 | | node1 | 26659 | 26660 | 9092-9093 | 8547-8548 | 26661 | | node2 | 26662 | 26663 | 9094-9095 | 8549-8550 | 26664 | | node3 | 26665 | 26666 | 9096-9097 | 8551-8552 | 26667 | ### Monitor Logs ``` # Tail logs for node 0 tail -f "build/localnode-runs/$LOCALNODE_RUN_ID/logs/paxd-0.log" # View all logs ls -l "build/localnode-runs/$LOCALNODE_RUN_ID/logs/" ``` ### Open a Container Shell ``` # List containers docker ps -a # Open a shell in a node docker exec -it pax-node-0 /bin/bash ``` ### Environment Variables The Compose file passes the following settings to the nodes. The Make cluster recipes set `NUM_ACCOUNTS=10`; the initialization script defaults to 5 when it is unset. | Variable | Purpose | | --- | --- | | `NUM_ACCOUNTS` | Number of development accounts to create | | `SKIP_BUILD` | Skip binary rebuild | | `INVARIANT_CHECK_INTERVAL` | State invariant check frequency | | `UPGRADE_VERSION_LIST` | Upgrade version list passed through the node environment | | `MOCK_BALANCES` | Use mock balance data | | `GIGA_EXECUTOR` | Enable Giga executor backend | | `GIGA_OCC` | Enable optimistic concurrency control | | `RECEIPT_BACKEND` | Receipt storage backend | | `AUTOBAHN` | Enable Autobahn optimizations | | `GIGA_STORAGE` | Use test_only_dual_write with the EVM state-store split | | `GIGA_MIGRATE_FROM_MEMIAVL` | Start in memiavl_only mode for a migration scenario | | `GIGA_FLATKV_ONLY` | Start in flatkv_only mode; cannot combine with GIGA_MIGRATE_FROM_MEMIAVL | ## Single Node (Not Recommended) The single-node recipe builds its image and launches one container. Its node process requires the same explicit disposable-run environment described above: ``` make run-local-node ``` Use multiple validators when examining consensus behavior. ## Compose Files | File | Purpose | | --- | --- | | `docker/docker-compose.yml` | Four-node cluster (base configuration) | | `docker/docker-compose.monitoring.yml` | Prometheus + Grafana monitoring overlay | | `docker/docker-compose.giga-mixed.yml` | Giga executor with OCC on node0 and standard execution on nodes1–3 | ## Monitoring with Prometheus & Grafana The monitoring overlay requires `GRAFANA_ADMIN_PASSWORD_FILE` to name a private password file. These recipes start and stop the cluster with the monitoring overlay: ``` # Start cluster + monitoring together make docker-cluster-start-monitoring # Stop cluster + monitoring together make docker-cluster-stop-monitoring ``` The standalone monitoring scripts use separate configuration under `docker/monitornode/`. Their Prometheus listener uses port 9091; select them separately from the Compose overlay, whose Prometheus host port is 9099: ``` # Start Prometheus ./docker/monitornode/scripts/start-prometheus.sh # Start Grafana ./docker/monitornode/scripts/start-grafana.sh # Stop ./docker/monitornode/scripts/stop-prometheus.sh ./docker/monitornode/scripts/stop-grafana.sh ``` ### Access UIs - **Grafana:** `3000`, using the configured password - **Prometheus:** `9099` for the Compose overlay; `9091` for the standalone script ## State Sync RPC Node RPC initialization requires `STATE_SYNC_RPC_SERVERS`, `STATE_SYNC_TRUST_HEIGHT` and `STATE_SYNC_TRUST_HASH` in the RPC container environment, plus a matching genesis at `build/generated/genesis.json`. It validates the selected checkpoint against the configured providers: ``` # Build the RPC-node image make build-rpc-node # RPC-node recipe, after supplying its container configuration make run-rpc-node ``` State sync restores a trusted snapshot and then replays subsequent blocks. Select a retained snapshot height and matching 32-byte hexadecimal trust hash; there is no fixed 500-block startup threshold. **Scripts:** `docker/rpcnode/scripts/` ## Fast Iteration & Local Development The node containers mount the source tree and Go caches. The declared image and cluster recipes support this workflow: 1. Edit code at the monorepo root (modules, consensus, SDK, storage, WASM) 2. Rebuild the node image: `make build-docker-node` 3. Restart the cluster: `make docker-cluster-start` The root `go.mod` declares module dependencies and replacements. External Go modules, base images and system libraries must also be available to the build. ### Volumes The compose files mount: - `$PROJECT_HOME` → `/pax-protocol/pax-chain` (source tree) - `$GO_PKG_PATH/mod` → `/root/go/pkg/mod` (Go module cache) - `$GOCACHE` → `/root/.cache/go-build` (Go build cache) ## Deployment Scripts Each node type has a multi-step initialization flow: ### Local Node - `step0_build.sh` — Build `paxd` binary - `step1_configure_init.sh` — Initialize node configuration - `step2_genesis.sh` — Generate genesis file - `step3_add_validator_to_genesis.sh` — Add validator to genesis - `step4_config_override.sh` — Override config files (ports, peers) - `step5_start_pax.sh` — Start `paxd` - `deploy.sh` — Orchestrates all steps ### RPC Node - `step0_build.sh` — Build `paxd` - `step1_configure_init.sh` — Initialize for state-sync - `step2_start_pax.sh` — Start with state-sync enabled - `deploy.sh` — Orchestrates RPC node setup **Scripts:** `docker/localnode/scripts/`, `docker/rpcnode/scripts/` ## Docker Image The `build-docker-node` target builds `docker/localnode/Dockerfile` and tags the image for local use and the Compose reference. `chain.mk` selects `linux/arm64` when `uname -m` reports arm64, otherwise `linux/amd64`. `DOCKER_PLATFORM` overrides that selection. ## Network Configuration The base Compose file declares a `localnet` bridge with fixed per-node addresses for peer configuration. Its published host port ranges map to the same internal node ports; application clients select the appropriate published RPC port. --- URL: https://docs.paxeer.app/emulator # Local Protocol Emulator Inspect local protocol state with explicit signing identities, account prefunding, time controls and snapshots. ## What the emulator provides The emulator wraps the native core for local inspection and account setup. Its surface document declares the available routes and reports `payments.supported: false`. Local prefunding, time controls and snapshots support repeatable inspection scenarios. Payment and program execution use the merged node. | Surface | Purpose | | --- | --- | | `GET /healthz` | Check local readiness. | | `GET /v1/sequencer` | Read the advertised native network ID and sequencer public key. | | `POST /__emulator/accounts/prefund` | Establish local development funding through emulator account tooling. | | `GET /v1/state`, `GET /v1/protocol/account-state/head` | Inspect local state; the account-state head route returns HTTP 503 with `principal_state_proof_unavailable`. | | `GET /v1/dids/{did}/sequence` | Read an identity sequence. | | `POST /__emulator/time/set`, `POST /__emulator/time/advance` | Set or advance local protocol time for deterministic scenarios. | | `POST /__emulator/faults` | Inject a fault for failure-path testing. | | `GET` / `PUT /__emulator/snapshot` | Export or import an emulator snapshot. | | `GET /v1/surface` | Read the route list and declared execution capabilities. | | Payment execution | Use merged-node `eth_sendRawTransaction` and `pax_sequencerReceipt`. | | Local receipt reads | Existing receipt entries return HTTP 410; an unknown receipt returns HTTP 404. | ## Provision a sequencer identity ``` layerx --json emulator provision ``` Provisioning generates a sequencer seed from operating-system randomness and publishes its public trust anchor. It creates `emulator/sequencer.seed` and `emulator/sequencer.anchor` under the CLI profile directory using owner-only storage and atomic identity publication. Retain the paths returned by the command. The seed is secret; the anchor is the public verification identity. Existing files cause `sequencer_seed_exists` or `sequencer_trust_anchor_exists`. Use `layerx emulator provision --force` only when deliberately replacing the local identity, then rebind clients to the new anchor. ## Start the gateway ``` layerx emulator up --listen --network-id 402 --sequencer-seed-file ``` Run the gateway in a dedicated terminal. Set the listener to a loopback socket; its default port is 9402. Emulator control routes provide local development authority. Network ID 402 is the local default, separate from the merged network's EVM chain ID 125. Network ID zero is reserved. | Option | Use | | --- | --- | | `--sequencer-seed-file` | Required provisioned signing seed. | | `--listen` | Choose an IP socket address on loopback. | | `--network-id` | Bind activities and client handshake to a local native network. | | `--protocol-version` | Select protocol version 2 or 3; the default is 2. | | `--time-ms` | Choose the local protocol time in milliseconds for deterministic scenarios. | | `--prefund` | Repeat a DID, public key and amount tuple for initial local account funding. | ## Bind the CLI to that identity ``` layerx environment use emulator --endpoint --network-id 402 --sequencer-trust-anchor-file layerx --json environment current ``` Supply endpoint, network ID and one trust-anchor input together. The CLI waits for the listener and reads `/v1/sequencer`, then checks the network and public identity before accepting the profile. A profile can also use `--sequencer-trust-anchor ` in place of the file. Subsequent selection uses `layerx environment use emulator`. ### Diagnose handshake failures | Code | Resolution | | --- | --- | | `environment_input_missing` | Provide the complete endpoint, network and anchor set. | | `sequencer_identity_unavailable` | Start the listener and confirm the endpoint and identity route. | | `network_id_mismatch` | Match client configuration to the running emulator network. | | `sequencer_trust_anchor_mismatch` | Use the public anchor corresponding to the running sequencer seed. | | `sequencer_trust_anchor_unreadable`, `sequencer_trust_anchor_malformed` | Correct the anchor path or public-key encoding. | ## Create development accounts ``` layerx key create payer layerx key default payer layerx account create --key payer --initial-amount 1000000 layerx key create payee layerx account create --key payee --initial-amount 0 layerx account get --did ``` Key creation stores secret material in the selected credential store. Account creation in the emulator uses its prefunding route. Read public DIDs and account identifiers from the returned metadata instead of inventing bindings. This account setup is local to the emulator; it does not fund an EVM address on the merged network. ### Prefund at startup ``` layerx emulator up --sequencer-seed-file --prefund ',<64-hex-public-key>,1000000' ``` Prefunding binds the supplied DID and 32-byte public key to the local account setup. The amount accepts a decimal low component or an explicit high:low pair. Keep the signing key, public binding and DID consistent across setup and activity construction. ## Read merged-network receipts ``` layerx --json --rpc receipt get <0x-prefixed-transaction-hash> ``` Point `--rpc` at the merged node's root JSON-RPC origin. `receipt get` calls `pax_sequencerReceipt` with the transaction hash. Preserve the response and independently verify its receipt authority and block-commit evidence. A receipt is final once its block is committed. ## Build programs and query the merged node ``` layerx new local-program layerx program build --manifest-path local-program/Cargo.toml layerx --rpc program discover layerx --rpc program interface get ``` Scaffolding and building create local artifacts. Discovery and interface reads query the program precompile through the selected node. Program lifecycle transactions, simulation and calls use the merged network rather than the emulator's inspection routes. Preserve code hashes, ABI versions, interface digests and execution receipts. ## Move the application to a hosted profile Keep emulator prefunding and local signing keys in the development environment. Configure the node origin for merged-network commands and a hosted profile for authenticated hosted APIs. A2A installation uses a hosted beta or production profile; MCP installation follows its enrolled daemon binding. Continue with [the CLI reference](https://docs.paxeer.app/cli), [platform API](https://docs.paxeer.app/platform-api), [A2A agents](https://docs.paxeer.app/a2a) and [Programs](https://docs.paxeer.app/wasm-runtime). --- URL: https://docs.paxeer.app/engine # Engine Paxeer's EVM execution engine, transaction processing, and state transition management. **Source:** `engine/` ## Overview The engine package provides EVM transaction execution for Paxeer. It wraps go-ethereum's EVM with Paxeer-specific precompiles, state management, and fee handling. The engine sits between the consensus layer (which orders transactions) and the EVM module (which manages on-chain state). ## Executor **Source:** `engine/executor/` The executor wraps EVM execution with separate constructors for the Geth interpreter and the EVMC backend. ### Executor Types The `Executor` struct in `engine/executor/executor.go` supports two backends: - **Geth Executor:** Uses go-ethereum's native EVM interpreter - **Evmone Executor:** Uses the evmone C++ VM via EVMC bindings for performance ``` // From engine/executor/executor.go type Executor struct { evm *vm.EVM } func NewGethExecutor(blockCtx vm.BlockContext, stateDB vm.StateDB, chainConfig *params.ChainConfig, config vm.Config, customPrecompiles map[common.Address]vm.PrecompiledContract) *Executor func NewEvmoneExecutor(evmoneVM *evmc.VM, blockCtx vm.BlockContext, stateDB vm.StateDB, chainConfig *params.ChainConfig, config vm.Config, customPrecompiles map[common.Address]vm.PrecompiledContract) *Executor ``` ### Transaction Execution The executor provides two execution modes: #### Standard Execution ``` func (e *Executor) ExecuteTransaction(tx *types.Transaction, sender common.Address, baseFee *big.Int, gasPool *core.GasPool) (*core.ExecutionResult, error) ``` Standard execution converts the transaction into an internal message and calls go-ethereum’s ApplyMessage, including its gas purchase and refund handling. #### Fee-Already-Charged Execution ``` func (e *Executor) ExecuteTransactionFeeCharged(tx *types.Transaction, sender common.Address, baseFee *big.Int, gasPool *core.GasPool) (*core.ExecutionResult, error) ``` This mode assumes fees were already charged before execution. It skips fee deduction and refund. This is the mode the node Giga execution path uses for `MsgEVMTransaction` transactions. ### Internal Components **Source:** `engine/executor/internal/` Internal execution utilities: - **Host context** (`host_context.go`): EVMC host context for evmone integration - **Interpreter** (`interpreter.go`): EVM opcode interpreter wrapper - **Message** (`message.go`): internal execution message handling ## Precompiles **Source:** `precompiles/`; `engine/executor/precompiles/failfast.go` Paxeer-specific precompiled contracts live in the top-level `precompiles/` package and are registered with the executor at initialization. The executor passes the `customPrecompiles` map to the EVM, which routes calls to the registered precompile addresses. The `engine/executor/precompiles/` directory itself contains only the fail-fast wrapper (`failfast.go`) and its tests. See [Precompiles documentation](https://docs.paxeer.app/precompiles) for the full list of Paxeer precompiles (bank, staking, oracle, pointer, etc.). ## Dependencies (xbank, xevm) **Source:** `engine/deps/` The engine depends on Cosmos SDK modules via thin wrappers in `engine/deps/`: ### xbank `engine/deps/xbank/` wraps the SDK bank module for balance operations: - **Send:** Transfer tokens between accounts - **View:** Query balances and supply - **Deferred Cache:** Batch balance updates before commit ### xevm `engine/deps/xevm/` wraps the EVM module keeper: - **State:** EVM storage access (accounts, code, storage slots) - **Code:** Contract bytecode storage and retrieval - **Receipt:** Transaction receipt generation - **Address:** Cosmos ↔ EVM address association - **Nonce:** Account nonce management - **Fee:** Gas price and fee collection - **Coinbase:** EVM coinbase address and fee-collector lookup - **Precompile:** Precompile address registration ## Configuration **Source:** `engine/executor/config/` The Giga executor configuration carries two flags, both defaulting to `true`: - **`giga_executor.enabled`:** whether the Giga executor is used - **`giga_executor.occ_enabled`:** whether optimistic concurrency control (OCC) is used with the Giga executor ``` # app.toml [giga_executor] enabled = true occ_enabled = true ``` Chain configuration (chain ID 125, fork activation) and the custom precompile address map are supplied to the executor constructors by the caller. They are not fields of this executor config. ## Testing **Source:** `engine/tests/` The engine includes state-transition tests and an execution harness: - **State Tests:** `state_test.go` runs Ethereum state transition tests - **Harness:** `engine/tests/harness/` provides test fixtures and builders - **Giga Test:** `giga_test.go` for large-scale execution ## Chain ID The chain configuration maps the Cosmos identifier `hyperpax_125-1` to **EVM chain ID 125**. Transactions on that network must use chain ID 125 for EIP-155 replay protection. Unmapped Cosmos identifiers also return the default EVM chain ID 125 in `modules/evm/config/config.go`. Check the configured network as well as the numeric chain ID. ## Utilities **Source:** `engine/executor/utils/` The utils package (`errors.go`) defines the Giga abort sentinel (`giga_fallback_to_v2`). `ShouldExecutionAbort` checks whether a `vm.AbortError` requests an abort, allowing the caller to select the standard (V2) execution path. ## Integration with EVM Module EVM transactions arrive as `MsgEVMTransaction` messages. On the Giga execution path, the node application (`node/app.go`) constructs a geth executor with `NewGethExecutor` and calls `ExecuteTransactionFeeCharged`, because fees have already been charged before execution. The flow is: 1. Consensus orders transactions in a block 2. Block processing routes `MsgEVMTransaction` to the EVM execution path 3. Ante processing validates the transaction and charges fees 4. The Giga path constructs the executor and calls `ExecuteTransactionFeeCharged` 5. The executor runs EVM bytecode against the state DB 6. The EVM module generates the receipt and emits events See [EVM Module documentation](https://docs.paxeer.app/evm) for the full message handling flow. ## Next Steps [Design for Parallel Execution](https://docs.paxeer.app/parallelization) explains how application storage layout affects contention and how to measure a change without confusing gas usage with network throughput. - [Understand the EVM module](https://docs.paxeer.app/evm) - [Review Paxeer precompiles](https://docs.paxeer.app/precompiles) - [Use the JSON-RPC API](https://docs.paxeer.app/json-rpc) --- URL: https://docs.paxeer.app/escrow # Escrow and Conditional Payments Reserve funds, capture milestone payments, refund unused balances, and resolve disputes through native Paxeer X escrow. ## Payment Guarantees for Agent Commerce Escrow separates a payment commitment from its final distribution. An agent owner funds a dedicated escrow account from its main account, a named beneficiary captures funds under the agreement, and a named arbiter resolves disputes. Marketplaces, service purchases, procurement, and milestone contracts use the same protocol lifecycle. The escrow module stores the agreement terms and lifecycle. Every movement of value uses the shared `402LXP` transfer mechanism, including funding, beneficiary payments, refunds, and dispute splits. The account namespace is `agent::escrow:`. ## Define an Escrow | Field | Purpose | | --- | --- | | Escrow ID and account | Identify the hold and its isolated funds. | | Owner | Funds the hold and receives unused funds. | | Beneficiary | Receives captured payments. | | Arbiter | Authorizes the distribution of disputed funds. | | Asset and amount | Specify the asset and positive funding amount in integer base units. | | Expiry | Absolute batch timestamp deadline in milliseconds; zero means no expiry. | | Dispute window | Absolute final timestamp for opening a dispute; zero disables dispute opening. | | Terms hash and agreement reference | Bind the hold to the agreed conditions and reference record. | The terms hash commits to the agreement. Applications verify delivery, evidence, or milestones against that agreement before requesting an authorized capture; hashing terms does not itself evaluate a real-world condition. ## Lifecycle and Actions | Action | Result | State | | --- | --- | --- | | Open | Move the owner's funds into escrow. | `OPEN` | | Partial capture | Pay a positive amount strictly below the remaining balance. | `PARTIALLY_CAPTURED` | | Capture | Pay the entire remaining balance to the beneficiary. | `CAPTURED` | | Release | Return the remaining balance to the owner. | `RELEASED` | | Timeout | Return an expired active hold's remaining balance to the owner. | `TIMED_OUT` | | Open dispute | Freeze ordinary capture and refund paths. | `DISPUTED` | | Resolve dispute | Distribute the remaining funds according to the arbiter's split. | `RESOLVED` | **Capture pays the beneficiary. Release refunds the owner.** Keep these meanings visible in application buttons and transaction previews. ### Authority and Deadlines The beneficiary or an owner principal acting through a delegated capability authorizes capture. The owner authorizes release. Either owner or beneficiary can open a dispute while the hold is active and the dispute deadline has not passed. Only the designated arbiter resolves the dispute. Captures fail at or after a nonzero expiry, even before a timeout sweep changes the recorded state. Batch maintenance processes due escrow deadlines using the batch timestamp. The sweep stores due holds in chunks of 24 (`LX_ESCROW_SWEEP_CAPACITY`) and allocates further chunks as needed. Disputed holds do not follow the ordinary timeout refund path; they require resolution. The dispute deadline is inclusive: a dispute opens when the batch timestamp equals `dispute_window`, and the window is closed only when the timestamp is greater than it. A zero dispute window disables dispute opening. ## Milestone Payment Workflow 1. Agree on the asset, owner, beneficiary, arbiter, deadlines, and delivery conditions. 2. Open and fund the escrow for 1,000 base units. 3. After the first milestone, partially capture 300 units. The beneficiary receives 300 and 700 remain locked. 4. On completion, capture the remaining 700. Alternatively, release the unused 700 to the owner. 5. If a dispute is opened before the deadline, submit evidence to the arbiter and resolve the remaining balance. ### Dispute Split Example A resolution specifies the beneficiary share in basis points from 0 to 10,000. With 700 units remaining and a 6,000 basis-point award, the beneficiary receives 420 and the owner receives 280. Earlier captures remain paid. The beneficiary amount rounds down to an integer base unit; the owner receives the remainder, preserving the complete escrow balance. ``` beneficiary = floor(remaining_balance × beneficiary_basis_points / 10000) owner = remaining_balance - beneficiary ``` ## Protocol Reference Escrow is module `2`, implemented in `src/modules/escrow/` with payload sizes declared in `include/layerx/lx_escrow.h`. Activity payloads use fixed-width IDs and integer amounts; they are protocol activities rather than EVM contract method names. | Activity | Type | Payload bytes | | --- | --- | --- | | `LX_ESCROW_OPEN` | `0x00020001` | 288 | | `LX_ESCROW_CAPTURE` | `0x00020002` | 80 | | `LX_ESCROW_PARTIAL_CAPTURE` | `0x00020003` | 80 | | `LX_ESCROW_RELEASE` | `0x00020004` | 64 | | `LX_ESCROW_TIMEOUT` | `0x00020005` | 64 | | `LX_ESCROW_DISPUTE_OPEN` | `0x00020006` | 32 | | `LX_ESCROW_DISPUTE_RESOLVE` | `0x00020007` | 68 | ### Retries and Failure Handling Capture, release, timeout, and resolution carry a nonzero idempotency key. Preserve that key when retrying the same operation. Keys bind to the escrow and operation context; reusing one for a different payment is rejected. Track the returned receipt and final state before advancing a business workflow. Handle expired holds, disputed holds, unauthorized capture, and capture amounts above the remaining balance as distinct failures. A partial capture cannot equal the entire balance: use full capture instead. Out-of-range dispute splits are rejected. ## Related Guides - [Continuous and metered payments](https://docs.paxeer.app/streams) - [Protocol modules](https://docs.paxeer.app/modules) - [Build with the SDK](https://docs.paxeer.app/sdk) --- URL: https://docs.paxeer.app/evm # EVM Module Native EVM execution, address association, receipts, pointers, and precompile integration on chain ID 125. **Source:** `modules/evm/` ## Overview The EVM module (`modules/evm/`) executes Ethereum-format transactions on Paxeer. It integrates with the [execution engine](https://docs.paxeer.app/engine) inside the paxd node, using EVM chain ID **125**. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. The module handles: - **EVM Transaction Processing:** Execute Ethereum-format transactions - **Address Association:** Map Cosmos bech32 addresses to EVM hex addresses - **Receipt Generation:** Create transaction receipts with logs and status - **Pointers:** Link ERC-20 tokens to native Cosmos denoms - **Precompiles:** Expose Cosmos modules via EVM precompiled contracts ## Message Types The EVM module handles `MsgEVMTransaction`, which wraps a standard Ethereum transaction: - Legacy transactions (type 0) - EIP-2930 access list transactions (type 1) - EIP-1559 dynamic fee transactions (type 2) - EIP-4844 blob transactions (type 3), accepted from Cancun - EIP-7702 set-code transactions (type 4), accepted from Prague The default chain configuration enables Cancun and Prague at time 0. Its transaction-type allowlist includes all five types. `MsgEVMTransaction` also supports `AssociateTx`, identified by `IsAssociateTx`, for address association. Transactions are submitted via the JSON-RPC `eth_sendRawTransaction` endpoint or the Cosmos SDK `MsgEVMTransaction` message. **Source:** `modules/evm/ante/preprocess.go`, `modules/evm/types/codec.go`, `modules/evm/types/message_evm_transaction.go`, `modules/evm/types/config.go` ## Address Association **Source:** `modules/evm/keeper/address.go` Paxeer addresses exist in two formats: - **Cosmos:** `pax1...` (bech32) - **EVM:** `0x...` (hex, 20 bytes) The EVM module stores a bidirectional mapping between these addresses. Transaction preprocessing derives both addresses from the signer and establishes their association when needed. This supports: - Cosmos accounts to interact with EVM contracts - EVM accounts to interact with native Cosmos denominations - Unified balance queries across both address formats ## State Management **Source:** `modules/evm/keeper/state.go` The EVM module stores: - **Accounts:** Nonce, balance (via bank module) - **Code:** Contract bytecode (`modules/evm/keeper/code.go`) - **Storage:** Contract storage slots (`modules/evm/keeper/state.go`) - **Receipts:** Transaction receipts and logs (`modules/evm/keeper/receipt.go`) EVM state is stored in the module's KVStore. Account balances are managed by the bank module to maintain consistency with native token operations. ## Transaction Execution Flow When an EVM transaction is submitted: 1. RPC receives `eth_sendRawTransaction` or SDK receives `MsgEVMTransaction` 2. Ante decorators under `modules/evm/ante/` validate signatures, nonces, and transaction fees 3. Msg server routes to EVM module 4. Execution runs through the [engine executor](https://docs.paxeer.app/engine); on the node Giga path this is `ExecuteTransactionFeeCharged`, with fees already charged 5. Executor runs EVM bytecode against state DB 6. Module generates receipt (`modules/evm/keeper/receipt.go`) with logs, gas used, status 7. Module emits events for indexing ## Receipts **Source:** `modules/evm/keeper/receipt.go` Transaction receipts include: - **Status:** 1 (success) or 0 (revert) - **Gas Used:** Total gas consumed - **Logs:** Event logs emitted during execution - **Contract Address:** For contract creation transactions - **Bloom Filter:** For efficient log filtering Execution stages receipts in a transient store and flushes them to the configured receipt store. `GetReceipt` delegates to that store; JSON-RPC exposes them through `eth_getTransactionReceipt`. ## Pointers Pointer contracts expose native denominations and CosmWasm tokens through ERC interfaces. Native token pointers use the bank module for balances and transfers. They support: - ERC-20 `transfer` to move native tokens via bank module - ERC-20 balance queries for a registered native denomination - ERC token interfaces for registered CosmWasm assets Pointer contracts are deployed via the [pointer precompile](https://docs.paxeer.app/precompiles). ## Precompile Integration **Source:** `precompiles/setup.go`, `precompiles/` The EVM module registers custom precompiled contracts that expose Cosmos SDK modules to EVM callers. Paxeer-specific addresses are registered by the precompile package, including bank at `0x1001` and address conversion at `0x1004`. Standard Ethereum precompiles occupy a separate address range. See [Precompiles documentation](https://docs.paxeer.app/precompiles) for the registered interfaces. Check each interface's availability before making a call. ## Fee Collection **Source:** `modules/evm/keeper/fee.go`, `modules/evm/keeper/feetoken.go`, `modules/evm/keeper/feecollect.go`, `precompiles/feetoken/feetoken.go` EVM transaction fees are: - Charged in PAX by default. When governance enables fee-token selection and configures an allowed denomination, an account can select it through the fee-token precompile at `0x0000000000000000000000000000000000001018`. See [Sidiora](https://docs.paxeer.app/sidiora) - Reported using receipt gas usage and the effective gas price; estimation and charge settlement depend on the configured execution path - Sent to the fee collector module - Routed under the configured fee-distribution rules; alternative fee tokens are held separately when their distribution is disabled EIP-1559 dynamic fees are supported with `baseFee` and priority fees. ## Coinbase **Source:** `modules/evm/keeper/coinbase.go`, `modules/evm/keeper/keeper.go` The EVM block context sets `COINBASE` to the fee collector module’s associated EVM address through `GetFeeCollectorAddress`. ## Chain ID Paxeer uses **EVM chain ID 125**. This must match the `chainId` field in EIP-155 transaction signatures for replay protection. The Cosmos chain identifier is `hyperpax_125-1`. ## Configuration **Source:** `modules/evm/types/params.go`, `modules/evm/types/config.go`, `modules/evm/keeper/params.go` EVM module parameters include: - **Native units:** PAX is the display currency; the implementation retains `uhpx` as its Cosmos base denomination and converts it to 18-decimal EVM units - **Fee bounds:** Minimum and maximum fees per gas, target block gas, and dynamic adjustment parameters - **Storage gas:** The default SSTORE set cost is 20,000 gas. Query the network’s EVM parameters when calculating costs for a deployment - **Chain Config:** Fork activation times, including Cancun and Prague, and a configurable SSTORE cost ## Genesis **Source:** `modules/evm/keeper/genesis.go` Genesis state for the EVM module includes: - Module parameters - Pre-deployed contract code and storage - Address associations ## Logging **Source:** `modules/evm/keeper/log.go` EVM event logs are emitted during transaction execution via the `LOG0`, `LOG1`, `LOG2`, `LOG3`, `LOG4` opcodes. Logs are included in receipts and indexed for querying via `eth_getLogs`. ## Deferred Operations **Source:** `modules/evm/keeper/deferred.go` `modules/evm/keeper/deferred.go` records each transaction's index, hash, bloom, and balance surplus in transient storage for block processing. It also tracks nonce bumps and execution errors. ## Next Steps - [Use the JSON-RPC API](https://docs.paxeer.app/json-rpc) - [Explore Paxeer precompiles](https://docs.paxeer.app/precompiles) - [Deploy contracts](https://docs.paxeer.app/contracts) --- URL: https://docs.paxeer.app/fees # Fees and payment costs Understand EVM gas, canonical kernel fee schedules, program occupancy, merchant prices, and fee ceilings on Paxeer. ## Identify the charge you are approving | Cost | What it pays for | Where to inspect it | | --- | --- | --- | | EVM gas | EVM transaction execution, measured in gas and priced in the native gas token | Transaction fee fields, current EVM parameters, gas estimate, execution receipt | | Native protocol fee | Canonical activity admission and execution under the committed kernel fee schedule | Fee estimate, signed `fee_limit`, canonical receipt | | Programs CALL fee | Program execution under its versioned execution budget and fee schedule | Program-specific estimate, authorized budget, CALL outcome | | Programs occupancy | Namespace bytes that persist across protocol batches | Occupancy receipt and batch settlement evidence | | Service or merchant price | The resource, cart, subscription, or metered usage being purchased | Accepted quote, x402 requirement, order digest, payment receipt | | Provider or conversion cost | Charges attached to the selected external payment mechanism or rail | The provider's terms and the accepted route quote | A purchase amount and its network execution cost are separate terms. A merchant cart total is the sum of catalog prices and quantities; it does not define the protocol schedule. There is no universal merchant processing or ramp percentage to apply across every route. Review the specific quote and provider terms for the mechanism you select. ## EVM gas EVM transactions use Ethereum-style gas accounting. Dynamic-fee transactions carry maximum fee and priority fee fields; execution receipts report gas used and effective gas price. Query the current network settings when preparing a transaction rather than assuming fixed base-fee bounds. EVM transfers and contract calls use the node's EVM fee estimates. The kernel's canonical activity schedule is implemented in `src/protocol/lxp_fee.c`; it prices activity bytes and resource meters. Display each charge against the operation that incurs it. ## The native committed schedule Native activity fees are deterministic functions of committed schedule bytes and execution meters. Parameters include `base_fee`, `per_activity_type_unit`, `per_encoded_byte`, `per_execution_unit`, `per_storage_unit`, `multiplier_basis_points`, Asset prices, and module prices. | Schedule version | Pricing capabilities | Canonical encoding | | --- | --- | --- | | 1 | Base and resource coefficients | 86 bytes | | 2 | Coefficients plus ten named Asset prices | 87 + 16 × 10 bytes | | 3 | Eleven Asset prices, adding the withdrawal slot | Version 2 plus 8 bytes | | 4 | Version 3 pricing plus seven named module prices | Version 3 head plus a module-count byte and 16 × 7 price bytes | Schedule versions select an encoding and pricing contract; they are distinct from an individual estimate's observed state. The withdrawal price slot is encoded as an unsigned 64-bit value even though other price slots use unsigned 128-bit values. An available schedule slot does not by itself determine which activity encodings a particular submission interface accepts. ## How the fee is calculated 1. For a Programs CALL carrying an exact program fee, use the declared exact fee units under the applicable program fee schedule. 2. Otherwise begin with `base_fee`. 3. For an Asset activity under schedule version 2 or later, add its named flat Asset price. For other activity types, add `per_activity_type_unit × activity_type`. 4. Under version 4, add the named module price for escrow, budget, stream, service, perpetuals, governance, or bridge activities. 5. Add the encoded-byte, execution-unit, and storage-unit coefficients multiplied by their corresponding meters. 6. Multiply the total by `multiplier_basis_points`, divide by 10,000, and round upward. ``` ordinary_fee = ceil( (base_fee + activity_component + applicable_module_price + per_encoded_byte * canonical_encoded_bytes + per_execution_unit * execution_units + per_storage_unit * storage_units) * multiplier_basis_points / 10000 ) ``` The exact Programs fee path is valid for Programs module 9, CALL ordinal 3, with a nonzero program fee schedule version. Unknown Asset ordinals fail as `LXP_ERR_UNKNOWN_ACTIVITY`; unsupported schedule versions fail as `LXP_ERR_VERSION_UNSUPPORTED`. Integer arithmetic and canonical encodings keep independent execution and replay calculations consistent. ## Asset and module prices | Asset operation | Parameter | Ordinal | | --- | --- | --- | | Register | `fee.asset.register` | 1 | | Pause / unpause | `fee.asset.pause` / `fee.asset.unpause` | 2 / 3 | | Open account | `fee.asset.account_open` | 4 | | Send / receive | `fee.asset.send` / `fee.asset.receive` | 5 / 6 | | Issue / revoke grant | `fee.asset.grant_issue` / `fee.asset.grant_revoke` | 7 / 8 | | Mint / burn | `fee.asset.mint` / `fee.asset.burn` | 10 / 11 | | Withdrawal price slot | `fee.asset.withdraw` | 9; schedule version 3 or later | Version 4 module parameters are `fee.module.escrow`, `fee.module.budget`, `fee.module.stream`, `fee.module.service`, `fee.module.perps`, `fee.module.governance`, and `fee.module.bridge`. Programs uses its own exact CALL pricing path rather than a slot in this seven-module table. ## Estimate before signing Estimate EVM gas through `eth_estimateGas` at the node's root JSON-RPC endpoint and review the fee fields before signing. Check `services/platform/hosted/gateway/openrpc.json` for the hosted gateway's declared methods. The hosted core estimate in `services/platform/hosted/core/src/public_reads.rs` decodes an unsigned EVM transaction for chain ID `125`. It computes `gas_limit × max_fee_per_gas` and returns `fee` as a decimal string, `parameter_version: 0`, an empty `canonical_schedule`, and `canonical_bytes`. This is the transaction fee ceiling derived from its supplied fields. An estimate reserves no balance and proves no execution. Canonical kernel pricing requires the applicable schedule and actual encoded-byte, execution-unit, and storage-unit meters. Compare the charged fee in the resulting receipt with the authorized limit. ## Set and fund the fee ceiling 1. Prepare the exact canonical activity and estimate its fee. 2. Choose a maximum in integer base units and disclose that `fee_limit` with the other payment terms. 3. Ensure the actor's spendable fee balance covers the full limit, even when the estimate is lower. 4. Sign and submit the approved bytes, preserving their activity identifier and idempotency key. 5. Verify the final receipt, charged fee, result code, and requested commitment. | Outcome | Sequence and fee behavior | Module effects | | --- | --- | --- | | Submission refused | No global sequence, no consumed account sequence, no fee | None | | Insufficient spendable balance for the limit | `LXP_ERR_FEE_UNPAYABLE`; refused before sequence assignment | None | | Admitted execution succeeds | Sequence consumed and computed fee charged within the limit | Committed | | Admitted execution fails | Sequence consumed; fee charged within the limit; failure receipt emitted | Rolled back | | Computed fee exceeds the signed limit | `LXP_ERR_FEE_LIMIT`; charge capped at the limit | Rolled back | The kernel fee policy in `src/protocol/lxp_fee_policy.c` charges admitted execution within its signed limit and rolls back failed module effects. `lxp_fee_charge` records a conserved transfer with reason `LXP_REASON_PROTOCOL_FEE` to treasury account `system:fees`. Replay checks the charge, actor debit, treasury credit, schedule version, and resulting state. ## Programs occupancy and persistent storage Program occupancy prices persistent namespace bytes in byte-batches. Its time unit is the protocol batch number. The program fee schedule and occupancy accounting are implemented in `src/modules/programs/fees.c`. Program outcomes include occupancy byte-batches, fee units, asset identifier, evidence digest, and transfer root, as defined in `include/layerx/lxp_receipt.h`. Use these fields and the corresponding batch evidence to reconcile persistent storage charges. ## Merchant, metered, and subscription pricing A merchant quote binds cart lines, integer totals, Asset, recipient, scheme, network, and timeout into a request digest. One cart uses one payment Asset and recipient. Catalog changes create new quote digests. In x402, accept the offered requirement without editing its amount or recipient, and distinguish that resource price from the network fee needed to settle it. Metered and subscription grants authorize bounded future draws with explicit purpose, expiry, and billing windows. Each draw or renewal remains a separately authorized receive and settlement. Price a complete workflow by its actual activities and storage obligations, rather than assuming that an initial grant covers every future network charge. ## Governance and parameter changes Governance controls `fee.base`, `fee.activity`, `fee.byte`, `fee.exec`, `fee.storage`, and `fee.multiplier_bps`. `fee.encoding` selects the schedule encoding and its named Asset and module prices. `src/modules/governance/lxp_fee_params.c` resolves these parameters and reads stored schedules from `fee.schedule` and, for version 4, `fee.module-prices`. ## Related guides - [Payments and settlement](https://docs.paxeer.app/payments) - [First payment walkthrough](https://docs.paxeer.app/payments-quickstart) - [EVM execution and gas](https://docs.paxeer.app/evm) - [Programs and occupancy](https://docs.paxeer.app/programs) - [Public payment API](https://docs.paxeer.app/platform-api) - [Governance](https://docs.paxeer.app/governance) --- URL: https://docs.paxeer.app/finality # Finality & Commitment Follow transactions executed and ordered by the LayerX kernel inside paxd, from signed execution receipts to blocks checked and committed by validators. ## Transaction progress on one network The LayerX kernel runs inside every paxd node, executes each transaction when it arrives, gives it the next position in one global sequence, returns a signed execution receipt and builds each block; validators check that block and commit it. An execution receipt becomes final when its block is committed. EVM chain ID is `125`. The node implementation lives in `node/`; receipt progress is exposed by `rpc/sequencer_receipt.go`. See [Commitment evidence](https://docs.paxeer.app/checkpoints). | Stage | Name | Evidence and responsibility | | --- | --- | --- | | Submission | Submitted | The node holds the transaction; no execution receipt is attached. | | Execution | Receipted | A signed receipt records the outcome before block commitment. | | Commitment | Committed | A committed block covers the receipt sequence. | A submission acknowledgement establishes that the transaction was received. A signed receipt establishes its execution outcome. Committed block evidence establishes finality on the same network. ## Receipt commitment rungs `pax_sequencerReceipt` reports three exact `rung` values. The hosted gateway relays this node method without promoting its evidence level. | Rung | Required evidence | Application decision | | --- | --- | --- | | `submitted` | Transaction hash and nonce without a receipt | Track the existing submission. | | `receipted` | Signed execution receipt and consistent decoded fields | Inspect success or failure and the recorded effects. | | `committed` | Receipt covered by a committed block | Treat the verified outcome as final. | A submitted result contains `txHash` and `nonce`. Receipted results add signed receipt bytes and their decoded fields. Committed results also contain `blockNumber` and `blockHash` for the block covering the receipt sequence. ### Use the exact wire vocabulary The current names are `submitted`, `receipted`, and `committed`. In the Human API, their verification labels are `unverified`, `receipt-verified`, and `checkpoint-finalised`. ## Recover an unknown outcome If the outcome is unknown, track the existing transaction and obtain its evidence before taking another economic action: 1. Keep the signed transaction, hash, and nonce. 2. Read `pax_sequencerReceipt` for that transaction hash. 3. Verify the signed receipt against the governed receipt keys from `px_getReceiptKeys`. 4. Check the covering committed block before treating the outcome as final. A new transaction can repeat the intended payment. Retain the original transaction hash and reconcile that transaction first. ## Payment release policies Release a paid resource only after checking the receipt against the expected payer, recipient, asset, amount, and execution result, together with the block commitment required by your application. A payment reference identifies an outcome; it does not establish the signer's authority or block inclusion. Verify the signed material and trusted receipt-key configuration as well as the response fields. ## Replay and execution The kernel executes canonical activities, program calls, program transfers, and storage occupancy accounting. Replay checks deterministic state changes and receipts against the same ordered history. ## Verify receipt and block evidence `SequencerReceiptResult.Verify` checks the signed receipt against its decoded fields and output digests. Supply trusted receipt-key pins; a signing key returned beside a receipt is insufficient to establish authority. Committed results must identify the covering block. ## Pending transactions If a transaction remains submitted or receipted, retain that state until commitment evidence is available. A timeout does not establish failure or finality. See [Account and custody boundaries](https://docs.paxeer.app/custody). Continue with [Receipts & Proofs](https://docs.paxeer.app/proofs), [Data Availability](https://docs.paxeer.app/data-availability) and [Consensus](https://docs.paxeer.app/consensus). --- URL: https://docs.paxeer.app/foundry # Build with Foundry Compile and test the in-tree Solidity contracts with Forge, then inspect a Paxeer deployment with Cast. Forge builds the repository's Solidity projects. The Paxeer chain project uses `foundry.paxeer.toml`; the root `foundry.toml` selects a separate contract project. The [Paxeer EVM chain ID is 125](https://docs.paxeer.app/network-parameters) (`hyperpax_125-1`), and the native gas token is PAX. ## Select the chain project Install Forge and Cast using the [Foundry installation instructions](https://getfoundry.sh/introduction/installation/). Run the following commands from the repository root. `contracts/bootstrap-libs.sh` fetches `forge-std v1.9.6` and `openzeppelin-contracts v5.3.0` into `contracts/lib/`. It reuses pristine pinned checkouts and replaces other contents at those dependency paths. ``` forge --version cast --version bash contracts/bootstrap-libs.sh ``` The chain configuration selects `contracts/src`, `contracts/test`, `contracts/out`, and Solidity `0.8.27`. The following excerpt is from `foundry.paxeer.toml`. Select it with `FOUNDRY_CONFIG`. ``` [profile.default] src = "contracts/src" out = "contracts/out" test = "contracts/test" libs = ["contracts/lib"] remappings = [ "forge-std/=contracts/lib/forge-std/src/", "@openzeppelin/contracts/=contracts/lib/openzeppelin-contracts/contracts/", ] solc_version = "0.8.27" auto_detect_solc = false ``` ## Read the contract `contracts/src/Box.sol` provides a small storage contract. Its `store`, `retrieve`, and `boxIncr` methods write, read, and increment a value. Its source is: ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract Box { uint256 private _value; event ValueChanged(uint256 value); function store(uint256 value) public { _value = value; emit ValueChanged(value); } function retrieve() public view returns (uint256) { return _value; } function boxIncr() public { _value = _value + 1; emit ValueChanged(_value); } } ``` ## Run the existing tests `contracts/test/WPAXTest.t.sol` exercises the wrapped native-token contract. The following test function checks its name, symbol, and decimals; run the existing test contract with the commands below. ``` function testMetadataNamesTheCoin() public view { assertEq(wpax.name(), "Wrapped Paxeer"); assertEq(wpax.symbol(), "WPAX"); assertEq(wpax.decimals(), 18); } ``` ``` FOUNDRY_CONFIG=foundry.paxeer.toml forge build FOUNDRY_CONFIG=foundry.paxeer.toml forge test --match-contract WPAXTest FOUNDRY_CONFIG=foundry.paxeer.toml forge test --match-contract WPAXTest --gas-report ``` `WPAXTest` checks token metadata, storage slots, selectors, wrapping, withdrawals, and token transfers. A Forge gas report reports local execution costs; use network fee estimates when preparing a transaction. ## Connect and prepare deployment Set `PAXEER_RPC_URL` to the node's root EVM HTTP endpoint. Confirm chain ID `125` and select an encrypted keystore account for deployment. ``` : "${PAXEER_RPC_URL:?Set the node EVM RPC endpoint}" cast chain-id --rpc-url "$PAXEER_RPC_URL" cast wallet import paxeer-dev --interactive FOUNDRY_CONFIG=foundry.paxeer.toml forge create contracts/src/Box.sol:Box --rpc-url "$PAXEER_RPC_URL" --account paxeer-dev ``` Use `forge create` without `--broadcast` to prepare the deployment. Review the chain, sender, and fee estimate. An actual deployment requires sufficient PAX. ## Deploy and read the result The next command broadcasts the existing Box contract. Retain the deployed contract address and transaction hash from its output. ``` FOUNDRY_CONFIG=foundry.paxeer.toml forge create contracts/src/Box.sol:Box --rpc-url "$PAXEER_RPC_URL" --account paxeer-dev --broadcast # Set CONTRACT_ADDRESS and TX_HASH from the deployment output. cast receipt "$TX_HASH" --rpc-url "$PAXEER_RPC_URL" cast code "$CONTRACT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast call "$CONTRACT_ADDRESS" 'retrieve()(uint256)' --rpc-url "$PAXEER_RPC_URL" ``` Check receipt status, deployed bytecode, and `retrieve()`. A new Box starts at zero. The build artifact is `contracts/out/Box.sol/Box.json`. Use its ABI in your [frontend](https://docs.paxeer.app/building-a-frontend) and retain the compiler settings used for deployment. Reference: [Foundry deployment and verification](https://getfoundry.sh/forge/deploying/). Verification uses the same source and compiler settings as the deployed bytecode. **Paxeer source:** `foundry.paxeer.toml`, `contracts/src/Box.sol`, `contracts/test/WPAXTest.t.sol`, `modules/evm/config/config.go`, and `rpc/send.go`. --- URL: https://docs.paxeer.app/funding # Funding and money movement Quote and commit money movements, fund managed agents, and inspect receipt evidence on Paxeer. ## Movement journeys The Human API represents money movement as a `move` journey on one network. The resolver vocabulary is `fund`, `allocate`, `return`, and `transfer`. Each journey reports its own stages and evidence. | Movement | Meaning | Authorization and evidence | | --- | --- | --- | | Fund | Fund a managed budget | Resolved route and verified receipts | | Allocate | Move funds from a budget to an agent | Resolved route and verified receipts | | Return | Return funds to the owner | Resolved route and verified receipts | | Transfer | Send funds to a recipient | Quote, commit, execution receipt | Money-moving mutations require an `Idempotency-Key`. Reuse the key when retrying the same intended action and reconcile the existing journey before requesting another movement. ## Production transfer path `POST /v1/moves/quote` prepares a movement and `POST /v1/moves` commits that quote. In the production service, a quote builds an EIP-1559 bank transfer using the source owner's bound EVM account and pending nonce. The source must belong to the authenticated owner; the destination must resolve to a different, nonzero recipient. ## Move money and fund an agent Quote the source, destination, and amount first. The resolver defines `fund`, `allocate`, `return`, and `transfer` according to the account relationship. The production bank quote returns `transfer` and preserves the selected source, recipient, amount, and fees for commitment. ``` POST /v1/moves/quote { "source": "", "destination": "", "money": { "amount": "500000", "currency": "" } } POST /v1/moves Idempotency-Key: { "quote_id": "" } ``` Substitute the authenticated source account, a resolvable recipient account, and the currency returned by the balance read. The production service accepts the owner's canonical source account or its returned account identifier; a destination may be a canonical account or EVM address. Amounts are positive integer strings in the asset's base units. Obtain `quote_id` from the quote response. | Quote field | What to review | | --- | --- | | `money` and `mechanism` | The exact amount, currency, and resolved movement | | `fee_estimate` and `fee_ceiling` | Expected charge and maximum disclosed charge | | `arrival_estimate` and `expires_at` | Expected timing and quote validity | | `irreversibility_copy_key` | Any irreversible-action disclosure | Commit returns a journey. A refused movement reports the refusing authority, explanatory copy, remaining money, and optional change path. Funding a recipient account uses the quote-and-commit surface. Reclaim uses `POST /v1/agents/{agent_id}/reclaim` with `money` and returns a move with return semantics. ### Spending and fee budgets Agent monthly limits carry an enforcement label: `protocol` or `app`. Native fee budgets separately constrain per-activity, total, and period fees. Read `GET /v1/sessions/fee-policy` for the configured fee asset, currency, and decimals, and present the principal amount separately from execution fees. ## Verification levels Human evidence uses `unverified` for submitted, `receipt-verified` for receipted, and `checkpoint-finalised` for committed. Committed means the verified outcome is included in a committed block on this network. The journey's completion label alone is insufficient to establish that evidence. ## Card, bank, and real-time payment rails The fiat interop adapter connects provider callbacks for card, bank, and real-time payments. Provider evidence distinguishes authorised, clearing, settled, reversed, and chargeback events. Credit and corrective movements require accepted provider evidence and a receipt-gated LayerX result. | Rail | Provider callback route | | --- | --- | | Card | `POST /v1/http/fiat/card/callbacks` | | Bank | `POST /v1/http/fiat/bank/callbacks` | | Real-time payment | `POST /v1/http/fiat/rtp/callbacks` | These are provider integration endpoints, not consumer deposit or card-entry endpoints. Callbacks carry token references only; PAN-shaped input is refused. A provider's authorisation is distinct from settlement, and reversal or chargeback is represented as its own verified event. ### Independent market-maker ramps Market-maker ramps in `services/platform/ramps/toolkit` compile grant draws and operator sends, verify order receipts, and journal orders. Their quote terms identify the external custody role. Inspect those terms before authorizing a conversion. ## Reconcile the result Read balances through `GET /v1/account/balance`, journey status through `GET /v1/journeys/{journey_id}`, and proof material through `GET /v1/evidence/{evidence_id}`. Journey states preserve still-checking, refused, and waiting-for-you alongside completion. The API response envelope is `{ ok, result?, error?, trace }`; retain trace and evidence references for support. See [the Human interface](https://docs.paxeer.app/human-interface) for passkeys, ownership, approvals, and agent controls, and [interop](https://docs.paxeer.app/interop) for external system boundaries. --- URL: https://docs.paxeer.app/governance # Governance Authorized module proposals, scoped pauses, and constrained proxy upgrades on Paxeer. Governance authorizes changes on one network. Chain proposals carry typed module messages, protocol activities carry their own authority, and Solidity proxy upgrades use their declared governance contract. ## Governance activities The kernel governance module processes identity and authority activities under the canonical activity envelope, ordering, fee, and receipt rules. Its implementation is `src/modules/governance/lxp_governance.c`. The governance activity catalogue includes identity registration, session authority, and delegated grants. The following identifiers are handled by the kernel: | Activity | Purpose | | --- | --- | | `0x00070001` | Identity registration and onboarding. | | `0x00070005` | Session authority. | | `0x00070008` | Delegated grant. | Use the declared encoding and authority for each activity. Governance proposal handling in `modules/layerxgov` is a separate typed chain interface. See [Identity and authority](https://docs.paxeer.app/identity) for account delegation. ## Typed module proposals `modules/layerxgov/types/proposal.go` defines `LayerXProposal`, which contains a title, description, and packed messages. Validation requires supported messages whose authority is the governance module account. The handler in `modules/layerxgov/handler.go` dispatches every message in a cached context and commits the changes only when all handlers succeed. ## Scoped pause controls `CheckPauseScope` enforces module pauses while allowing named exit operations. Its scopes cover payment, exchange, ledger, authorization, and agent operations. A paused operation outside its allowed exit set returns `ErrPausedScope`. Payment exits include escrow release and timeout, budget closure and defunding, stream pause and close, and service-offer withdrawal. Exchange exits include order cancellation, position closure, and margin withdrawal. Read the scope's exact method names before invoking an exit. ## Proxy upgrade roles | Role | Authority | | --- | --- | | Governance authority | Schedules the permitted proxy upgrade with sufficient delay. | | Executor | Executes the exact scheduled operation within its readiness window. | | Guardian | Cancels a scheduled operation before it becomes ready. | | Proxy target | Receives the authorized upgradeToAndCall operation with zero value. | `contracts/governance/SidioraProxyTimelock.sol` binds an immutable proxy, governance authority, executor, guardian, minimum delay, delay floor, and grace period. Its operation identifier commits to the chain, timelock, target, value, calldata hash, salt, and nonce. Execution requires the scheduled operation to be ready and within its grace period. ### Constrained proxy upgrades The Sidiora timelock permits only `upgradeToAndCall` on its configured proxy, requires zero call value and deployed implementation code, and checks canonical upgrade calldata. Its roles and delay settings are immutable. Compare the target, implementation, calldata, salt, nonce, and ready time before execution. Inspect the operation event and resulting proxy state afterwards. A failed target call reverts execution; a completed operation cannot execute again. ## Continue Read [Validators and commitment](https://docs.paxeer.app/guarantors) for consensus evidence, [Security and trust boundaries](https://docs.paxeer.app/security) for verification responsibilities, and [Finality](https://docs.paxeer.app/finality) for block commitment. --- URL: https://docs.paxeer.app/guarantors # Validators and commitment The LayerX kernel executes and orders transactions and builds blocks; validators check and commit them. Verify execution receipts and commitment evidence. The LayerX kernel runs inside every paxd node, executes each transaction when it arrives, gives it the next position in one global sequence, returns a signed execution receipt and builds each block; validators check that block and commit it. Paxeer validators commit blocks on one network. Applications verify execution receipts and the committed blocks covering them; finality comes from BFT commitment. ## Verify the execution outcome 1. Confirm the chain ID and retain the signed transaction. 2. Retrieve the transaction receipt and its progress rung. 3. Obtain the governed receipt keys and check their authorized height ranges. 4. Verify the receipt signature, decoded fields, and output digests. 5. Verify the committed block covering the receipt sequence. A receipt signature authenticates execution only when its signing key is authorized for the receipt height. The node exposes the governed key ranges through `px_getReceiptKeys`, implemented in `rpc/sequencer_receipt.go`. ### Exact evidence bindings Verification checks the exact signed bytes and their bindings. Receipt output data must reproduce the digests in the signed receipt. Missing evidence leaves the outcome at its observed progress level. ## Receipt and commitment evidence `pax_sequencerReceipt` exposes the transaction hash, nonce, progress rung, and available receipt material. Its committed result identifies the block whose sequence batch covers the receipt. | Evidence | Meaning | | --- | --- | | Submission acknowledgement | The node holds the transaction. | | Signed execution receipt | The authorized signer records the execution outcome. | | Receipt-key range | Governance authorizes a receipt key over stated heights. | | Committed block | BFT commitment makes the included outcome final. | `SequencerReceiptResult.Verify` checks receipt signatures, decoded fields, output digests, and required block fields. Pass the trusted receipt keys to authenticate signing authority. Consistency under an untrusted supplied key is insufficient. ## Consensus membership Paxeer validators check and commit the blocks the kernel builds. The hosted gateway declares `px_getValidators` and `px_getCommit` in `services/platform/hosted/gateway/openrpc.json`; use their verified chain data when inspecting consensus evidence. The public EVM chain ID is `125`. Bind transaction signatures and receipt verification to the intended chain and obtain current consensus state from that network. ## Block confirmation The `committed` rung means the receipt sequence is covered by a committed block. Its `blockNumber` and `blockHash` identify that block. Verify these bindings together with the execution result. A successful submission response is an acknowledgement. A receipt may record a reverted execution. Check status and effects before presenting a committed outcome as a successful payment. ## Application responsibilities Retain the original signed transaction, its hash, receipt bytes, trusted receipt-key ranges, and covering block evidence. These records let an application verify the outcome independently of a progress indicator. If evidence is unavailable, keep the transaction pending and reconcile its existing hash. Reissuing a payment with another transaction can create a second economic effect. ## Continue See [Finality](https://docs.paxeer.app/finality), [Governance](https://docs.paxeer.app/governance), and [Security and trust boundaries](https://docs.paxeer.app/security). --- URL: https://docs.paxeer.app/hardhat # Build with Hardhat Use the repository's Hardhat 2 project to compile contracts and interact with a development node. The contract project at `contracts/` uses Hardhat 2 and a CommonJS configuration. Its sources live under `contracts/src/`. Paxeer EVM chain ID is `125`, mapped from `hyperpax_125-1` in `modules/evm/config/config.go`. ## Use the in-tree project Use a [Node.js version supported by Hardhat 2](https://hardhat.org/hardhat2). Install the dependencies recorded in `contracts/package-lock.json` and inspect the local tool version. ``` cd contracts npm ci npx hardhat --version ``` `contracts/package.json` declares `hardhat ^2.20.1`, `@nomicfoundation/hardhat-toolbox ^6.1.2`, and `@openzeppelin/hardhat-upgrades ^3.0.2`. The lockfile records the resolved dependency versions. ## Configure the development endpoint `contracts/hardhat.config.js` selects Solidity `0.8.27`, the `prague` target, and an enabled optimizer with `1000` runs. Its network configuration reads `PAXEER_LOCAL_EVM_RPC_URL`. The following excerpt shows the compiler and source settings. ``` module.exports = { solidity: { version: "0.8.27", settings: { evmVersion: "prague", optimizer: { enabled: true, runs: 1000 }, }, }, paths: { sources: "./src" }, }; ``` The configured HTTP network is named `paxlocal`. Set `PAXEER_LOCAL_EVM_RPC_URL` to your development node's root EVM endpoint before connecting. The default uses the loopback interface on port `8545`. The configuration loads `contracts/.env` through `dotenv` and reads the endpoint from the environment. The following command requires that endpoint to be set. ``` : "${PAXEER_LOCAL_EVM_RPC_URL:?Set the development node EVM endpoint}" ``` ## Read sources and run the compiler check `contracts/src/Box.sol` is an existing storage example. It exposes `store`, `retrieve`, and `boxIncr` and emits `ValueChanged`. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract Box { uint256 private _value; event ValueChanged(uint256 value); function store(uint256 value) public { _value = value; emit ValueChanged(value); } function retrieve() public view returns (uint256) { return _value; } function boxIncr() public { _value = _value + 1; emit ValueChanged(_value); } } ``` Token contracts use the installed OpenZeppelin package. For example, this is the import and constructor in `contracts/src/TestToken.sol`. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import "@openzeppelin/contracts/access/Ownable.sol"; contract TestToken is ERC20, Ownable { constructor(string memory name, string memory symbol) Ownable(msg.sender) ERC20(name, symbol) { _mint(msg.sender, 1000 * (10 ** uint256(decimals()))); } // The owner adjusts balances by minting or burning function setBalance(address account, uint256 amount) public onlyOwner { uint256 currentBalance = balanceOf(account); if (amount > currentBalance) { _mint(account, amount - currentBalance); } else if (amount < currentBalance) { _burn(account, currentBalance - amount); } } } ``` ``` npx hardhat compile node --test test/hardhat_solc_parity.test.js ``` The focused Node test `contracts/test/hardhat_solc_parity.test.js` checks that the Hardhat compiler version matches `foundry.paxeer.toml`. Run it from `contracts/` after compiling. ## Interact through the console In the Hardhat console, the following Ethers calls deploy the existing Box artifact, wait for deployment, write a value, and read it. Deployment and writes require a signer exposed by the development node. ``` const box = await ethers.deployContract("Box"); await box.waitForDeployment(); const tx = await box.store(7); const receipt = await tx.wait(); await box.retrieve(); ``` Open the console with the configured network. Confirm that it is the intended development node before running the deployment expressions above. ``` npx hardhat console --network paxlocal ``` ## Check the connected chain In that console, inspect the endpoint's chain ID before submitting transactions. Paxeer uses `125`. Deployment and storage writes spend the configured signer's gas balance. ``` const network = await ethers.provider.getNetwork(); network.chainId; ``` Retain the contract address, transaction receipt, source, and compiler settings. Read the result through the [querying guide](https://docs.paxeer.app/querying-evm). Hardhat writes the Box artifact to `contracts/artifacts/src/Box.sol/Box.json`. `contracts/package.json` declares `@openzeppelin/contracts ^5.4.0`. Its `TestToken` source imports `@openzeppelin/contracts/token/ERC20/ERC20.sol`. References: [Hardhat 2 configuration](https://hardhat.org/hardhat2/hardhat-runner/docs/config), [contract tests](https://hardhat.org/hardhat2/hardhat-runner/docs/guides/test-contracts), and [contract deployment](https://hardhat.org/hardhat2/hardhat-runner/docs/guides/deploying). **Paxeer source:** `contracts/hardhat.config.js`, `contracts/package.json`, `contracts/src/Box.sol`, `contracts/src/TestToken.sol`, and `contracts/test/hardhat_solc_parity.test.js`. --- URL: https://docs.paxeer.app/human-interface # Human interface Manage your Paxeer identity, balances, agents, approvals, and recovery through receipt-backed journeys. ## An account interface for Paxeer The Human interface presents the Paxeer network through accounts and journeys: authenticate with a passkey, move funds, manage agents, review approvals, and inspect receipts. Home combines balances, managed agents, pending approvals, and recent activity. Self-custody is the default posture; custodial holding requires explicit opt-in. Account authentication and protocol authority have separate roles. The key-export ceremony transfers the primary key once and stops subsequent service signing for that identity. Current money movements use `move` journeys on the same network. | Identity | Purpose | Authority | | --- | --- | --- | | Application identity | Passkey authentication and device sessions | Opens the Human account experience | | Protocol identity | DID and account operations | Self-custody or explicitly selected custodial authority | ## Onboard and secure an account 1. Create an account with an email and display name. 2. Register a passkey using the browser credential ceremony. 3. Follow the protocol identity and recovery stages. 4. Open the account when its protocol identity has a verified LayerX receipt. Onboarding progresses through creating the account, adding the passkey, setting up the protocol identity, and putting recovery in place. Resume continues the existing journey. A local progress indicator alone does not activate an account. | Action | Human API | | --- | --- | | Create account | `POST /v1/accounts` | | Register passkey | `POST /v1/passkeys/registrations`, then `POST /v1/passkeys/registrations/{registration_id}` | | Read or resume onboarding | `GET /v1/onboarding`, `POST /v1/onboarding/resume` | | Sign in | `POST /v1/passkeys/assertions`, finish the assertion, then `POST /v1/sessions` | | Inspect or refresh sessions | `GET /v1/sessions`, `POST /v1/sessions/refresh` | ### Protocol ownership Onboarding binds protocol identity through the address precompile and verifies the resulting receipt. Passkeys authorize application access; protocol authority controls signed operations. See [identity](https://docs.paxeer.app/identity) for these roles. ## Create and govern managed agents Agent creation asks for a name, purpose, and monthly spending limit. Each limit identifies whether enforcement is `protocol` or `app`. A separate native fee budget sets maximum fees per activity, total fees, period length, and maximum fees per period. Networks enforcing fee-authority version 2 require a finite `native_fee_budget`; changing or rotating a key does not replenish it. ``` POST /v1/agents Idempotency-Key: 9f3c1e6a0b8d4f72a5c9e1d3b7a2c4e6 { "name": "Research Runner", "purpose": "Buys datasets and pays per-use research services", "monthly_limit": { "amount": "250000000", "currency": "LXP" }, "native_fee_budget": { "asset_id": "", "maximum_per_activity": "1000000000000000", "maximum_total": "100000000000000000", "period_length_ms": "86400000", "maximum_per_period": "10000000000000000" } } ``` This example follows `services/human/schema/human-api/agents.kvx`. Substitute `asset_id` from `GET /v1/sessions/fee-policy`. Amounts are integer strings in the declared asset units. The positive per-activity limit cannot exceed the total; a nonzero period requires a period limit at least as large as the per-activity limit. Creation returns an `agent-create` journey. | Control | Operation | Result | | --- | --- | --- | | Browse agents | `GET /v1/agents`; `GET /v1/agents/{agent_id}` | Agent details and status | | Pause or resume | `POST /v1/agents/{agent_id}/pause` or `/resume` | Updated Agent | | Change monthly limit | `POST /v1/agents/{agent_id}/limit` | Updated Agent | | Fund | Move quote and commit | Receipt-backed movement journey | | Reclaim funds | `POST /v1/agents/{agent_id}/reclaim` | Move journey using return semantics | | Rotate or recover keys | `POST /v1/agents/{agent_id}/rotate` or `/recover` | Key challenge | | Archive | `POST /v1/agents/{agent_id}/archive` with `confirm_name` | Agent retirement journey | Owner key rotation adds a disclosure and step-up before starting the rotation window. Retirement stops work and closes the agent. Pause returns the current Agent directly; it does not create a separate journey response. ## Review approvals before money moves Held activities appear as `waiting-for-you`. Open the approval to inspect the amount, counterparty, asset, fees, expiry, remaining budget after approval, and supporting evidence. A step-up ceremony confirms the disclosed action before approval. Rejecting resolves the request without approving its movement. 1. List pending requests with `GET /v1/approvals`. 2. Read `GET /v1/approvals/{approval_id}` and review its facts. 3. Begin step-up with `POST /v1/step-up` and finish it with `POST /v1/step-up/{challenge_id}` using the supplied confirmation digest. 4. Submit `step_up_evidence` to `POST /v1/approvals/{approval_id}/approve`, or use `/reject`. 5. Read the decision's `money_moved` and evidence instead of inferring success from the button press. At decision time `money_moved` is false; movement is established by the resulting journey and receipt. Approval states are pending, approved, rejected, expired, and defective. Expiry and defective evidence prevent a request from being treated as an approved payment. ## Read progress and proof Journeys expose stages, evidence references, timestamps, and refusals. States include getting-ready, sending, processing, done, done-finalised, still-checking, refused, waiting-for-you, closed, and awaiting-approval. A journey held for approval has no completed movement. A refusal identifies its authority, explanatory copy, whether money left, and an optional path to change the request. | Verification | Meaning | | --- | --- | | `unverified` | Submitted; no stronger authenticated execution evidence is attached | | `receipt-verified` | Receipted; the execution receipt is verified | | `checkpoint-finalised` | Committed; inclusion in a committed block is verified | Read `GET /v1/journeys`, `GET /v1/journeys/{journey_id}`, and `GET /v1/evidence/{evidence_id}`. Evidence material includes its class, verification, content type, base64 bytes, and optional progress rung and inclusion height. Verify the actual material and its trusted key bindings. Live updates use `POST /v1/stream` and `GET /v1/stream/{cursor}`. ## Recovery, sessions, and support Security settings manage passkeys, sessions, authenticators, backup codes, and recovery evidence. Sensitive actions require a server disclosure digest and matching step-up evidence. Recovery evidence has a remask time and copy policy. Primary-key export uses `POST /v1/security/key-export/begin` and `POST /v1/security/key-export/finish`; it returns the key once and leaves the service unable to sign for that identity. Activity search uses `POST /v1/activity/query`; detail uses `GET /v1/activity/{entry_id}`. Support conversations accept deposit, withdrawal, agents, account, and report topics through `POST /v1/support/conversations`. Continue with [funding and money movement](https://docs.paxeer.app/funding) or explore [agent capabilities](https://docs.paxeer.app/agents). --- URL: https://docs.paxeer.app/identity # Identity, Ownership and Credentials Connect human ownership, agent identities, hosted sessions and scoped signing authority across Paxeer X. ## One owner, explicit authority Paxeer X connects an owner to an agent DID, a signing authority, an account and a recovery policy. The identity provider exports a principal DID, while the node binds an EVM address to a DID derived from an Ed25519 public key. Preserve each identity with its own registration evidence. A hosted login authenticates a principal; a protocol signature authorizes a particular action. | Identity surface | What it establishes | What to retain | | --- | --- | --- | | Human owner | The owner DID, protected Ed25519 authority and recovery commitment. | Public registration evidence and secure custody references. | | Native account | The account bound to the owner through the EVM/DID binding. | Account identity and the committed binding transaction. | | Hosted principal | Tenant, subject, allowed signer keys, optional account and audiences. | The principal record and tenant context. | | Hosted session | Time-limited access to hosted services. | Session ID, expiry and securely held token. | | Agent capability | The activities, counterparties, assets and limits an agent may use. | Capability scope, expiry and revocation state. | ## Register an owner Registration, funding, and recovery are transactions on the network (EVM chain ID 125). The kernel runs inside the node, and a receipt is final when its block commits; see [custody](https://docs.paxeer.app/custody). 1. Provision the owner principal and recovery policy, and separately generate and protect the signing key. Provisioning a principal alone does not register an on-chain identity. 2. For a key-derived node DID, read `layerXBindNonce(address)` from the address precompile at `0x0000000000000000000000000000000000001004`. Have the Ed25519 key sign `"LX:PAXEER-BIND:v1" || chain_id:uint256be || evm_address:20 bytes || nonce:u64be`, then call `bindLayerX(bytes32, bytes)` from that EVM address. The binding is one EVM address per DID and one DID per address. 3. Verify the committed transaction and `LayerXBound` event, then query `getUnifiedAccount(address)` for the main account ID. A successful query alone is insufficient, because an unbound address returns zero DID and account fields. 4. Register identity and recovery state through LayerXAuth at `0x000000000000000000000000000000000000101C`: `recordLifecycle(bytes payload, bytes32 idempotencyKey)` executes Governance module 7 for the bound caller. Identity registration is ordinal 1 (`71 01 00 02 || did_id32 || primary_key32`); the recovery commitment is ordinal 3, with an optional five-field form carrying delay bounds. Derive the DID identifier with the protocol codec and use big-endian integers. 5. Fund the intended account with the correct native asset, keeping EVM gas funding distinct from the kernel account balance. Retain the activity IDs and receipt evidence. An account name such as `agent::main` identifies the intended account. Its account ID is derived by the protocol account codec, not by interpreting the DID as an address. Session authorization uses the dedicated `grantSession` and `revokeGrant` methods rather than the lifecycle payload. ### Key and account representations The node binding uses `did:layerx:` followed by the lowercase 64-character Ed25519 public-key hex. The Human sponsor configuration compares its authority reference to the resolved owner's lowercase public-key hex, and its actor to the exact exported DID. The recovery root is unpadded base64url of the registered 32-byte commitment. Preserve the representation required by each interface. ## Hosted principals and sessions The hosted identity API serves HTTPS with service Bearer authentication. The Provisioning service manages principals and sessions; the Registrar service can also create principals but cannot manage sessions. Consumer services introspect a user session using their own service credential, keeping user tokens separate from service authority. | Method and path | Purpose | | --- | --- | | `POST /v1/principals` | Create or update a principal and its signer/account/audience bindings. | | `POST /v1/sessions` | Mint a session for a known subject. | | `DELETE /v1/sessions/{id}` | Revoke a session by its 16-byte hex identifier. | | `POST /v1/sessions/introspect` | Check whether a presented token is active for the calling service. | | `POST /v1/introspect` | Use the same introspection contract through its alternate path. | | `POST /v1/publication-keys`, `/v1/signup`, `/v1/signup/verify` | Publication-key registration and the signup flow. | | `POST /v1/starter-credits`, `/v1/starter-credits/settle` | Starter-credit issuance and settlement. | | `GET /internal/v1/principal`, `GET /internal/readyz` | Internal principal lookup and readiness. | ``` POST /v1/principals Content-Type: application/json Authorization: Bearer { "tenant": "treasury", "sub": "agent:treasury-operator", "allowed_signer_public_keys": ["<32-byte-lowercase-public-key-hex>"], "account": "", "audiences": ["ramp"] } POST /v1/sessions {"tenant":"treasury","sub":"agent:treasury-operator","ttl_seconds":3600} ``` Replace bracketed values with established public bindings. The session response contains `session_id`, `tenant`, `sub`, `token`, `csrf_token` and `expires_at`. Tokens use `ses_{32hex-id}.{64hex-secret}`. Keep token and CSRF material out of URLs, logs and public configuration. ### Session bounds and introspection The default lifetime is 86,400 seconds. A session may request 1 through 2,592,000 seconds, with at most 4,096 live unrevoked sessions per principal. Principal subjects contain 1–128 lowercase identifier bytes. Signer lists contain at most 128 unique lowercase 32-byte hex keys; audience lists contain at most 32 unique identifiers. Gateway introspection returns the active subject and allowed signer keys. Developer consumers (Webhooks and Dashboard) receive the active subject and CSRF token. Ramp introspection additionally requires an authorized audience and a stored account. Unknown, expired, revoked or secret-mismatched sessions return an inactive result. ## Delegate without surrendering ownership Agent sessions carry tenant, agent DID, authority reference, permitted activity types, expiry, client and policy version. Capabilities restrict activity types, counterparties, assets, amount ceilings, rate ceilings, purpose constraints and expiry. Every dimension is required; an empty permission set denies the corresponding action. Use `capability.create` to establish authority, `capability.attenuate` to narrow a grant, `capability.list` to inspect grants and `capability.revoke` to withdraw authority. Combine capability scope with a [funded agent budget](https://docs.paxeer.app/agent-budgets) and approval policy for monetary operations. ## Rotation, revocation and recovery Session grants are authorized through `grantSession(bytes, uint64, bytes32)` and withdrawn through `revokeGrant(bytes32, uint8, uint64)`. The arguments carry the canonical grant, its expiry sequence, and a 32-byte action key. Rotation announcements use `recordLifecycle` with the 92-byte ordinal-2 form: `71 02 00 04 || did_id32 || next_key32 || begin_ms:u64 || end_ms:u64 || effective_sequence:u64`. Check committed identity, scope and revocation state before authorizing a spend. Recovery uses the registered guardian commitment and threshold from the ordinal-3 lifecycle payload. Keep recovery material exercisable and separate from the primary owner key, and maintain the registered delay policy alongside that commitment. ### Respond to a compromised credential 1. Revoke the affected hosted session and withdraw its agent capability. 2. Close or revoke budgets exposed to the compromised delegate. 3. Rotate the signing authority through the registered owner policy, or use the guardian recovery process. 4. Verify committed policy state and receipts before issuing replacement credentials. ## Errors and operational checks The HTTP API returns typed errors with a retry policy. Invalid arguments, missing credentials and unauthorized service operations require corrected input or authority. Session capacity returns `429 session_bound_reached`; unavailable durable storage returns `503 store_unavailable`. Respect `Retry-After` where supplied. `GET /livez` checks service liveness; `GET /readyz` verifies writable durable storage. Principal records, session digests and revocation state survive restart through a snapshot and journal. Token secrets are not stored in plaintext. **Technical references:** `docs/wiki/HumanOwnerRegistration.md`; `services/platform/hosted/identity/src/main.rs`; `services/agent/schema/agent-api/identity.kvx`. Continue with [agent budgets and approvals](https://docs.paxeer.app/agent-budgets). --- URL: https://docs.paxeer.app/installation # Installation & Build Build the Paxeer X node, deterministic LayerX kernel, hosted services, agent tools and Programs from the unified monorepo. **Source:** `Makefile`, `chain.mk`, and `README.md` at the repository root ## Build the complete network stack The monorepo contains the Go chain node, the C17 kernel, Rust service workspaces, SDKs, and program tooling. The network entry point is `paxd`. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. A receipt is final when validators commit its block. | Component | Build surface | Purpose | | --- | --- | --- | | Merged node | `make paxd-build` | `build/paxd` with linked native libraries and release version stamp | | Kernel library and tools | `make build` | Kernel archive, genesis builder, and module registry, without rebuilding the node | | Agent services | `make agent-build` | Agent runtime and its service boundaries | | Human services | `make human-build` | Human API, providers, owner and security components | | Platform services | `make platform-build-all` | Hosted services, SDKs, integrations, and samples | | Programs and porting | `make programs-build` | Programs workspace and porting kits | These commands run from the repository root. Use the Rust toolchain and dependency locks declared by each workspace, and the C compiler and native dependencies declared by the kernel build. Program guests target WebAssembly; install the target required by the selected guest before compiling it. The platform target also requires Node.js, Python, Maven/JVM, .NET and Swift, with dependencies prepared as declared in `services/platform/Makefile.inc`. Installation provides binaries and images. Joining a network also requires its genesis, network identity, and role-specific credentials. Retain build provenance and artifact checksums with the deployment record. Continue with [node startup](https://docs.paxeer.app/run-node) and [operator roles](https://docs.paxeer.app/operators). ## Prerequisites - **Go:** 1.25.8, as declared in `go.mod`, or the toolchain required by the selected revision - **Rust:** 1.91.1, as declared in `rust-toolchain.toml` - **C compiler:** C17 compiler for the kernel, via the root `Makefile` - **Build tools:** Make and jq; the node also builds the native EVM library through `make evmone-lib` in `chain.mk` - **Git:** For cloning the repository - **Solidity:** 0.8.27 with Foundry, for contract builds - **Native toolchain:** GCC, a C++ compiler and CMake for the native EVM library. The `evmone-lib` target builds that library on Linux/amd64 and fetches its declared source dependencies. Use `LEDGER_ENABLED=false` to disable the optional Ledger build tag. ## Repository Location Clone the [Sidiora-Labs/paxeer-monorepo](https://github.com/Sidiora-Labs/paxeer-monorepo) repository. Chain sources, kernel sources, workspaces, and build configurations share this repository root. The root Go module is `github.com/Sidiora-Labs/Paxeer-X-Network`. ``` git clone https://github.com/Sidiora-Labs/paxeer-monorepo.git cd paxeer-monorepo ``` ## Build the Chain Node Build the node from the repository root. `make paxd-build` builds `build/liblayerx.a`, `programs/target/release/liblayerx_programs_sandbox.a`, and the native EVM library before invoking `chain.mk`, and stamps the version from `tools/release/version.json`. The root node build disables Go module proxy downloads, so populate the declared dependency cache before using it. ``` make paxd-build # build/paxd, linked native libraries and release version stamp make paxeer-build make paxeer-lint make paxeer-test make paxeer-ci ``` `make paxeer-build` and `make -f chain.mk build` also build the linked native prerequisites and produce `build/paxd`, using the chain makefile's version resolver. Root `make build` builds the kernel archive, genesis builder, and module registry. Select the chain explicitly with `chain.mk`: ``` make -f chain.mk build make -f chain.mk install make -f chain.mk test make -f chain.mk ci ``` ### Build Output - `build/paxd` from `make paxd-build`, `make paxeer-build`, or `make -f chain.mk build`. - `$GOBIN/paxd` when GOBIN is set, otherwise `$(go env GOPATH)/bin/paxd`, from `make -f chain.mk install`. - `make workspace-build` combines the kernel, services, node, app and tooling targets, and the root Foundry tree; `make monorepo-ci` delegates to the workspace CI target. ## Build Tags and Flags ### Ledger Support Ledger hardware wallet support is enabled by default in `chain.mk`. To build without ledger: ``` make paxeer-build LEDGER_ENABLED=false ``` ### Mock Balances (Testing) For testing with mock balances: ``` make -f chain.mk install-mock-balances ``` ### Benchmark Build For benchmark runs: ``` make -f chain.mk install-bench ``` ## Version Information The chain version resolver compares matching Git tags and versioned branch names, and uses `tools/release/version.json` when no matching tag exists. Its tag pattern is: ``` paxeer-network/vX.Y.Z ``` Version information is embedded in the binary at build time via linker flags: - `Name`: paxeer - `AppName`: paxd - `Version`: The selected version; `make paxd-build` selects it from `tools/release/version.json` - `Commit`: Git commit SHA Check version: ``` paxd version ``` ## Static Linking Request static external linking for the Go binary with the flag below. The native EVM loader in `engine/executor/lib/evmlib.go` still loads a platform-specific shared library: ``` make paxeer-build LINK_STATICALLY=true ``` ## Go Module The repository root declares the chain Go module: ``` module github.com/Sidiora-Labs/Paxeer-X-Network go 1.25.8 ``` **Note:** The root `go.mod` and `go.sum` govern the chain Go dependencies. Rust components use their own workspace manifests and lockfiles. ## Foundry (Contracts) Chain contracts under `contracts/src/` use `foundry.paxeer.toml`. Fetch the pinned dependencies and build from the repository root: ``` bash contracts/bootstrap-libs.sh FOUNDRY_CONFIG=foundry.paxeer.toml forge build --offline --root . ``` Kernel contracts also live under `contracts/`, using repository-root `foundry.toml` and `tests/solidity/`. See `contracts/README.md` and the [contracts guide](https://docs.paxeer.app/contracts) for the two project configurations. ## Docker Local Docker cluster targets are available. See [Docker documentation](https://docs.paxeer.app/docker) for: - `make docker-cluster-start` - `make run-local-node` - Compose configurations in `docker/` ## Choose a Node Configuration Use the local Docker configuration to try the built binary, or initialize a node with the genesis, peers, and mode for your chosen network. For an existing network, select the binary revision specified by its upgrade plan. ## Next Steps - [Run a node](https://docs.paxeer.app/run-node) - [Configure paxd](https://docs.paxeer.app/configuration) - [Use Docker for local testing](https://docs.paxeer.app/docker) --- URL: https://docs.paxeer.app/interchain # Interchain (IBC) Connect Paxeer X to other chains through IBC packets, native token transfers, and the attested bridge. **Source:** `interchain/`, `precompiles/ibc/`, and the IBC keeper and router wiring in `node/app.go`. ## Cross-chain routes in Paxeer X Paxeer X supports IBC transfers through its Cosmos protocol stack and attested external-chain transfers through the [native bridge](https://docs.paxeer.app/bridge). IBC authenticates packets with light clients, connections, channel state, and packet proofs. The bridge authenticates external deposits with a configured attestor threshold and enforces registered chains, asset caps, nullifiers, and pause controls. The bridge precompile at `0x0000000000000000000000000000000000001016` exposes `bridgeIn`, `bridgeOut`, chain and attestor queries, cap queries, replay status, and pause state. IBC transfers use `0x1009`. Choose the route supported by the destination and asset; an IBC channel identifier is separate from the bridge chain registry identifier. Record the source transaction, destination identifier, asset denomination, amount, and transfer status. Treat packet acknowledgement or timeout separately from bridge attestation and destination release. Continue with [assets](https://docs.paxeer.app/assets), [settlement](https://docs.paxeer.app/settlement), and the [unified network](https://docs.paxeer.app/unified-network). ## Protocol and implementation The in-tree IBC implementation provides clients, connections, channels, packet commitments, and application routing. Relayers submit proofs and carry packets and acknowledgements between chains. A working transfer requires compatible live clients, an open channel, and relayer delivery. Query the target network for the port, channel, counterparty, and supported denomination before sending funds. | Source directory | Purpose | | --- | --- | | `interchain/modules/core/` | Client, connection, channel, port, and commitment protocol logic. | | `interchain/modules/apps/transfer/` | ICS-20 fungible-token transfer messages, packets, and keeper. | | `interchain/modules/apps/27-interchain-accounts/` | Interchain-account implementation. | | `interchain/modules/light-clients/` | Tendermint (`07-tendermint`), solo-machine (`06-solomachine`), and localhost (`09-localhost`) light-client code. | | `precompiles/ibc/` | EVM interface to native ICS-20 transfers. | ## Inspect clients and channels Configure the CLI's Cosmos RPC endpoint for the Paxeer node being queried, then inspect its state: ``` paxd query ibc client states paxd query ibc connection connections paxd query ibc channel channels ``` Verify the channel's port, connection, remote chain, ordering, and open state. Channel identifiers such as `channel-0` are local to a chain; they are not universal destinations. ## Transfer through the CLI This command template sends `1,000,000 uhpx`, one unit of the registered display denomination `hpx`. Set `IBC_CHANNEL` to a verified channel and `IBC_RECIPIENT` to an address valid on its destination chain. ``` paxd tx ibc-transfer transfer \ transfer "$IBC_CHANNEL" "$IBC_RECIPIENT" 1000000uhpx \ --from mykey --chain-id hyperpax_125-1 ``` Use the actual bank denomination for other assets. An IBC voucher has its own denomination trace; do not substitute a display ticker for a bank denomination. ## Transfer directly from the EVM The precompile at `0x0000000000000000000000000000000000001009` exposes two nonpayable transfer methods. Use the full `precompiles/ibc/abi.json` for client bindings. ``` interface IBC { function transfer( string calldata toAddress, string calldata port, string calldata channel, string calldata denom, uint256 amount, uint64 revisionNumber, uint64 revisionHeight, uint64 timeoutTimestamp, string calldata memo ) external returns (bool success); function transferWithDefaultTimeout( string calldata toAddress, string calldata port, string calldata channel, string calldata denom, uint256 amount, string calldata memo ) external returns (bool success); } ``` The immediate EVM caller must have a Paxeer address association and sufficient native-denomination balance. A wrapper uses the wrapper's associated account. `amount` is a bank base-unit integer, not payable EVM value; delegatecall and staticcall are rejected. The explicit method takes an absolute remote timeout height and timestamp. IBC timestamps use nanoseconds. The default-timeout method derives its timeout from the channel's connection and client state: the height is the client's latest height plus the relative default `0-1000` (revision 0, height 1000), and the timestamp is ten minutes in nanoseconds beyond the later of the client consensus timestamp and the current block time. It can fail when required channel or client state is absent. The ABI submits transfers; it does not expose channel enumeration or a general incoming-packet callback. Use the native query interfaces to inspect IBC state. ## Track the whole transfer A successful local transaction means the source-chain transfer was accepted. It does not mean the destination has already received the assets. Retain the source transaction and packet identifiers, then track relay, acknowledgement, or timeout/refund handling on both chains. Configure your relayer for both networks, check that its clients are current, and monitor packet delivery and acknowledgement processing. ## Implementation references - `precompiles/ibc/IBC.sol`: exact public selectors. - `precompiles/ibc/ibc.go`: associated sender, amount conversion, timeout derivation, and keeper invocation. - `interchain/modules/apps/transfer/`: packet lifecycle and native transfer behavior. - [Precompile reference](https://docs.paxeer.app/precompiles) and [native query interfaces](https://docs.paxeer.app/rest-grpc). --- URL: https://docs.paxeer.app/interop # Interoperability Connect agent payments, commerce mandates, card and bank rails, and external chains to Paxeer X through evidence-backed adapters. ## One execution ledger, many entry points Interoperability adapters validate external payment, mandate and settlement evidence and submit authorized transactions to Paxeer X. The kernel executes within the node, and a transaction receipt becomes final when its block commits. An external provider's settlement evidence remains a separate input to reconciliation. The interoperability gateway provides HTTP, MCP, and A2A ingress. Transport selects how a request arrives; the adapter selects how its evidence is validated. Applications keep the same operation identity and reconciliation process across these interfaces. ## Connector catalogue | Adapter | Application journey | Evidence boundary | | --- | --- | --- | | `x402` | Buyer builds payment, seller offers a resource, facilitator verifies and settles | Payment evidence plus verified LayerX receipt; HTTP, MCP, and A2A transports | | `ap2` | Verify an agent commerce mandate and execute within its authority | Verified mandate and LayerX receipt | | `ucp` | Complete a commerce checkout | Checkout evidence and receipt-gated execution | | `visa-tap` | Verify a trusted agent intent and execute its authorized action | Trusted agent credential, canonical target, and policy checks | | `fiat` | Process card, bank, and real-time-payment callbacks | External settlement evidence and LayerX receipt | | `migration-v2` | Import verified account, asset, and history state | Source-chain verification and migration rules | ## Gateway discovery and operation tracking `GET /v1/adapters` exposes adapter metadata and readiness. Track or resume an operation with `GET /v1/operations/{id}`, where `id` is exactly 64 hexadecimal characters and belongs to the authenticated principal. The service also exposes `GET /livez` and `GET /readyz` for process and readiness checks. These paths are relative to the configured interop service origin. ``` # Set these shell variables to your service origin, API key and operation ID. curl "$INTEROP_GATEWAY/v1/adapters" curl -H "Authorization: Bearer $INTEROP_API_KEY" \ "$INTEROP_GATEWAY/v1/operations/$OPERATION_ID" ``` Build the request body from the selected adapter's schema. Adapter requests require a gateway API key in the Authorization header; requests other than provider callbacks also require an Idempotency-Key header. Preserve operation identifiers and evidence digests through retries. A successful HTTP exchange alone does not establish a committed state change. ### Evidence policies | Policy | Required basis | | --- | --- | | `layerx-receipt` | A verified LayerX execution receipt | | `verified-mandate+layerx-receipt` | Accepted mandate authority and a verified execution receipt | | `trusted-agent-credential` | Agent credential accepted by the configured trust policy | | `external-settlement+layerx-receipt` | External rail settlement evidence paired with a verified execution receipt | ## x402 over HTTP, MCP, and A2A x402 supports buyer, seller, and facilitator roles. The same route family accepts `http`, `mcp`, or `a2a` as its transport segment. Capability discovery comes before constructing a payment, so clients can select the supported scheme and network. | Method | Path | Purpose | | --- | --- | --- | | GET | `/v1/{transport}/x402/supported` | Discover payment support | | GET | `/v1/{transport}/x402/facilitator/supported` | Discover facilitator support | | POST | `/v1/{transport}/x402/buyer/build` | Build buyer evidence | | POST | `/v1/{transport}/x402/seller/offer` | Produce a seller offer | | POST | `/v1/{transport}/x402/verify` | Verify payment evidence | | POST | `/v1/{transport}/x402/settle` | Settle through LayerX execution | Verification also has the `/facilitator/verify` variant; settlement has `/seller/settle` and `/facilitator/settle` variants beneath the same x402 prefix. Commitment extras and metered or subscription grant draws let applications bind payments to a resource and consume an authorized allowance over time. ### Paid resource workflow 1. The seller publishes an offer identifying the resource and payment terms. 2. The buyer discovers support and builds evidence for the selected terms. 3. The seller or facilitator verifies the evidence before accepting the purchase. 4. Settlement submits the LayerX operation and verifies its receipt. 5. The application associates resource delivery with the accepted payment operation and retains its evidence for reconciliation. ## Agent commerce and fiat rails | Method | HTTP route | Action | | --- | --- | --- | | POST | `/v1/http/ap2/mandates/verify` | Verify mandate | | POST | `/v1/http/ap2/execute` | Execute authorized mandate | | POST | `/v1/http/ucp/checkouts/complete` | Complete checkout | | POST | `/v1/http/visa-tap/intents/verify` | Verify trusted-agent intent | | POST | `/v1/http/visa-tap/intents/execute` | Execute accepted intent | | POST | `/v1/http/fiat/card/callbacks` | Accept card-rail evidence | | POST | `/v1/http/fiat/bank/callbacks` | Accept bank-rail evidence | | POST | `/v1/http/fiat/rtp/callbacks` | Accept real-time-payment evidence | Unlike x402, these adapters are HTTP-only: there is no MCP or A2A variant of the routes above. Mandate verification establishes what an agent may do before execution changes state. TAP policy binds the trusted agent and canonical request target, with clock-skew limits owned by the service. Fiat callbacks bind external settlement to the LayerX operation; repeating a provider notification must reconcile the original operation rather than credit it twice. ## Migration imports The hosted migration adapter is `migration-v2`. It is served under `/v2`, not the `/v1` adapter prefix, and every route is a POST. Other methods, a `/v1` prefix, or a trailing slash are unknown routes. | Method | Route | Action | | --- | --- | --- | | POST | `/v2/migration/accounts` | Import accounts | | POST | `/v2/migration/assets` | Import assets | | POST | `/v2/migration/history` | Import history | | POST | `/v2/migration/history/read` | Read imported history | ## Portable receipts and mirrors Portable receipt verification checks supplied receipt evidence against independently trusted keys and inclusion facts. Ethereum and Solana mirror implementations publish batch archives and commitments for independent verification; see [Ethereum & Solana Mirrors](https://docs.paxeer.app/mirrors). Mirrors carry verification data; custody remains on Paxeer X. Choose migration for a source-state transition, a mirror for independent archive verification, and the [bridge](https://docs.paxeer.app/bridge) for a custody-backed asset transfer. Preserve the source chain identity and proof material in each case. ## Admission and receipts Adapters submit transactions to the node. A submitted or pending response requires further receipt lookup; it does not establish a committed state change. Verify the receipt's result and block commitment before treating execution as final. Keep the gateway operation identifier, transaction hash, receipt and external settlement evidence together for reconciliation. ## Continue building Explore [bridging and custody](https://docs.paxeer.app/bridge), [execution and settlement architecture](https://docs.paxeer.app/paxeer-vs-layerx), and [native chain APIs](https://docs.paxeer.app/rest-grpc) to connect protocol evidence to chain state. --- URL: https://docs.paxeer.app/json-rpc-unsupported # Unsupported JSON-RPC Methods Ethereum JSON-RPC methods that are explicitly unsupported on Paxeer EVM. **Source:** `rpc/info.go`, `rpc/filter.go`, `rpc/tracers.go`, `rpc/state.go` and `rpc/tx.go` in the Paxeer node source. ## Overview Some Ethereum JSON-RPC methods are **registered** on Paxeer's EVM endpoint but return a **JSON-RPC error** instead of a result. This gives clients and tools a stable, documented failure (code `-32000`) rather than "method not found" (`-32601`). ## Explicitly Unsupported Methods | Method | Typical Error Message | Reason | | --- | --- | --- | | `eth_blobBaseFee` | "blobs not supported on this chain" | EIP-4844 blob transactions not supported | | `eth_newPendingTransactionFilter` | "eth_newPendingTransactionFilter is not supported on Pax EVM RPC" | Only on nodes without a receipt-log feed; sequencer and standby nodes serve it (see below) | | `debug_getRawBlock` | "debug_getRawBlock is not supported on Pax EVM RPC" | Raw RLP block payloads not served | | `debug_getRawHeader` | "debug_getRawHeader is not supported on Pax EVM RPC" | Raw RLP header payloads not served | | `debug_getRawReceipts` | "debug_getRawReceipts is not supported on Pax EVM RPC" | Raw RLP receipt payloads not served | ### Synchronization and raw transactions `eth_syncing` returns `false` when consensus reports the node caught up, and otherwise a progress object with `startingBlock`, `currentBlock` and `highestBlock`. `debug_getRawTransaction` returns raw transaction bytes by hash, or a *transaction not found* error. The raw header, block and receipt-list methods in the table return explicit unsupported errors. ## Error Response Format Unsupported methods return a standard JSON-RPC error: ``` { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "blobs not supported on this chain" } } ``` ## Behavior Notes ### eth_syncing `eth_syncing` is implemented from the consensus status: `false` when the node is caught up, otherwise `startingBlock` (earliest held block), `currentBlock` and `highestBlock`. ### eth_newPendingTransactionFilter On sequencer and standby nodes, which hold the receipt-log feed, this filter is served: each poll returns the hashes of transactions receipted since the last poll, in sequence order. Full-transaction mode (`fullTx: true`) is refused — the filter serves transaction hashes only. On every other node the call returns the `-32000` unsupported error. Independently, the node tracks pending nonces, and `eth_getTransactionCount(address, "pending")` uses the local pending nonce or forwards the request to the appropriate EVM proxy. ### debug_getRaw* Methods Raw RLP-encoded headers, blocks and receipt lists are not served on this RPC surface; use the standard `eth_*` endpoints, which return structured JSON. Raw transaction bytes are the exception: `debug_getRawTransaction` is implemented and returns them by hash. ### eth_blobBaseFee The current implementation rejects EIP-4844 blob transactions in transaction admission. The blob fee RPC returns the explicit unsupported error shown above. ## Broader Compatibility Notes Beyond explicitly unsupported methods, Paxeer's RPC diverges from Ethereum in several conceptual areas: ### Block Tags and Pending Nonces - Committed reads resolve `latest`, `safe` and `finalized` through publication watermarks. Supported `pending` reads use the open execution layer when configured; `eth_getProof` refuses pending state. - Pending nonce queries have a separate path. Do not assume `pending` and `latest` return the same nonce. - A BFT commit provides finality under the consensus protocol’s assumptions. RPC freshness and finality are separate properties. ### Storage Proofs Use a Different Format - `eth_getProof` is implemented by `StateAPI.GetProof`. - Its result contains `address`, `hexValues` and `storageProof`. Storage proofs contain ICS23 proof operations through the application root rather than Ethereum Merkle Patricia trie proofs. - The response excludes Ethereum per-account proof fields because the store has no Ethereum per-account root. Ethereum proof verifiers cannot consume this response unchanged. - The requested height must be readable and the configured store must support proof queries. Historical retention and endpoint availability still apply. ### No Proof-of-Work - `eth_mining` and `eth_hashrate` have no implementation on any registered API, so they return method-not-found (`-32601`), not the registered `-32000` unsupported error. Do not branch on `-32000` for them. - Paxeer uses BFT consensus, not PoW See [JSON-RPC API](https://docs.paxeer.app/json-rpc) for full compatibility details. ## Implementation references The node sources and contract checks are in this repository: ``` rpc/info_test.go rpc/state_test.go rpc/tracers_test.go rpc/filter_test.go ``` For provider-specific method support, check the endpoint configuration and inspect the JSON-RPC result or error returned by each request. --- URL: https://docs.paxeer.app/json-rpc # JSON-RPC API Paxeer's EVM JSON-RPC interface with standard Ethereum compatibility and Paxeer-specific enhancements. For complete read-only examples, follow [Query the EVM](https://docs.paxeer.app/querying-evm) or the [Python Quickstart](https://docs.paxeer.app/python). Use [Debug Transactions](https://docs.paxeer.app/debugging-transactions) to work from a failed receipt to a reproducible diagnosis. **Source:** `rpc/server.go` (registration), `rpc/tx.go` (pending nonces), `rpc/state.go` (proofs), and `rpc/subscribe.go` and `rpc/send.go` (subscriptions) ## Architecture Overview Paxeer serves [Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) at the node's root path. Mainnet-beta uses EVM chain ID 125 (`0x7d`) and BFT block commitment. The source registers the namespaces below; availability on a particular endpoint depends on its configuration and enabled capabilities. ### Namespace Summary | Namespace | Transaction Visibility | Use Case | | --- | --- | --- | | `eth_` | EVM view and native venue receipts | Pure EVM applications, Ethereum tooling compatibility | | `pax_` | Extended EVM/Cosmos views and signed receipts | Allowlisted Cosmos helpers and `pax_sequencerReceipt` | | `pax2_` | EVM + Cosmos + bank transfers | Complete transaction view including native transfers | | `debug_` | EVM tracing and debugging | Transaction replay, gas profiling, state inspection | | `px_` | Native account, kernel and receipt data | Node methods and `px_getReceiptKeys`; hosted gateway methods have their own contract | | `echo_`, `net_`, `web3_` | Liveness, network identity, client version | Standard utility namespaces | | `txpool_` | Mempool inspection | Pending/queued transaction views on HTTP and WebSocket | HTTP registers `echo`, `eth`, `pax`, `pax2`, `px`, `net`, `txpool`, `web3` and `debug`. WebSocket registers `echo`, `eth`, `net`, `web3`, `txpool`, `px` and the signed-receipt method in `pax`. The `test` namespace is HTTP-only and requires explicit enablement on a non-live chain. The hosted gateway's `px_` contract is declared in `services/platform/hosted/gateway/openrpc.json`. ## eth_ Endpoints The `eth_` prefixed endpoints provide the EVM-compatible view, including chain-generated venue receipts where present: - **Transaction selection:** EVM transactions and native venue receipts; Cosmos contract activity uses the extended view - **Ethereum tooling:** Use ethers.js, viem, web3.js, Hardhat, and Foundry with the method-specific differences below - **Transaction view:** EVM transactions, their emitted logs, and supported native venue receipt logs - **Method contracts:** Standard request shapes with documented Paxeer differences ### Key eth_ Methods - `eth_blockNumber` - `eth_getBlockByNumber`, `eth_getBlockByHash` - `eth_getTransactionByHash` - `eth_getTransactionReceipt` - `eth_getLogs` - `eth_call`, `eth_estimateGas` - `eth_sendRawTransaction` - `eth_getBalance`, `eth_getCode` ## pax_ Endpoints The `pax_` prefixed endpoints provide an enhanced view that includes both EVM and relevant Cosmos transactions: - **Synthetic transactions:** Cosmos events (CW20, CW721) exposed as EVM logs - **Extended visibility:** EVM transactions and eligible Cosmos contract activity with synthetic receipts - **Cross-chain events:** Index pointer contracts and token transfers - **Trace filtering:** Variants to exclude pre-state check failures ### Synthetic Transaction Endpoints These endpoints bridge Cosmos and EVM by exposing Cosmos-native events as EVM-compatible logs: - `pax_getLogs` — Enhanced `eth_getLogs` with synthetic logs - `pax_getFilterLogs` — Enhanced `eth_getFilterLogs` with synthetic logs - `pax_getBlockByNumber`, `pax_getBlockByHash` — Include synthetic transactions - `pax_getBlockReceipts` — Include receipts for synthetic transactions **Receipt lookup:** Use the allowlisted `pax_getTransactionReceipt` for Cosmos synthetic receipts. `eth_getTransactionReceipt` also serves native venue receipts by hash. ### Trace Failure Filtering A block can contain transactions that fail before EVM execution, including nonce or balance checks. Use the following endpoints when you need a view that excludes those failures: - `pax_traceBlockByNumberExcludeTraceFail` - `pax_traceBlockByHashExcludeTraceFail` - `pax_getTransactionReceiptExcludeTraceFail` - `pax_getBlockByNumberExcludeTraceFail` - `pax_getBlockByHashExcludeTraceFail` ## pax2_ Endpoints (Bank Transfers) The `pax2_` namespace exposes the same block shape as `pax_` but includes **bank transfers** in block payloads: - Seven methods: block, block receipts, transaction counts, `ExcludeTraceFail` variants - No `pax2_` transaction or filter API - HTTP only (not WebSocket) ### Extended API Gating Extended `pax_*` and `pax2_*` methods on HTTP are gated by `[evm].enabled_legacy_pax_apis` in `app.toml`. The signed-receipt lookup `pax_sequencerReceipt` is exempt from this allowlist: - **New integrations:** Prefer standard EVM methods and the native receipt APIs - **Allow list:** Only methods in the config array are enabled - **Default config:** Three `pax_*` address/Cosmos helpers pre-filled (`pax_getPaxAddress`, `pax_getEVMAddress`, `pax_getCosmosTx`) - **Disabled response:** JSON-RPC error `-32601` with the method's enablement requirement **Coverage:** `rpc/pax_legacy_test.go` ## Transaction Index Mismatches **Important:** Transaction indices differ between `eth_` and `pax_` endpoints. ### Example Consider a block with two EVM transactions and an eligible Cosmos contract transaction, without additional venue receipts: 1. EVM Transaction 1 2. Cosmos Transaction 1 3. EVM Transaction 2 #### eth_getBlockReceipts Returns only EVM transactions with sequential indices: - EVM Transaction 1 (tx index: 0) - EVM Transaction 2 (tx index: 1) #### pax_getBlockReceipts Includes the eligible Cosmos transaction and returns these indices: - EVM Transaction 1 (tx index: 0) - Cosmos Transaction 1 (tx index: 1) - EVM Transaction 2 (tx index: 2) ### Receipts and Logs - **EVM-originating:** Synthetic events included in both `eth_getLogs` and `eth_getTransactionReceipt` - **Cosmos contract transactions:** Their synthetic events are *not* in the ordinary `eth_` transaction view; use `pax_getLogs` and `pax_getBlockReceipts` - **Native venue receipts:** Chain-generated venue receipts can appear in both views; their transaction indices use fixed slots after the block's transaction count ### Best Practice - Use the same endpoint consistently within your application - Account for index differences when switching endpoints - Prefer transaction hashes over indices (hashes are consistent across endpoints) ## debug_ Endpoints Use `debug_trace*` methods to inspect historical execution: - Inspect failed call frames and returned error data - Compare gas consumption across calls and opcodes - Review the state accesses and changes exposed by the selected tracer ### Key debug_ Methods - `debug_traceBlockByNumber`, `debug_traceBlockByHash` - `debug_traceTransaction` - `debug_traceCall` ## Paxeer RPC Distinctions Paxeer's RPC deviates from Ethereum in several areas: ### Block Tags and Pending Nonces - Committed-state reads resolve supported latest, safe, and finalized tags through the RPC publication watermarks; supported pending reads use a configured open execution layer - Pending account nonces have a separate path: `eth_getTransactionCount(address, "pending")` uses the mempool’s next nonce or a configured proxy - Track submitted hashes and use the pending nonce when coordinating multiple transactions from one account ### No Uncle Blocks - Paxeer finalizes blocks through BFT consensus and does not produce Ethereum uncle blocks - The uncle endpoints are registered on HTTP and WebSocket and answer with the empty result: `eth_getUncleByBlockNumberAndIndex` and `eth_getUncleByBlockHashAndIndex` return `null`, and `eth_getUncleCountByBlockNumber` / `eth_getUncleCountByBlockHash` return `0x0` for known blocks ### Storage Proof Format - `eth_getProof` is implemented for proof-capable stores - The result contains `address`, `hexValues`, and ICS23 `storageProof` operations through the application root; it is not Ethereum’s Merkle Patricia account-proof shape - Use a verifier for the returned application-store proof operations and an endpoint retaining the requested committed state; pending proofs are refused ### No Proof-of-Work - `eth_mining` and `eth_hashrate` are not registered on any API, so they return method-not-found (`-32601`) rather than the explicit `-32000` unsupported error - Paxeer uses BFT consensus, not PoW ### No Blobs - EIP-4844 blob transactions not supported - `eth_blobBaseFee` returns error `-32000`: "blobs not supported on this chain" See [Unsupported Methods](https://docs.paxeer.app/json-rpc-unsupported) for the complete list. ## Consistent Historical Reads Pin related reads to one block number and retain its block hash with indexed data. Use a provider with the historical state your application needs, and keep the same namespace when reading blocks, receipts, and logs. ## WebSocket Support Paxeer RPC supports WebSocket for: - `eth_subscribe` for `newHeads` and `logs` - `newPendingTransactions` is served by `SendAPI` when the node has the receipt-backed pending feed; it emits hashes in receipt order and a `lagged` notification if its buffer drops hashes - `eth_unsubscribe` Extended `pax_*` block/filter helpers, `pax2_*` and `debug_` are HTTP-only. WebSocket also serves `pax_sequencerReceipt`, `px_` node APIs and `txpool_`. Use receipt lookup to reconcile notifications with execution results, and verify block commitment for finality. --- URL: https://docs.paxeer.app/launchpad # Launchpad Create fixed-supply instruments, open virtual-reserve markets, trade with explicit limits, and direct accumulated fees. ## From issuance to an active market Paxeer X Launchpad deploys a CREATE2 `SidioraERC20` token, installs its SidioraPool surface, mints an NFT fee right, and opens a virtual-reserve curve in one transaction. The market denomination is `launchpad/` followed by the pool's checksummed `0x`-prefixed address. The implementation is in `modules/launchpad/` and `precompiles/launchpad/`. The instrument represents the issuer's declared terms. Creating a market does not establish equity, revenue rights, or a legal claim automatically. Keep the business identity, creator account, token address, and instrument description visible in your application. 1. Choose a name, symbol, fee strategy, and optical hook address (zero when unused; a nonzero hook must be approved); fund the creator with the configured quote asset and transaction gas. 2. Submit `createMarket(name, symbol, feeStrategy, optical)` to the Launchpad precompile; it returns `(token, pool, nftId)`. A permit variant, `createMarketWithPermit`, takes the same arguments plus permit parameters. 3. Read the committed `MarketCreated` and `PoolRegistered` events and retain the token address, pool address, NFT id, and market denomination. The NFT id is supplied by `PoolRegistered` or a registry query. 4. Inspect reserves and a fresh buy or sell quote before signing an order. 5. Operate fee distribution and market pause controls under the appropriate authority. ## Creation and supply The creation fee is paid in the configured quote token. Launchpad deploys the token with its fixed supply, binds it to the pool with `bindPool`, and transfers the supply to the pool. Market indices start at one and increase per market; the denomination is `launchpad/0x`. The creator begins as guardian and fee-rights holder, and the fee right is represented by the minted NFT (`nftId`). Names contain at most 64 bytes and symbols at most 16. Both are nonblank UTF-8 without surrounding whitespace or control characters. Market supply and initial reserve settings come from protocol parameters rather than a per-call supply argument. ## Curve reserves and executable prices A market tracks virtual quote reserve, real quote balance, and token reserve. Effective quote reserve is the sum of virtual and real quote reserves. Virtual liquidity shapes the pricing curve; it is not a funded quote balance that can be withdrawn. Sells remain constrained by real quote liquidity. The market record includes total supply, cumulative volume, creation time, accumulated fees, pause state, and an eight-slot price-snapshot ring. Use `getPoolPrice(pool)` for a reference price, `getPoolStats(pool)` for reserves, volume, current fee, and market cap, and `quoteExactInput(pool, amountIn, isBuy)` for an amount-specific estimate returning amount out, fee amount, and price impact. `quoteMultihop` quotes token-to-token routes through the quote asset. ## Trade with slippage and expiry limits The precompile is `0x0000000000000000000000000000000000001017`. `buy(pool, usdlAmountIn, minTokensOut, deadline)` and `sell(pool, tokenAmountIn, minUsdlOut, deadline)` are keyed by pool address and take no recipient argument; output goes to the caller. Permit variants (`buyWithPermit`, `sellWithPermit`) and the multihop `swapTokenForToken(tokenIn, tokenOut, amountIn, minAmountOut, deadline)` are also exposed. Both calls are nonpayable: EVM native value is not the quote payment. ``` // launchpad is an ethers Contract using the Launchpad ABI and signer. // pool and quoteIn come from the selected market and user input. const quote = await launchpad.quoteExactInput(pool, quoteIn, true) const minOut = quote.amountOut * 9900n / 10000n // 1% tolerance const deadline = BigInt(Math.floor(Date.now() / 1000) + 120) const tx = await launchpad.buy(pool, quoteIn, minOut, deadline) await tx.wait() ``` This template assumes the connected account has the required quote balance (and allowance, or a permit) and gas. The pool address identifies the market; do not substitute the token or quote asset address. A stale quote does not reserve liquidity. The signed minimum output and deadline protect execution when reserves or fees change. ### Buy and sell fee behavior Fees are charged in the input asset. On a buy, the protocol share of quote fees goes to the treasury and the remainder accumulates for the market's fee-rights holder. On a sell, token fees remain in the token reserve. Dynamic fees use market age and volatility, clamped to configured bounds; a quote supplies the effective rate for that trade. ## Choose where accumulated fees go | Value | Strategy | Execution | | --- | --- | --- | | 0 | Claim | `claimFees(nftId)` pays accumulated quote fees to the fee-rights holder; the accumulator-level `claim(pool, recipient)` requires the fees-router role and pays a chosen recipient. | | 1 | Burn | `executeBurn(nftId)` sends accumulated quote fees to the dead account. | | 2 | Airdrop | `executeAirdrop(nftId)` opens a holder distribution epoch. | | 3 | LP rewards | `executeLpRewards(nftId)` adds accumulated quote fees to real curve reserves. | The fee-rights holder changes strategy with `setFeeStrategy(nftId, newStrategy)` and executes the selected strategy. Fee functions on this surface are keyed by `nftId`; accumulator-level functions are keyed by pool (for example `getAccumulatedFees(pool)`). Burn here directs quote fees to the dead account; it does not burn the launched token's fixed supply. LP rewards reinforce the market's quote backing rather than issuing a separate LP token. ### Holder airdrop epochs Each airdrop records its distribution amount, eligible supply, and snapshot block. Eligible supply excludes the pool and dead-account balances. A claim normally receives the integer floor of epoch amount multiplied by the holder's snapshot balance divided by eligible supply; the final eligible claimant receives the remaining rounding residue. The snapshot is the block before the epoch opens, so later transfers do not rewrite entitlement. A holder claims the current epoch through `claimAirdrop(nftId)` (or the accumulator-level `claimAirdrop(pool, holder)`); each holder claims an epoch once. Use `claimAirdropEpoch(nftId, epoch)` to claim a specified opened epoch. ## Permissions and market controls | Actor | Authority | | --- | --- | | Creator | Funds creation and starts as guardian and fee-rights holder. | | Guardian | Pauses and unpauses market trading. | | Fee-rights holder | Changes fee strategy and executes fee disposition. | | Trader | Spends its own input balance and selects minimum output and deadline; output is paid to the caller. | | Token holder | Claims eligible airdrop entitlement. | | Governance authority | Updates protocol parameters through the governance-authorized parameter message. | Paused markets reject swaps. Orders also reject expired deadlines, zero input, insufficient balances or real liquidity, and output below the signed minimum. These are transaction conditions your interface should explain before prompting for a signature. ## Read markets and track receipts `getAllPools(offset, limit)` paginates discovery; `getPoolCount()` returns the total; `getPoolsByCreator(creator)` groups issuance by creator; and `getPoolByToken(token)`, `getNftIdByPool(pool)`, and `getPoolMetadata(pool)` resolve one market. `getPoolStats`, `getPoolPrice`, and `getMarketCap` support trading views. Markets exist in Generation 1 and Generation 2 SidioraPool forms; new markets are created as Generation 2. Index `MarketCreated`, `Swap`, `FeeFlow`, `FeeDistributed`, `FeeStrategyChanged`, `PoolRegistered`, `PoolStateUpdated`, and `TokenDeployed`. Use `precompiles/launchpad/abi.json` for the event family and the role ABIs under `precompiles/launchpad/abi/` for role events: their signatures differ, and the Router's `MarketCreated` includes the NFT id. Reconcile observations against the committed market record and balances before showing a completed issuance, trade, or claim. ## Protocol settings The default quote token is the USDL ERC-20 at `0x85FcD13735F4309833A503EE804ea32395851479`. Defaults in `modules/launchpad/types/params.go` set virtual quote reserve to `10000000000`, token supply to `1000000000000000` base units, and creation fee to `1000000` quote base units. Fee bounds are 10–300 basis points with a base of 30, and the protocol receives 1000 basis points of buy fees. Read current settings through `creationFee()`, `baseFeeBps()`, and `virtualUsdlDefault()` before estimating costs. Parameter updates require governance authority; EVM administrator setters are refused. Continue with [asset registration and supply](https://docs.paxeer.app/assets), [exchange trading](https://docs.paxeer.app/spot-exchange), [precompile integration](https://docs.paxeer.app/precompiles), and [SDKs](https://docs.paxeer.app/sdk). --- URL: https://docs.paxeer.app/layerx-kernel # LayerX Kernel The deterministic C17 execution core of Paxeer X: one signed activity, one canonical history, and one reproducible result. The LayerX kernel executes native activity across payments, escrow, budgets, streams, services, trading, governance, assets, bridges, and programs. It resolves authority, applies state transitions, produces receipts, and binds each result to the next state root. It runs inside `paxd` through `modules/lxphost/`. Native operations execute in the node's transaction context on the same chain as EVM operations; a receipt is final when its block commits. ## Three execution invariants | Invariant | Meaning for applications | | --- | --- | | One canonical history | The node orders transactions and binds native activity results to global sequences and state roots. Block commitment establishes finality; query indexes derive from committed execution. | | One financial doorway | Modules do not write balances directly. Economic modules and programs propose validated transfer sets, and the only module-to-ledger entry is `lxp_kernel_apply_transfer_set`, preserving a common accounting boundary. | | One reproducible result | Independent replay produces identical receipts and roots from the same ordered input, parameter versions, and batch time. | ## Canonical activities The kernel represents an operation with an `lxp_activity` envelope. Native precompiles resolve the EVM caller's authority and construct the kernel execution context. The activity codec uses fixed-width big-endian integers, explicit fields, and no floating point or maps. A valid decode must re-encode to the same bytes; extra trailing bytes are rejected. | Field | Purpose | | --- | --- | | `protocol_version`, `network_id` | Select the enabled protocol rules and prevent cross-network replay. Version 2 includes occupancy, and version 3 includes state commitment. Use the version configured by the node. | | `activity_type` | The high 16 bits identify the module; the low 16 identify the operation ordinal. | | `actor_did`, `authority` | Identify the principal and primary key, session, or capability grant authorizing the action. | | `account_sequence` | Must exactly match the actor’s next sequence; gaps and stale sequences are refused. | | `timestamp_bound` | Bounds validity using the sealed batch timestamp. | | `idempotency_key` | Binds the retry identity of the activity. Retain the exact signed bytes and key for recovery; do not assume re-executing a duplicate returns the original receipt — recover the outcome through receipt and status reads. | | `fee_limit` | Caps the deterministic execution fee the actor authorizes. | | `payload`, `payload_hash`, `signature` | Bind the operation body to its canonical signing preimage. Direct signed activities use Ed25519; native precompiles supply authority from the authenticated transaction caller. | ## From admission to state transition 1. Decode and check the envelope, including protocol version, network, payload binding, and module enablement. 2. Resolve the actor and authority, validate the applicable signature or native caller authorization, and enforce the account sequence. 3. Evaluate timestamp bounds against batch time. 4. Compute the fee against the active schedule and the activity’s fee limit. 5. Open the state journal; dispatch module validation and execution. 6. Commit successful module effects or roll them back on execution refusal. 7. Apply required fee and sequence bookkeeping and produce a receipt chained to the resulting state root. ### Admission refusal and execution failure Malformed envelopes, wrong-network requests, and payload-hash mismatches fail admission without consuming the kernel account sequence or charging a kernel execution fee. Ordered terminal refusals have a separate receipt path. An admitted execution can roll back module effects while retaining sequence and fee bookkeeping under the active fee policy. EVM gas accounting is separate. Inspect the receipt’s result code and committed state before treating an action as successful. ## Identity is part of execution Agent DIDs identify principals whose account IDs are derived by the protocol account codec. The kernel enforces primary and session keys, scoped grants, rotation, recovery, revocation, and expiry. Delegation can narrow authority without widening it. See [Identity and delegated authority](https://docs.paxeer.app/identity) for the identity lifecycle. ## Determinism across machines Consensus execution uses C17 and deterministic protocol types. It excludes floating point, local wall-clock reads, unstable database iteration, and pointer-derived hashing. Time-dependent rules—including grant expiry, escrow deadlines, stream accrual, funding intervals, and governance activation—read the committed batch timestamp. Oracle observations arrive as signed ordered activities; execution never fetches an external HTTP response. ### Programs share the accounting boundary Module `0x09` executes deterministic WASM programs under the invoking activity’s authority. Program-owned accounts derive from public program identifiers and seeds. Derivation alone grants no debit authority. Nested spending grants narrow the permitted source, destination, asset, and amount. Program monetary effects pass through the same transfer-set entry as other modules, and persisted namespace occupancy is metered and settled as replayable transfer legs. ## Receipts and replay A `lxp_receipt` binds the activity identifier, global sequence, previous and resulting state roots, activity root, result code, effects, fee charged, batch identifier, and module and parameter versions. Program outcomes additionally bind terminal results, runtime and ABI versions, resource metering, transfer evidence, and call-graph commitments. Clients supply activities; the protocol produces receipt evidence. Replay uses the ordered history and committed parameters to reproduce receipts and roots. A root or receipt disagreement refuses the replay. Portable `layerx-receipt-proof-v2` evidence authenticates a signed receipt against independently trusted receipt keys and inclusion facts. A signed receipt records execution; finality on Paxeer X follows when the containing block commits. ### Native integration surfaces The native interface in `include/layerx/lxp_kernel.h` exposes `lxp_kernel_execute_activity` and `lxp_kernel_dispatch`. Prepared-batch APIs separate preparation, commit, and publication; batch-boundary and publication-digest interfaces bind the records being published. Protocol-3 batch maintenance runs escrow deadlines, budget rollover, service defaults, and occupancy finalization within the batch journal. ## Application workflow 1. Select the native precompile or signed-activity interface and the correct network, authority, sequence, fee limit, and validity bounds. 2. Sign the applicable transaction or activity and retain its exact bytes and retry identity. 3. Submit to the node and retain the transaction hash. 4. Verify receipt identity, result, fees, effects, and state-root binding. 5. Verify the containing block's commitment before releasing a resource that requires final execution. ## Continue reading - [Sequencing, checkpoints, and finality](https://docs.paxeer.app/sequencing) - [Programmable execution](https://docs.paxeer.app/programs) - [Identity and delegated authority](https://docs.paxeer.app/identity) - [Payments and accounting](https://docs.paxeer.app/payments) - [Receipt verification](https://docs.paxeer.app/receipts) --- URL: https://docs.paxeer.app/mandates # Payment mandates and trusted agents Authorize direct and autonomous purchases with signed AP2 mandates, exact asset bindings, and trusted-agent request verification. ## Separate the agent, the authorization, and the payment Paxeer X verifies who presents a commerce request, what the payer authorizes, and what payment executes. Visa Trusted Agent Protocol supplies signed agent credentials and intent tags. AP2 supplies signed mandate constraints and checkout bindings. The interoperability service binds verified authorization to a payer-signed EVM payment and returns verified settlement evidence. Each step retains its own verification boundary. ## AP2 v1 mandate verification The Rust AP2 verifier in services/interop/crates/layerx-ap2 verifies SD-JWT and JOSE mandate material and evaluates its constraints before preparing payment. Direct mode handles direct authorization; autonomous mode evaluates delegated purchasing authorization, including the applicable line-item constraints. Verification binds payment and checkout identities, merchant details, amount, currency, payment instrument, audience, nonce, and validity conditions. | Verification input | Purpose | | --- | --- | | `now` and `clock_skew_seconds` | Evaluate validity windows with an explicit clock and permitted skew. | | `expected_audience` | Require the mandate to target the expected audience. | | `expected_nonce` | Bind verification to the expected authorization context. | | `currency_minor_exponent` | Interpret the payment currency at its correct minor-unit precision. | | `usage` | Evaluate an open mandate against caller-supplied prior-use facts in the Rust verifier. | ### Bounded autonomous authorization For an open payment mandate, retain a usage record with its exact mandate reference, frequency, previous occurrence count, amount already spent in minor units, and next eligible execution time. The reference is the AP2 `sd_hash` of that specific mandate, preventing usage facts from being applied to a different authorization. Supply these facts explicitly to the Rust verifier for the next purchase. The hosted HTTP handler supplies no usage record and therefore cannot verify constraints that require prior-use facts. The verification context requires a positive timestamp, nonempty audience and nonce, a currency minor exponent no greater than 18, and clock skew no greater than 3,600 seconds. These are verifier input bounds enforced before constraint evaluation; the mandate still has to pass its signed constraints. The adapter profile is AP2 v1 (`ap2-v1-signature-constraint-receipt-verified`). ## Bind authorization to actual settlement A verified mandate becomes an authorized payment only after its merchant and currency match the configured LayerX asset binding. The binding identifies the asset, payer and payee receipt accounts, minor-unit exponent, and atomic units per currency minor unit. Amount conversion uses checked multiplication and rejects overflow or a zero result. ``` asset atomic amount = mandate minor units × atomic units per minor unit idempotency identity = principal + stable payment reference request binding = mandate material + currency + asset + payer account + payee account + amount ``` The idempotency identity remains stable across retries of the same principal and payment reference. The request digest commits to the signed authorization material and settlement binding. An explicit execution date is already bound by the signed presentations; a locally resolved execution time does not change the digest on retry. ## Interoperability service routes | HTTP route | Operation | | --- | --- | | `POST /v1/http/ap2/mandates/verify` | Verify signed mandate material and its constraint context. | | `POST /v1/http/ap2/execute` | Validate and relay the payer-signed payment, then export signed receipt evidence. | | `POST /v1/http/visa-tap/intents/verify` | Verify a trusted-agent request. | | `POST /v1/http/visa-tap/intents/execute` | Verify the trusted-agent request and relay its authorized payment. | 1. Send checkout_presentation, payment_presentation, and nonce. The HTTP handler uses its server clock, configured audience and currency precision, and zero clock skew to verify the mandate pair. 2. Evaluate the signed merchant, amount, checkout, and applicable autonomous constraints. 3. Apply the asset and receipt-account binding configured for the authenticated principal. 4. For execution, include activity as hex-encoded, payer-signed EIP-1559 transaction bytes. The service checks the payment accounts, asset, amount, reference and expiry before relay. 5. A pending relay returns HTTP 202. Once execution evidence verifies, the configured receipt signers export payment_receipt_jwt and checkout_receipt_jwt. ## Visa Trusted Agent Protocol The TAP adapter verifies RFC 9421-style `sig2` request signatures against a trusted-agent registry. The `agent-browser-auth` tag identifies browsing intent and `agent-payer-auth` identifies payment intent. Verification checks the validity window, registered key status, signature algorithm, signed request target, cryptographic signature, and nonce uniqueness. ### Replay protection and credential binding A nonce window consumes the nonce together with its key identifier and expiry. A verified credential can be associated with a LayerX agent through the credential-binding store. That association records identity context; payment authority still requires the matching payer-signed transaction. A valid agent signature does not by itself supply the payer's mandate or authorize an arbitrary transfer. Maintain the registry's key status and validity information, use canonical authority and path representations for signature verification, and preserve nonce state across the merchant request lifecycle. Browse and pay operations retain distinct intent tags so an operation is evaluated in its declared context. ## Portable purchase evidence Completed AP2 execution returns signed evidence containing portable LayerX receipt evidence. Payment and checkout receipt references preserve the exact verified authorization bindings. The portable mandate-pair format carries the external evidence needed by `Ap2ExternalMandateVerifier`, allowing verification to travel with the purchase evidence. Retain the signed mandate pair, signed payment transaction, canonical execution receipt, independent receipt-key trust configuration, merchant checkout identity, and applicable mandate usage facts. Keep raw payment credentials out of operational logs. Use [agent commerce](https://docs.paxeer.app/commerce) to connect this authorization flow to merchant checkout, order reads, and paid-resource fulfillment. --- URL: https://docs.paxeer.app/market-makers # Market Makers Provide exchange liquidity and operate independent asset ramps with bound quotes, authorized payments, durable reconciliation, and receipt-gated settlement. ## Two liquidity workflows Market-making applications use the network execution interfaces and the ramp toolkit under services/platform/ramps/toolkit. On exchange books, a maker posts resting bids and asks and manages the inventory committed to those orders. An independent ramp operator quotes conversions between LayerX assets and an external payment or payout system. Exchange orders and ramp orders have distinct execution and custody models. | Workflow | Inventory | Execution evidence | | --- | --- | --- | | Spot quoting | Base or quote units escrowed for resting orders | Matching result and asset settlement receipt | | On-ramp | Operator LayerX assets and external funds | External settlement followed by verified LayerX delivery | | Off-ramp | Customer-authorized LayerX payment and operator external payout inventory | Verified LayerX payment followed by external payout settlement | ## Quote exchange liquidity Create separate order identifiers for each quote, size bids against quote-asset inventory and asks against base-asset inventory, and submit limit GTC orders to the [spot book](https://docs.paxeer.app/spot-exchange). Matching uses best price and time priority; fills execute at the resting order's price. Update exposure from verified fills and residual order state. Before repricing, cancel the old order and reconcile the result. Maintain separate records for free inventory, inventory reserved by resting quotes, and completed trades. Market halts stop new placement; an agent's quoting policy should inspect market state and stop replacement submissions while a market is halted. ## Independent ramp custody The ramp toolkit binds a customer, operator, quote, and authorization into one order. The operator controls off-platform funds and payout. Show the toolkit's custody disclosure wherever the customer reviews or tracks a ramp: External custody: this independent market maker controls the off-platform funds and payout. The LayerX receipt proves the LayerX payment leg. External payment settlement comes from the provider's evidence and remains a separate obligation. A complete ramp order reconciles both. ## Bind the quote | Terms | Purpose | | --- | --- | | `quote_id`, direction, expiry | Identify the offer, on-ramp or off-ramp flow, and validity window | | LayerX asset and amount | Bind the exact on-platform inventory movement | | External currency and minor-unit amount | Bind the external payment amount without floating-point ambiguity | | Rate numerator and denominator, fee, maximum slippage | Make the conversion terms explicit | | Context, provider token, payout token | Bind the intended payment context and provider operation | `RampOrder::bind` validates the quote and customer/operator identities, matches the requested quote identifier, and computes an order digest. Customers and operators use the `AgentMain` account namespace. On-ramp orders use operator authorization; off-ramp orders require a customer-owned payment budget and its purpose hash. The digest commits to the quote, principals, operator signing-key handle, context, and budget authorization references. ``` RampOrder::bind(request, quote, customer, operator, now) -> order_digest On-ramp: external provider settles -> operator sends LayerX asset -> verify receipt Off-ramp: customer-signed budget spend -> verify LayerX payment -> external provider settles ``` This is the toolkit workflow, not an HTTP endpoint. Integrate through the toolkit's typed clients and your provider's actual contract. ## Execute an on-ramp 1. Authenticate the customer and obtain a valid quote with exact LayerX and external amounts. 2. Bind and journal the order, then complete the compliance decision and external collection workflow. 3. Reconcile external provider settlement before preparing the LayerX delivery. 4. Use `compile_operator_send(order)`, which takes only the bound order and returns a `LedgerCall` to `LEDGER_ADDRESS` carrying `encode_pay_exact(..., order_digest)`. It refuses orders that are not operator-funded on-ramps without a payer grant. 5. Retain the signed EVM transaction before submission. Resolve pending or unknown submissions by transaction hash. 6. Verify the signed receipt, committed settlement evidence and bound order before completing delivery. ## Execute an off-ramp 1. Bind the customer's quote, customer_budget_id and customer_budget_purpose into the order. The Rust fields are payer_grant and payer_grant_purpose. 2. Use `compile_customer_payment(order)` to construct a budget spend to `PAY_ADDRESS`. `compile_payer_grant_draw(order, _receiver_sequence)` delegates to the same compiler. The customer signs the exact EVM transaction; the client checks the signed payment and budget ownership, purpose, asset and expiry before submission. 3. Verify the LayerX payment receipt before initiating the provider payout. 4. Reconcile the provider operation or authenticated callback and retain its evidence digest. 5. Complete the order after the external payout settles. Surface refusal, reversal, or manual review as distinct outcomes. ## Verify payment evidence `verify_order_receipt` verifies the receipt signature under configured height-range keys, binds it to the signed transaction hash, requires a successful result, and verifies the log commitment. On-ramp evidence must contain exactly one matching exact-payment event; off-ramp evidence must match the compiled budget-spend transaction and its event. On success it returns a `VerifiedLayerxLeg` with `tx_hash`, `receipt_digest`, `height`, and `rung`, derived from the sequencer signature and log binding. A provider callback is verified against the bound order and provider public key before it changes the journal. Callback identifiers and provider sequence numbers support replay handling. Keep the order digest, activity identifier, receipt digest, and provider evidence digest together in the customer's operational record. ## Durability and recovery The journal uses the domain `LXP/market-maker-ramp/journal/v2`; records also bind workflow stage and evidence under `order_digest`. Worker leases coordinate order progression. The engine records the signed transaction and its hash before broadcasting, so recovery can reconcile the same payment. Unknown submission status remains unknown until reconciled. | Customer status | Operational meaning | | --- | --- | | Pending | A payment or payout is progressing | | Unknown | Submission outcome requires lookup and reconciliation | | Refused | A leg refuses; retain the refusal code | | Manual review | The provider requires an operator decision | | Reversed | The provider reports a reversal | | Done | The direction-specific settlement gates are satisfied | ## Rebalance Paxeer inventory `InventoryRebalancer` journals custody transfers under an idempotency key and reconciles the retained operation identifier and transaction hash. Reusing a key with different asset or amount terms returns a conflict. Polling retrieves and authenticates the signed receipt and committed settlement evidence through the LayerxClient, then records block identity and settlement level. A broadcast hash alone is a submitted outcome. ## Integration map The toolkit lives at `services/platform/ramps/toolkit` and exposes `clients`, `engine`, `evm`, `journal`, and `migration` modules. Use `QuoteTerms` and `RampOrder` for order binding, the compilation helpers for authorized payment construction, `verify_order_receipt` for payment verification, and `RampPresentation` for customer-facing status. Continue with [Spot Exchange](https://docs.paxeer.app/spot-exchange), [EVM Precompiles](https://docs.paxeer.app/precompiles), and [Paxeer Modules](https://docs.paxeer.app/modules). **Protocol references:** `services/platform/ramps/toolkit/src/lib.rs`, `services/platform/ramps/toolkit/src/engine.rs`, `services/platform/ramps/toolkit/src/journal.rs`, and `include/layerx/lx_spot.h`. --- URL: https://docs.paxeer.app/mcp # MCP tools Connect assistants to verified Paxeer X state and policy-governed wallet and token operations through 22 scoped MCP tools. ## One governed execution path `layerx-mcp` exposes a 22-tool catalogue to MCP clients. Calls are authorized by `layerx-agentd` and recorded as a `DaemonInvocation`, with Policy, Capability, Budget, RateLimit, and Audit gates on ordinary daemon operations. `faucet.request` uses session and capability authorization and invocation auditing, then calls the configured gateway directly (below). The same authorization and submission rules apply when an assistant uses a tool as when an application calls the daemon. A read-only deployment exposes read tools and omits writes. Tool discovery is filtered to the caller's scopes. Native wallet and token aliases also require an enabled native profile, the required activity capability, and authorization for every preparation, disclosure, signing, submission and tracking stage. ## Tool catalog | Tool | Kind | Required scope | Daemon operation | Purpose | | --- | --- | --- | --- | --- | | `tenant.readiness` | read | `read` | `TenantReadiness` | Read daemon-local readiness; the evidence is explicitly unverified protocol state. | | `balance.get` | read | `read:balance` | `ReadBalance` | Read verified program-scoped balances from the daemon with their verification level and freshness. | | `history.list` | read | `read:history` | `ReadHistory` | Page verified account history from the daemon under an explicit item bound and stable cursor. | | `receipt.get` | read | `read:receipt` | `ProgramReceipt` | Read the canonical receipt the daemon holds for one activity. | | `checkpoint.get` | read | `read:checkpoint` | `ReadCheckpoint` | Read native committed-block evidence, including the header, BFT commit and validator set, for the requested height. | | `proof.get` | read | `read:proof` | `ReadProofBundle` | Read the proof bundle the daemon holds for one activity. | | `availability.get` | read | `read:availability` | `AvailabilityFetch` | Read verified availability chunks and attributed failures for one decimal batch number. | | `wallet.accounts` | read | `read:wallet:accounts` | `ReadAccount` | List the verified accounts the daemon observes for one program. | | `wallet.balance` | read | `read:wallet:balance` | `ReadBalance` | Read one verified account balance for one asset through the daemon. | | `activity.prepare` | write | `write:prepare` | `Prepare` | Prepare canonical activity bytes and their bound disclosure inside the daemon. | | `activity.disclose` | write | `write:disclose` | `Prepare` | Decode the bound disclosure of canonical activity bytes. | | `activity.sign` | write | `write:sign` | `Sign` | Sign a daemon preparation at the daemon's external signing boundary; no key material is read. | | `activity.submit` | write | `write:submit` | `Submit` | Submit an externally signed preparation through the ordinary daemon path. | | `activity.track` | write | `write:track` | `Track` | Resolve the daemon's current state for one submission. | | `activity.wait` | write | `write:activity:wait` | `Wait` | Wait, under an explicit bound, for the daemon to resolve one submission. | | `wallet.send` | write | `write:wallet:send` | `Submit` | Send one asset amount through the ordinary daemon submission path. | | `token.create` | write | `write:token:create` | `Submit` | Create one asset through the ordinary daemon submission path. | | `token.mint` | write | `write:token:mint` | `Submit` | Mint one asset amount through the ordinary daemon submission path. | | `token.transfer` | write | `write:token:transfer` | `Submit` | Transfer one asset amount through the ordinary daemon submission path. | | `grant.issue` | write | `write:grant:issue` | `Submit` | Submit the grant-issuance alias through native preparation; ledger payer-grant issuance is retired and refuses execution. | | `grant.draw` | write | `write:grant:draw` | `Submit` | Submit the grant-draw alias through native preparation; ledger payer-grant draws are retired and refuse execution. | | `faucet.request` | write | `write:faucet:claim` | — | One testnet funding request through the configured gateway's `px_requestFunds`; returns the funding transaction hash or a refusal. The session token accompanies the request. | ## Session and web tools Two further surfaces are served alongside the main catalogue. The session surface carries 11 tools bound to the caller's session: `subscription.create`, `subscription.list`, `subscription.pause`, `subscription.resume`, `subscription.delete`, `subscription.health`, `subscription.acknowledge`, `approval.list`, `approval.get`, `approval.approve` and `approval.reject`, each mapping to the daemon operation of the same name. The web surface carries 3 paid tools — `web.search`, `web.fetch` and `web.content` — which map to daemon `Submit`, spend through the approval boundary to the configured web-search sidecar, and return a sequencer-signed settlement receipt alongside untrusted external content. Treat returned web content as external input, never as verified chain state. ## Tool parameters A hex32 value represents 32 bytes in hexadecimal; hex64 represents 64 bytes. Integer arguments are decimal strings; height, batch and timeout values must fit their declared bounds. Native signatures are 65 bytes and EVM signer addresses are 20 bytes, encoded as lowercase hexadecimal without a prefix. The native aliases require a native_write_v1 envelope containing intent, preparation, canonical_bytes, signature and signer_address. The intent fields appear below; token creation uses supply_cap. Obtain the full request schema from tool discovery. Catalog validation bounds encoded JSON to 65,536 bytes. | Tool | Arguments or intent fields | Further requirements | | --- | --- | --- | | `balance.get` | `program` (hex32) | `account`, `asset` (hex32) | | `history.list` | `account` (hex32), `limit` (1–256) | `cursor` (hex32) | | `receipt.get` | `activity_id` (hex32) | — | | `checkpoint.get` | `sequence` (committed block height) | — | | `proof.get` | `activity_id` (hex32) | — | | `availability.get` | `batch` (decimal u64) | — | | `wallet.accounts` | `program` (hex32) | — | | `wallet.balance` | `program`, `account`, `asset` (hex32) | — | | `activity.prepare` | `variant`, `payload`, `account_sequence`, `not_before`, `not_after`, `fee_limit`, `idempotency_key` | Use the discovered native_v1, native_effect_v1 or native_send_v1 schema, including activity, actor, authority, payload hash, capability and signed purpose. | | `activity.disclose` | `canonical_bytes` | — | | `activity.sign` | `preparation_ref` and a 65-byte external signature | Use external_signature_v1; the signer supplies the EVM signature. | | `activity.submit` | `preparation_ref`, `signature` (65 bytes), `signer_address` (20 bytes) | Use native_send_submit_v1 for native sends; alternatively supply only raw_transaction with signed EIP-1559 bytes. | | `activity.track` | `submission_ref` | — | | `activity.wait` | `submission_ref`, `timeout_ms` (1–600000) | — | | `wallet.send` | `destination`, `asset`, `amount`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `token.create` | `symbol`, `decimals` (0–18), `supply_cap`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `token.mint` | `asset`, `destination`, `amount`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `token.transfer` | `asset`, `destination`, `amount`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `grant.issue` | `beneficiary`, `asset`, `amount`, `expires_at_ms`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `grant.draw` | `grant_id`, `amount`, `idempotency_key` | Fields belong in intent within native_write_v1; include the bound preparation, canonical bytes, EVM signature and signer address. | | `faucet.request` | `did`, `public_key` (hex32) | — | ## Prepare, disclose, sign, submit Prepare the EIP-1559 call through the selected native request schema, including its signed purpose and capability. Read the bound disclosure before authorizing the transaction. `activity.sign` accepts an externally produced signature for the preparation; it does not create a signing key. Submit the preparation reference with the EVM signature and signer address, then track the submission or wait under an explicit timeout. `activity.wait` accepts 1–600000 milliseconds. A timeout bounds waiting; it does not reverse a submitted activity. Continue tracking the same submission reference and preserve the business action idempotency key. ## Read verified state and settlement evidence Use balances with their verification level and freshness, bounded history pages with stable cursors, canonical receipts, committed block headers and BFT commits, and proof bundles. `availability.get` returns verified chunks and attributed failures for a batch. `tenant.readiness` is the exception: it reports daemon-local readiness only and its evidence is unverified. Read operations otherwise retain the daemon verification context instead of asking a model to infer settlement from prose. ## Wallet, token, grant, and faucet journeys Wallet sends, token creation, minting and transfers use the native preparation and submission path when authorized and enabled. Token decimals are bounded to 0–18. The grant aliases target retired ledger payer-grant methods and return refusals; payment budgets use the maintained payment module. Faucet requests bind the DID and public key and execute as one `px_requestFunds` call against the configured gateway, whose funding policy determines availability. Integrate tools alongside [XDK](https://docs.paxeer.app/xdk) and [SDK quickstarts](https://docs.paxeer.app/sdk-quickstarts). Inspect [Agent API](https://docs.paxeer.app/platform-api) for canonical write semantics and [the agent daemon](https://docs.paxeer.app/agent-runtime) for its execution boundary. --- URL: https://docs.paxeer.app/mirrors # Ethereum & Solana Mirrors Publish Paxeer X batch archives to external chains and verify committed receipt evidence independently of a hosted gateway. ## External access to canonical evidence The mirror system builds committed batch archives, publishes them to Ethereum or Solana, and retrieves them through independently configured chain sources. A consumer can then verify an archived receipt under its own sequencer key configuration without contacting the Paxeer X gateway. Mirror publication distributes evidence. Paxeer receipts are final once validators commit their blocks. External-chain publication confirms archive availability under that chain's rules; it does not authorize a Paxeer transfer. ## Publisher and verifier roles | Component | Responsibility | | --- | --- | | `layerx-mirror-publisher` | Acquire committed node data, construct archives, publish to configured targets and track durable progress | | `layerx-mirror-verify` | Read configured mirror sources and verify a committed archive or one archived receipt | | `MirrorVerifier` | Admit a committed archive, return its committed coordinate, and verify a receipt by index under configured sequencer keys | | `PublicationJournal` and archive spool | Preserve publication phases and exact archive material through restart | ## Trust configuration The verifier configuration carries `layerx_network_id`, a `receipt_keys` list, and a `sources` list. Each receipt key pins `sequencer_id_hex`, `public_key_hex`, and the `first_height`/`last_height` window in which that key authorizes receipts. This trust material is configured independently of archive payloads; an archive cannot authorize its own signing key or extend its height window. A configuration with no receipt keys is refused. | Source | Identity pins | | --- | --- | | Ethereum | RPC quorum, chain ID, genesis hash, archive contract, archive code hash and publisher identity | | Solana | RPC quorum, genesis hash, archive program, upgradeable loader, program-data account, program code hash and publisher identity | Retain target-chain identity and canonical position with each observation. On Ethereum this includes the observed block and reference head; on Solana it includes the rooted slot and block hash. ## Publish an archive ``` layerx-mirror-publisher layerx-mirror-publisher --probe ``` The second form probes the publisher's status listener for readiness instead of starting the service. Any other argument shape exits with a usage error. 1. Read committed blocks from the configured Paxeer source, starting at the configured first height. 2. Build and validate the archive, preserving its exact canonical bytes and content commitment. 3. Persist publication intent, obtain target-chain signatures and broadcast. 4. Observe configured chain confirmation or rooting, retrieve the published archive and verify the bytes. 5. Advance the durable publication cursor only through the recorded publication workflow. Publisher configuration includes the state directory, first height, polling interval, committed-block freshness budget, status listener address, and the Paxeer committed-source section. The Ethereum target is configured explicitly; the Solana section is optional and validated when present. ### Recover publication safely The publication journal distinguishes prepared, pre-broadcast failure, signed, broadcast-unknown, pending, finalized, and retrieved-verified states, alongside permanent refusal, reorganization, and expired broadcast. When broadcast status is unknown, resolve chain history before issuing a replacement nonce or blockhash. Readiness includes committed-block freshness against the configured block budget. A healthy process and a completed historical publication do not by themselves establish that every target is current. ## Read policies | Policy | Behavior | Use | | --- | --- | --- | | `exact` | Read one source locator and commitment | Audit a specific publication | | `ordered-preference` | Use an explicit ordered candidate set | Controlled source failover | | `agreement` | Require a configured minimum agreement among candidates | Cross-source corroboration | A candidate identifies the configured source index and exact archive commitment. The command reports source or RPC divergence as divergent, alongside insufficient-agreement, missing, rate-limited and unavailable outcomes. ## Verify from a mirror Prepare a verifier configuration with your independent network and source pins, then save the JSON request below as receipt-request.json and supply it on standard input. A receipt request names the archived receipt by its index within the batch. Replace the commitment placeholder with the 32-byte archive commitment: ``` { "batch_number": "12", "evidence": { "kind": "receipt", "index": 0 }, "policy": { "kind": "exact", "candidate": { "source": 0, "commitment_hex": "REPLACE_WITH_32_BYTE_ARCHIVE_COMMITMENT_HEX" } } } ``` ``` layerx-mirror-verify < receipt-request.json ``` The verifier fetches the archive from the pinned source, checks its commitment and batch, and verifies the sequencer signature over the archived receipt bytes against the receipt key whose height window covers the batch. It does not take receipt bytes from the caller: a request carrying fields such as `canonical_hex` is refused, because unknown request members are denied. There is no state-proof request in this command; the only other evidence kind is `committed`, which verifies the archive's committed coordinate without selecting a receipt. Batch numbers are nonzero canonical decimal strings without leading zeros. Receipt indices at or above 1,048,576 are out of bounds, and the request body is capped at 40 MiB. ## Interpret the result On success the verifier prints `{ "ok": true, "verification": { ... } }`. The verification object contains `level`, `evidenceDigest`, `sourceId`, `target`, `canonicalPosition`, `provenance`, `latestBatch`, `batchLag`, `failoverCount`, `agreeingSources`, `committedHeight`, and `committedBlockHash`. Failures print `ok: false` with an error code. The only evidence level is `Committed`: the archive was admitted under the pinned source commitment and, for a receipt request, the receipt's sequencer signature verified. The report identifies the admitted committed height and block hash. Freshness is reported separately through `latestBatch` and `batchLag` and can be unknown. Store the observation and trust configuration with the evidence so later readers can distinguish historical validity from current coverage. ## Library verifier In Rust, `MirrorVerifier::from_committed_source` or `admit_committed` admits archive bytes against an observation, refusing a mismatched source commitment or batch. `committed()` returns the committed height and block hash retained in the archive. `committed_receipt(index, keys)` verifies one archived receipt under the supplied sequencer height-range keys. Admission checks the archive against its independently observed source commitment. To verify BFT consensus or application state independently, use native block-commit evidence and the relevant state proofs in addition to the mirror report. ## Archive retention and audit Keep the archive commitment, canonical archive bytes, trusted sequencer key windows, target identity, canonical chain position and evidence verification result together. For independent settlement verification, retain native block-commit evidence and the trusted validator configuration as well. Continue with [Relay & Archive Nodes](https://docs.paxeer.app/relay-archive) for public history endpoints, [Receipts & Proofs](https://docs.paxeer.app/proofs) for portable verification, and [Data Availability](https://docs.paxeer.app/data-availability) for authenticated replay bundles. --- URL: https://docs.paxeer.app/modules/epoch # Epoch Module Time-based hooks and epoch lifecycle management for coordinating periodic chain operations. **Source:** `modules/epoch/` ## Overview The epoch module manages fixed time periods (epochs) and triggers registered hooks when an epoch ends and the next begins. An epoch defaults to **60 seconds** (`time.Minute` in genesis). Hooks run during `BeginBlock`. In this codebase only one hook consumer is wired in `node/app.go`: the mint keeper. Validator-set updates, parameter activation, and periodic cleanup are not epoch-hook consumers here. ## State The epoch module maintains a single epoch state object. Query it with the command below; the JSON illustrates default genesis values before initialization. Initialization replaces these default timestamps with consensus block time; a running chain returns its stored epoch: ``` paxd query epoch epoch --output json { "epoch": { "genesis_time": "1970-01-01T00:00:01Z", "epoch_duration": "60s", "current_epoch": "0", "current_epoch_start_time": "1970-01-01T00:00:01Z", "current_epoch_height": "0" } } ``` - **genesis_time:** Chain genesis time (fixed) - **epoch_duration:** Duration of each epoch (default 60s) - **current_epoch:** Current epoch number (increments at each epoch boundary) - **current_epoch_start_time:** Timestamp when the current epoch started - **current_epoch_height:** Block height at which the current epoch started ## Epoch Boundaries Epochs are defined by wall-clock time, not block height. In `BeginBlock` (`modules/epoch/keeper/abci.go`) a new epoch begins only when the block time is *strictly after* the boundary: ``` if ctx.BlockTime().Sub(lastEpoch.CurrentEpochStartTime) > lastEpoch.EpochDuration { // advance exactly one epoch } ``` - The comparison is strict (`>`), not `≥`. - It is a single `if`, not a loop: at most one epoch advance per block, even after a long halt. - The new start time is `oldStart + epoch_duration`, not the current block time, so the schedule does not drift to block time. ## Hooks Other modules implement the `EpochHooks` interface (`modules/epoch/types/hooks.go`): ``` type EpochHooks interface { AfterEpochEnd(ctx sdk.Context, epoch Epoch) BeforeEpochStart(ctx sdk.Context, epoch Epoch) } ``` At a boundary the keeper runs them in this order: 1. `AfterEpochEnd(ctx, lastEpoch)` — for the epoch that is ending 2. `SetEpoch(newEpoch)` — store the incremented epoch 3. `BeforeEpochStart(ctx, newEpoch)` — for the epoch that is starting 4. Emit the `new_epoch` event Each hook runs in a cached context (`ctx.CacheContext()`). Its writes are committed only if the hook completes; a hook panic is re-raised and aborts the block rather than advancing the epoch without the hook's state transition. ### Example: Mint Module The mint module (`modules/mint/keeper/hooks.go`) implements epoch hooks: `BeforeEpochStart` is a no-op and `AfterEpochEnd` performs the daily release check. It is the only hook registered in `node/app.go`: ``` app.EpochKeeper = *epochmodulekeeper.NewKeeper( appCodec, keys[epochmoduletypes.StoreKey], keys[epochmoduletypes.MemStoreKey], app.GetSubspace(epochmoduletypes.ModuleName), ).SetHooks(epochmoduletypes.NewMultiEpochHooks( app.MintKeeper.Hooks())) ``` ## Events The epoch module emits a `new_epoch` event at each epoch boundary: - **epoch_number:** The new epoch's epoch number - **epoch_time:** The new epoch's start time - **epoch_height:** The block height at which the new epoch started ## Messages The epoch module does not expose any transactions. Its handler rejects every message as unrecognized. Only the module itself updates epoch state during `BeginBlock`. ## Parameters The epoch module has no runtime parameter fields: `Params` is empty. The epoch duration lives in the epoch genesis state. ## Use Cases - **Mint module:** The only wired consumer; its `AfterEpochEnd` hook checks whether a daily release is due. See [Mint module](https://docs.paxeer.app/modules/mint) ## Next Steps - [Understand how the mint module uses epochs](https://docs.paxeer.app/modules/mint) - [Review all Paxeer modules](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/modules/mint # Mint Module Scheduled native token release through epoch hooks, with daily amounts derived from the remaining supply and governed release dates. **Source:** `modules/mint/` ## Overview The mint module creates new native tokens according to a predefined schedule: a `total_mint_amount` released between a start date and an end date. There is no block-by-block inflation rate. Minting is driven only by the epoch module's `AfterEpochEnd` hook and releases at most once per UTC date. ## Minting Mechanism On each epoch end, the hook (`modules/mint/keeper/hooks.go`) loads or updates the current minter from the release schedule, then computes today's release from the *ending epoch's start time* — not the current block time: ``` coinsToMint := latestMinter.GetReleaseAmountToday(epoch.CurrentEpochStartTime.UTC()) ``` `GetReleaseAmountToday` (`modules/mint/types/minter.go`) applies these rules, in order: 1. Before the start date, or if a mint already happened on that UTC date (`last_mint_date` matches): release `0` 2. Past the end date, or with zero days left: release **all** of `remaining_mint_amount` 3. Otherwise: release `remaining_mint_amount / days_between(today, end_date)` (integer division) If the amount is zero or nothing remains, the hook returns without minting. Otherwise it mints the coins (`MintCoins`), sends them to the `fee_collector` account (`AddCollectedFees`), and records the mint: `remaining_mint_amount` decreases and `last_mint_amount`, `last_mint_date`, and `last_mint_height` are updated. The distribution module then handles collected fees as usual. ### Example For an illustrative schedule with `total_mint_amount = 1,000,000` base units and 100 days between the initial release date and the end date: - Initial daily mint: `1,000,000 / 100 = 10,000` base units/day - After 50 days: `500,000 remaining / 50 days = 10,000` base units/day (unchanged if no downtime) - If a daily release is missed and the next evaluated epoch date is one day later: `500,000 remaining / 49 days = 10,204` base units/day (adjusted) - When the evaluated epoch start date reaches the end date, the hook releases the entire remainder (rule 2). Epochs advance at most once per block, so recovery follows the epoch schedule ## State ### Minter The minter stores current release state. Dates use the `yyyy-mm-dd` format: ``` type Minter struct { StartDate string // The day where the mint begins EndDate string // The day where the mint ends Denom string // Must equal the bond denom (uhpx) TotalMintAmount uint64 // Total amount to be minted RemainingMintAmount uint64 // Remaining amount to be minted LastMintAmount uint64 // Last amount minted (usually from the day before) LastMintDate string // Last day minted LastMintHeight uint64 // The height of the last mint } ``` The denom is not a free choice: validation requires both the minter denom and `Params.MintDenom` to equal the default bond denom, `uhpx`. Query the current minter and parameters: ``` paxd q mint minter paxd q mint params ``` ### Params Parameters define the release schedules the minter is derived from: ``` type Params struct { MintDenom string // Type of coin to mint (must be uhpx) TokenReleaseSchedule []ScheduledTokenRelease // List of token release schedules } type ScheduledTokenRelease struct { StartDate string // The day where the mint begins EndDate string // The day where the mint ends TokenReleaseAmount uint64 // Total amount to be minted } ``` Multiple release schedules can be defined, allowing sequential minting periods. ## Epoch Hook The mint module has no begin-block minting logic of its own. Its `BeforeEpochStart` hook is a no-op; all minting happens in `AfterEpochEnd` as described above. Because epochs default to 60s, the hook runs frequently, but the same-date check limits actual mints to one per UTC date. See the [Epoch module](https://docs.paxeer.app/modules/epoch) for how boundaries are detected. ## Governance ### Update Minter Proposal The minter can be replaced via governance to change the mint schedule. The proposal is stored *verbatim* after validation (`HandleUpdateMinterProposal` calls `ValidateContent` then `SetMinter`), so every field must be set explicitly. In particular: - `remaining_mint_amount` is not derived from `total_mint_amount`. Setting it to `0` ends that release; another eligible schedule can then supply a new minter - `last_mint_date` must be a parseable `yyyy-mm-dd` date; an empty string fails validation. A fresh minter uses `0001-01-01` - `denom` must be `uhpx`, and `last_mint_amount` must not exceed `total_mint_amount - remaining_mint_amount` ``` { "title": "Update Minter", "description": "Adjust mint schedule", "minter": { "start_date": "2023-10-05", "end_date": "2023-11-22", "denom": "uhpx", "total_mint_amount": "100000", "remaining_mint_amount": "100000", "last_mint_amount": "0", "last_mint_date": "0001-01-01", "last_mint_height": "0" } } ``` Save the example JSON as minter_prop.json and submit it with your network deposit and fee: ``` paxd tx gov submit-proposal update-minter ./minter_prop.json \ --deposit --from -b block -y \ --gas 200000 --fees ``` The amounts above are base units of the configured denom. Choose a deposit, fee, and signing key for your network. After the proposal executes, `paxd q mint minter` returns the stored minter; subsequent epoch processing can update it. ### Update Params Proposal Parameters can be updated to define new token release schedules. Save the example below as param_change_prop.json and set its deposit to the amount required by your network: ``` { "title": "Param Change Proposal", "description": "Update token release schedule", "deposit": "20000000uhpx", "changes": [ { "subspace": "mint", "key": "MintDenom", "value": "uhpx" }, { "subspace": "mint", "key": "TokenReleaseSchedule", "value": [ { "token_release_amount": 500, "start_date": "2023-10-01", "end_date": "2023-10-30" }, { "token_release_amount": 1000, "start_date": "2023-11-01", "end_date": "2023-11-30" } ] } ] } ``` Submit: ``` paxd tx gov submit-proposal param-change ./param_change_prop.json \ --from -b block -y --gas 200000 --fees ``` **Note:** Changes to `total_mint_amount` or `remaining_mint_amount` after the start date do not affect tokens already minted. ## Events ### Mint Event Emitted on each successful mint: - **mint_date:** Date of the mint - **mint_epoch:** Epoch number when the mint occurred - **amount:** Amount minted ## Metrics Each successful mint records two gauges: the OpenTelemetry gauge `mint_coins_minted{denom}` and the legacy telemetry gauge `pax/mint/coins` (exported as `pax_mint_coins{denom}`). ## Next Steps - [Understand epoch coordination](https://docs.paxeer.app/modules/epoch) - [Learn about the oracle module](https://docs.paxeer.app/modules/oracle) --- URL: https://docs.paxeer.app/modules/oracle # Oracle Module Navigate the retired EVM Oracle API and the native interfaces for exchange rates, voting parameters, and price observations. **Source:** `precompiles/oracle/oracle.go`, `modules/oracle/`, `node/wasmbinding/queries.go`, and `node/app.go`. ## EVM price queries are retired The Oracle precompile remains registered at `0x0000000000000000000000000000000000001008`, but both `getExchangeRates` and `getOracleTwaps` revert with: ``` oracle precompile is retired; oracle data queries are disabled ``` For EVM applications, choose an active price-data integration for your network and configure its asset identifiers, units, and freshness checks. ## Native Oracle interfaces The native Oracle module handles validator voting, aggregation, and queries. It also provides the keeper used by CosmWasm Oracle query plugins. | Component | Function | | --- | --- | | `modules/oracle/handler.go` | Feed-consent delegation and aggregate exchange-rate vote messages. | | `modules/oracle/abci.go` | `MidBlocker`: vote-period aggregation and exchange-rate updates. EndBlocker: slash-window penalties and removal of excess feeds. | | `modules/oracle/keeper/` | Stored rates, vote targets, validator voting state, parameters, and query services. | | `modules/oracle/client/cli/query.go` | Native exchange-rate, actives, snapshot-history, TWAP, parameter, feeder, and vote-penalty queries. | | `node/wasmbinding/queries.go` | `HandleOracleQuery`: native `exchange_rates` and `oracle_twaps` custom-query handlers. | Query current vote targets and observations to identify the denominations available on your network. Check observation timestamps before using a rate in application logic. ## Aggregation and parameters Aggregation runs in the module's mid-blocker (`MidBlock` in `modules/oracle/module.go`), during transaction processing between begin- and end-block. At the last block of each vote period it builds voting claims from bonded validators, organizes ballots by configured vote targets, applies threshold checks, and derives exchange rates through weighted-median processing (`WeightedMedianWithAssertion` for the reference denom, `Tally` with the reward band for cross rates). At the last block of each slash window, the end-blocker runs `SlashAndResetCounters` over the miss/abstain counters and removes excess feeds. Vote-period, reward-band, and slash-window behavior is controlled by module parameters. Read the live parameters and vote targets before interpreting a network's observations or validator obligations. Do not infer a fixed voting period, reward band, slash rate, or required asset list from an example or another network's settings. ## Native query commands These eight commands are registered by the native module. Point the CLI at the Cosmos RPC endpoint for the node you are inspecting: ``` paxd query oracle params paxd query oracle vote-targets paxd query oracle actives paxd query oracle exchange-rates paxd query oracle exchange-rates paxd query oracle price-snapshot-history paxd query oracle twaps paxd query oracle feeder paxd query oracle vote-penalty-counter ``` The optional denomination belongs to `exchange-rates`; there is no separate singular `exchange-rate` command in this CLI. Validator operator addresses use the `paxvaloper` prefix. ## CosmWasm query boundary The `oracle` custom-query route still calls the native module handler. A CosmWasm custom querier payload for retained exchange rates has this shape: ``` { "route": "oracle", "query_data": { "exchange_rates": {} } } ``` Issue this query from a CosmWasm contract through [WASM bindings](https://docs.paxeer.app/wasmbinding). Check the returned denominations and observation freshness before using the results. ## Related interfaces - [Current precompile addresses and ABI behavior](https://docs.paxeer.app/precompiles) - [Native REST and gRPC interfaces](https://docs.paxeer.app/rest-grpc) - [Custom CosmWasm queries and messages](https://docs.paxeer.app/wasmbinding) --- URL: https://docs.paxeer.app/modules # Paxeer X Modules Native execution, markets, issuance, and data modules in `modules/`, including retired settlement-compatibility directories. **Source:** `modules/README.md` ## Unified Paxeer X modules Paxeer X combines EVM and Cosmos execution with the LayerX kernel. The chain modules below enforce the chain-side rules; the [LayerX kernel](https://docs.paxeer.app/layerx-kernel) inside `paxd` executes and orders each transaction and builds each block; validators check and commit it, and a receipt is final when its block is committed. Addresses below are shortened; see [precompiles](https://docs.paxeer.app/precompiles) for full addresses and upgrade gates. | Module | Role in Paxeer X | EVM entry point | | --- | --- | --- | | `lxphost` | Shared cgo host for kernel validation and execution; also backs the `layerxprograms` precompile | `0x101D` | | `layerxledger` | Asset registration, derived accounts, transfers, and exact payments. The old payer-grant issue, revoke, and draw operations are retired | `0x101A` | | `layerxauth` | Capability and session grants, revocation, and SDK authorization integration | `0x101C` | | `layerxpay` | Escrows, budgets, streams, and service agreements, subject to configured family enablement and pause gates | `0x101B` | | `layerxagent` | Scheduled EVM calls, job deposits, and bounded end-block execution. Agent-function precompiles occupy `0x0901`–`0x0908`; the scheduler is at `0x0905` | `0x0901`–`0x0908` | | `layerxchains` | Tenant-domain registry, funding, allowances, operator controls, and lifecycle. Sub-chains are database namespaces on the same network | `0x101E` | | `sequencer` | On-chain leader list, receipt keys, and sequence state used by block proposal and receipt machinery | — | | `layerxgov` | Governance proposal content (`LayerXProposal`) that dispatches packaged parameter and admin messages through the SDK `MsgServiceRouter` | Governance proposals | | `perps` | Native perpetuals markets and synchronous trading: orders, positions, and margin | `0x1015` | | `spot` | Native spot markets, orders, stop orders, quoters, and vaults | — | | `pricefeed` | Validator-signed index and mark price observations with mid-block aggregation | — | | `layerxbridge` | Attested transfers between Paxeer and external chains: chain registry, attestor set, per-asset caps, and `bridgeIn`/`bridgeOut` | `0x1016` | | `launchpad` | Native bonding-curve markets over `tokenfactory` denoms | `0x1017` | | `xweb` | Attested web data for EVM contracts and kernel programs; governance controls the attestor set, threshold, and pause state | `0x1019` | Explore the [unified network](https://docs.paxeer.app/unified-network), [asset model](https://docs.paxeer.app/assets), [settlement lifecycle](https://docs.paxeer.app/settlement), and [bridge](https://docs.paxeer.app/bridge). `modules/README.md` describes module ownership. ## Retired settlement compatibility These directories retain legacy types, historical state handling, and retirement checks. They do not provide a separate execution or settlement domain: | Module | Status | EVM entry point | | --- | --- | --- | | `layerxcustody` | Legacy custody registry and retirement handling. Deposits, proof-carrying withdrawals, forced exits, and deposit-root publication are retired. Fund derived sub-accounts through native bank sends; use `layerxbridge` for outward transfers | `0x1013` | | `layerxanchor` | Retired checkpoint and bond machinery. Use committed blocks for finality and committed application state with per-key proofs for state verification | `0x1014` | | `layerxexchange` | Retired exchange-intent submission and proof-based settlement machinery. Use the native `perps` module at `0x1015` for orders, positions, and margin | `0x1015` (superseded by `perps`) | ## Module Overview Paxeer X-specific chain modules live under `modules/`. These extend the Cosmos SDK with functionality unique to Paxeer X’s EVM L1 design. The pages in this section document `epoch`, `mint`, `oracle`, `store`, and `tokenfactory` in detail; the modules above are documented in their own sections or in `modules/README.md`. ## Module List | Module | Purpose | | --- | --- | | [`evm`](https://docs.paxeer.app/evm) | Native EVM execution, address association, receipts, pointers, and precompile integration | | [`epoch`](https://docs.paxeer.app/modules/epoch) | Time-based hooks and epoch lifecycle management | | [`mint`](https://docs.paxeer.app/modules/mint) | Scheduled native-token minting, released daily through the epoch hook | | [`oracle`](https://docs.paxeer.app/modules/oracle) | Validator exchange-rate voting and weighted-median price aggregation (native interfaces; the EVM precompile is retired) | | [`store`](https://docs.paxeer.app/modules/store) | Single cached-context helper; not a registered chain module | | [`tokenfactory`](https://docs.paxeer.app/modules/tokenfactory) | Creation and admin management of native token denominations by any sender | ## Framework Modules Framework-provided modules (bank, staking, distribution, governance, etc.) remain under `sdk/x/`. Interchain application modules live under `interchain/modules/`. ## EVM Module The `evm` module is Paxeer X’s core EVM execution layer: - **EVM execution:** Runs Ethereum transactions through the configured EVM and upgrade rules - **Address association:** Maps Cosmos addresses to EVM addresses - **Receipts:** Generates EVM transaction receipts - **Pointers:** Bridging between Cosmos and EVM state - **Precompiles:** Integration with Paxeer X-specific precompiled contracts See [EVM documentation](https://docs.paxeer.app/evm) for details. ## Epoch Module The `epoch` module provides time-based lifecycle hooks: - **Epoch boundaries:** Fixed time periods (60s by default) checked in `BeginBlock` - **Hooks:** Registered modules run `AfterEpochEnd` / `BeforeEpochStart` callbacks at each boundary. Only the mint keeper is wired in `node/app.go` See [Epoch documentation](https://docs.paxeer.app/modules/epoch) for details. ## Mint Module The `mint` module manages native token issuance: - **Release schedule:** A `total_mint_amount` released between a start and end date - **Minting trigger:** Only the epoch `AfterEpochEnd` hook, which mints at most once per day (UTC date) - **Destination:** Newly minted coins are sent to the `fee_collector` account See [Mint documentation](https://docs.paxeer.app/modules/mint) for details. ## Oracle Module The `oracle` module enables validator-based price feeds on native interfaces: - **Exchange rate voting:** Validators submit price observations for configured vote targets - **Aggregation:** Weighted-median computation in the mid-blocker at the last block of each vote period - **Penalties:** The end-blocker processes miss/abstain counters at each slash window; counters reflect participation and in-range votes - **EVM access:** The oracle precompile at `0x…1008` is retired and reverts; use native or CosmWasm queries See [Oracle documentation](https://docs.paxeer.app/modules/oracle) for details. ## Store Module `modules/store/` is a single helper file, not a registered module: - **`GetCachedContext`:** Returns a context backed by a `CacheMultiStore` plus the cache itself. It has no keeper, types, queries, or messages See [Store documentation](https://docs.paxeer.app/modules/store) for details. ## Token Factory Module The `tokenfactory` module enables native token creation: - **Native denominations:** Create new token types as `factory/{creator}/{subdenom}` - **Creation:** `MsgCreateDenom` has no permission gate; any sender can create a denom and becomes its admin - **Management:** The admin can mint (to itself), burn (from itself), change admin, update the allow list, set metadata, and pause/unpause the denom See [Token Factory documentation](https://docs.paxeer.app/modules/tokenfactory) for details. ## Module Integration Modules are registered in the application through `node/app.go`: - **Module manager:** Coordinates module initialization and upgrades - **Begin/end block:** Modules register hooks for block lifecycle - **Message routing:** Module-specific transactions routed to handlers - **Query routing:** Module-specific queries routed to keepers --- URL: https://docs.paxeer.app/modules/store # Store Module A single cached-context helper in `modules/store/` — not a registered chain module. **Source:** `modules/store/handler.go` ## Overview `modules/store/` provides `handler.go`, which exports the cached-context helper. Keepers and module lifecycle registration live in `node/app.go`. `modules/README.md` describes this package as "module-level store integration helpers". ## GetCachedContext ``` package store import ( sdk "github.com/Sidiora-Labs/Paxeer-X-Network/sdk/types" ) func GetCachedContext(ctx sdk.Context) (sdk.Context, sdk.CacheMultiStore) { ms := ctx.MultiStore() msCache := ms.CacheMultiStore() return ctx.WithMultiStore(msCache), msCache } ``` `GetCachedContext` wraps the context's multistore in a `CacheMultiStore` and returns both the derived context and the cache. Writes made through the derived context stay in the cache until the caller writes the cache through; discarding the cache discards the writes. This is the standard SDK pattern for speculative execution. ## Using the cached context - Modules define their own prefixes and use the SDK `KVStore` and codec through the returned context. - Retain the returned cache when the caller needs to commit the buffered writes. - The SDK multistore supplies the cache used for speculative execution over [PaxDB storage](https://docs.paxeer.app/storage). ## Next Steps - [Understand PaxDB storage architecture](https://docs.paxeer.app/storage) - [Review other Paxeer modules](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/modules/tokenfactory # Token Factory Module Creation and admin management of native token denominations with creator-namespaced denoms. **Source:** `modules/tokenfactory/` ## Overview The tokenfactory module allows any account to create new native tokens: `MsgCreateDenom` has no permission gate, allow list of creators, or governance check. Tokens are namespaced by creator address as `factory/{creator address}/{subdenom}`, eliminating name collisions. A single account can create multiple denoms by providing unique subdenoms. The creator becomes the denom's admin. The admin can mint, burn, change admin, update the denom allow list, set bank metadata, and pause or unpause the denom — subject to the sender restrictions below. ## Token Naming Tokenfactory denoms follow the format: ``` factory/{creator_address}/{subdenom} ``` Example: ``` factory/{creator_address}/ufoo ``` - **Prefix:** Always `factory` (7 bytes) - **Creator address:** Bech32 address (max 75 bytes) - **Subdenom:** User-defined (max 44 bytes) The full denom must also pass the SDK denom validation, `[a-zA-Z][a-zA-Z0-9/-]{2,127}` (`sdk/types/coin.go`). That means a subdenom containing `.` is rejected, while `-` and `/` are allowed characters in the full denom. Total denom length must not exceed 128 bytes. ## Messages ### CreateDenom Create a new denom. Field 3 carries an optional bank allow list for the new denom: ``` message MsgCreateDenom { string sender = 1; string subdenom = 2; AllowList allow_list = 3; // bank AllowList type } ``` CLI: ``` paxd tx tokenfactory create-denom ufoo --from mylocalwallet ``` State modifications: - Set `DenomMetadata` via bank keeper - Set `AuthorityMetadata` with sender as admin - Add denom to `CreatorPrefixStore` Replace angle-bracketed arguments with your denom or file path. Creation fails if the subdenom already has bank supply or the resulting denom already has bank metadata. ### Mint Mint tokens (admin only). The minted coins go to the sender — there is no recipient field: ``` message MsgMint { string sender = 1; cosmos.base.v1beta1.Coin amount = 2; } ``` CLI: ``` paxd tx tokenfactory mint 100000000000 --from mylocalwallet ``` Checks: the denom was created via tokenfactory, the sender is the admin, and the denom is not paused. The amount is minted via the bank module to the sender's account; distributing it further is a separate bank send. ### Burn Burn tokens (admin only). The coins are burned from the sender's own balance — the admin cannot burn from another account: ``` message MsgBurn { string sender = 1; cosmos.base.v1beta1.Coin amount = 2; } ``` Checks: the denom was created via tokenfactory, the sender is the admin, the denom is not paused, and the sender holds the amount. The amount is sent from the sender to the module account and burned via the bank module. ### ChangeAdmin Transfer admin privileges: ``` message MsgChangeAdmin { string sender = 1; string denom = 2; string newAdmin = 3; } ``` The sender must be the current admin, and `newAdmin` must differ from the current admin. `ValidateBasic` accepts either a valid bech32 address or `""` to renounce admin authority. Renouncing leaves no admin able to perform these operations. ### UpdateDenom Replace the denom's bank allow list: ``` message MsgUpdateDenom { string sender = 1; string denom = 2; AllowList allow_list = 3; // bank AllowList type } ``` ``` paxd tx tokenfactory update-denom --allow-list --from mylocalwallet ``` The allow-list file is a JSON object with an addresses array; an empty array clears the list. The stored allow list must be defined, contain only valid bech32 addresses, and not exceed the `denom_allowlist_max_size` parameter (default `2000`). ### SetDenomMetadata Set the denom's bank metadata from a file: ``` paxd tx tokenfactory set-denom-metadata --from mylocalwallet ``` ### SetDenomPaused Pause or unpause a denom: ``` paxd tx tokenfactory set-denom-paused true --from mylocalwallet ``` While a denom is paused, tokenfactory mint and burn reject with `ErrDenomPaused`. This CLI message applies to denoms without an issuer DID; issuer-bound denoms use the issuer authorization path. ## Admin Capabilities The admin can: - **Mint:** Create new tokens of the denom, credited to the admin itself - **Burn:** Destroy tokens from the admin's own balance - **Change Admin:** Transfer admin rights to another address - **Update allow list / metadata / pause:** Via `MsgUpdateDenom`, `MsgSetDenomMetadata`, and `MsgSetDenomPaused` There is no force-transfer message in this module: the admin cannot move or burn tokens held by other accounts. Ordinary transfers use the bank module and require the holder's signature. Admins can share privileges via the authz module without changing the master admin. ## Queries ``` paxd query tokenfactory params paxd query tokenfactory denom-authority-metadata paxd query tokenfactory denom-paused paxd query tokenfactory denoms-from-creator paxd query tokenfactory denom-metadata paxd query tokenfactory denom-allow-list paxd query bank denom-metadata --denom ``` ## Parameters - **`denom_allowlist_max_size`:** Maximum addresses in a denom allow list. Default `2000`; changeable by governance ## Restrictions To fit within the 128-byte Cosmos SDK denom limit: - **Max subdenom length:** 44 bytes - **Max creator address length:** 75 bytes (bech32 prefix ≤ 16 chars) Calculation: ``` len("factory") + 2*len("/") + len(creator_address) + len(subdenom) ≤ 128 7 + 2 + 75 + 44 = 128 ``` ## Use Cases - **Wrapped assets:** Mint tokens representing off-chain assets - **Synthetic tokens:** Create tokens backed by other on-chain assets - **Protocol-managed denoms:** Modules create denoms for internal accounting - **Governance tokens:** DAOs issue native governance tokens ## Integration with Bank Module Tokenfactory denoms are native tokens, not ERC-20 contracts. They integrate with the bank module for: - Balance queries - Transfers via `MsgSend` - IBC transfers - Distribution to stakers ## Next Steps - [Review current precompile addresses and behavior](https://docs.paxeer.app/precompiles) - [Review other Paxeer modules](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/network-operations # Network operations Operate paxd nodes with the LayerX kernel that executes and orders transactions and builds blocks for validators to check and commit. The LayerX kernel runs inside every `paxd` node, executes each transaction when it arrives, gives it the next position in one global sequence, returns a signed execution receipt and builds each block; validators check that block and commit it. Paxeer mainnet-beta uses EVM chain ID 125. A receipt is final when its block is committed. Hosted identity, Human, gateway, registry, signing, and event-delivery services support applications around that network. The control routes below belong to `services/platform/hosted/testnet/`, the control service for an isolated hosted environment. ## Service architecture | Service boundary | Responsibility | Operational evidence | | --- | --- | --- | | Gateway | Application JSON-RPC admission, authentication, and upstream calls. | Readiness, JSON-RPC responses, and verified receipt lookup. | | Identity and Human | Identity sessions, human journeys, approvals, and account-facing workflows. | Identity readiness and durable journey or approval state. | | Node and core | The node commits execution; hosted core coordinates payment and funding operations. | Committed blocks, receipts, and core operation journals. | | Receipt authority | Verify signed receipt material for hosted consumers. | Configured receipt keys, transaction binding, and receipt digest. | | Registry and builder | Program artifacts, registration, and release material. | Artifact commitments, registry records, and compatible release versions. | | Chain consensus | Commit blocks through the validator set. | Block headers, commits, validator sets, and application state. | | Internal signing and event sources | Non-exporting signing APIs and verified journey, payment, approval, and program events. | Durable journals, principal binding, and event sequences. | | Control | Dependency status, package and wire gates, and journey admission. | Readiness document and explicit failing dependencies. | Public node JSON-RPC serves the node namespaces at the root path. The hosted gateway additionally serves its declared `px_` methods. Human and administrative APIs have their own authorization boundaries. The testnet control service exposes protected funding and reset operations for its configured environment; application payments use the chain ledger. ## Startup and release lifecycle 1. Select the node release, genesis, chain identity, and node profile for the intended network. 2. Provision service trust material and persistent stores before starting their consumers. 3. Start the chain node with its configured kernel and verify synchronization. 4. Confirm the connected EVM chain identifier and enabled application interfaces. 5. Start configured hosted services after their dependencies are reachable. 6. Check package and wire versions, dependency readiness, and application journey admission. 7. Complete an application operation and inspect its transaction and receipt evidence before admitting traffic. Use the same genesis and chain identity for nodes joining the same network, with a separate data directory and peer identity for each node. Hosted clients must use the matching EVM chain identifier and configured trust roots. Tenant domains share the network infrastructure and namespace their state in the database. ### Package and protocol compatibility The control release gate compares package semantic version and wire protocol version independently. A compatible package name does not override a wire-version mismatch. Global readiness includes the release gate; a journey can have healthy dependencies while the overall release remains degraded. ## Health and journey admission | Control route | Meaning | | --- | --- | | `GET /livez` | The control process answers requests. | | `GET /readyz` | All declared dependencies, all journeys, and the release gate are ready; otherwise HTTP 503 includes the degraded document. | | `GET /v1/status` | Summary state for control, gateway, core, and Paxeer components. | | `GET /v1/parameters` | Testnet-specific parameters (network `layerx-testnet`, package and wire versions, monthly reset schedule). | | `GET /v1/journeys/{journey}` | Admission for a named journey, including failing dependencies. | These routes describe the control service inside the operator's configured environment. Configure the control origin explicitly; the paths are not a promise of a public control hostname. The control service declares three journey routes: `funding`, `payment`, and `receipt-inspection`. The last route reports the journey name `receipt_inspection` in JSON. | Journey | Required dependencies | | --- | --- | | `funding` | Identity, faucet, Redis, core admin, core. | | `payment` | Identity, gateway, core, receipt authority. | | `receipt-inspection` | Gateway, receipt authority, core. | An admitted journey returns HTTP 200 with `admitted: true`, `ready: true`, and an empty `failing` array. A degraded journey returns HTTP 503 with named failures. The global probe also includes Paxeer; a Paxeer dependency failure can degrade global readiness while an execution journey remains admitted. ### Probe depth Identity, faucet, core, receipt authority, gateway, and Paxeer probes require HTTP 200 from their configured `/readyz` routes. The core-admin probe completes a TLS handshake. Redis is probed over TLS with PING; either PONG or an authentication-required response establishes reachability. These checks do not execute an application payment. Inspect a real transaction and its verified receipt for application evidence. ## Durability and recovery Core operation journals, Human state, registry records, internal event journals, signing material, and chain data have distinct owners. Preserve the complete material set needed by each service. Restore an existing store with its matching signing and sealing material. ### Signing boundary Internal signing uses authenticated APIs: callers create key handles and request signatures without receiving private material. Stored private material is sealed with AES-256-GCM using a key derived from the configured secret and domain label, with a fresh nonce for each sealed value. The signing API does not export seeds. KMS readiness requires the exclusive store lock and a successful durable-write probe. Access to signing routes requires a verified client certificate and bearer identity. ### Verified event sources Journey, payment, approval, and program event sources bind provisioned principals to upstream credentials. Payment facts come from verified receipt data. The event store advances a separate sequence for each principal and subject and validates the sequence while replaying its journal. Internal journals append and synchronize records before reporting success, hold an exclusive lock, and replay in append order. A failed append marks the journal unavailable. Event-source readiness requires upstream readiness, principal binding, and a writable journal; this prevents an apparently healthy process from silently losing new events. ## Maintenance and draining 1. Record the active release, network identity, latest committed block and verified receipt, and outstanding operation identifiers. 2. Remove the affected service from new ingress admission through the deployment's traffic controls. 3. Reconcile accepted operations from their durable receipts and journals, preserving idempotency keys for retries. 4. Preserve outstanding event delivery state, signing material, and persistent volumes before replacing a process. 5. Restore the service with matching identity and release material, then inspect replay and readiness results. 6. Readmit traffic after the relevant journey and its evidence checks pass. Draining is a deployment and reconciliation workflow. The control API exposes readiness and journey admission; it does not define a universal drain endpoint. A pending operation remains pending until its canonical receipt or durable outcome resolves it. ## Disposable environment tooling The chain Makefile provides a disposable Docker cluster and a separate monitoring variant. Run these commands from the monorepo root. Startup stops the corresponding cluster and replaces generated cluster configuration; use a directory dedicated to development. ``` DOCKER_DETACH=true make -f chain.mk docker-cluster-start # Or start the cluster with Prometheus and Grafana: DOCKER_DETACH=true make -f chain.mk docker-cluster-start-monitoring # Stop the matching cluster: make -f chain.mk docker-cluster-stop make -f chain.mk docker-cluster-stop-monitoring ``` The cluster targets in `chain.mk` use the Compose definitions under `docker/`. The monitoring variant adds the monitoring Compose file. Keep generated development configuration separate from a mainnet node home and retain the stores and signing state needed for any planned recovery. ## Failure triage 1. Read the global readiness document, then the specific journey's failing dependency list. 2. Check the named dependency at its own boundary and distinguish connection health from verified application results. 3. For release failures, compare package and wire versions before changing traffic admission. 4. For journal or seal failures, preserve the store and restore matching material before restarting consumers. 5. For payment failures, compare the intended chain, signed transaction, receipt digest, and committed-block evidence required by the application. Continue with [Node operators](https://docs.paxeer.app/operators), [Related protocol reference](https://docs.paxeer.app/guarantors), [Security and trust boundaries](https://docs.paxeer.app/security), and [Governance](https://docs.paxeer.app/governance). --- URL: https://docs.paxeer.app/network-parameters # Network Parameters Chain identity, denominations, source defaults, and governance controls for Paxeer mainnet-beta. ## Unified execution and application parameters Paxeer mainnet-beta uses EVM chain ID 125. The kernel runs inside `paxd`, and a receipt is final when its block is committed. The address precompile’s `getUnifiedAccount` returns an EVM address, associated Cosmos address, bound DID public key, and kernel main account identifier. An absent association returns an empty Cosmos address; an absent DID binding returns zero key and account fields. See the [network model](https://docs.paxeer.app/unified-network). | Parameter family | Controlled behavior | | --- | --- | | Bridge | Chain registry, attestor threshold, per-asset caps, and pause state | | Launchpad | Quote token, virtual reserves, creation fee, fee bounds, decay, volatility and concentration weights, and protocol fee share | | Fee tokens | Approved fee denominations, rate age, spread limit, enablement, and distribution policy | | XWeb | Attestors, signature threshold, request fee, delivery limits, and pause controls | | Tenant domains | `modules/layerxchains` namespaces state within the shared network. Creating a domain does not require new node infrastructure. | Governance writes remain subject to each module’s active handlers and authority checks. Bridge registration, launchpad configuration, fee-token policy, and XWeb settings have distinct validation rules. Consensus commits establish finality for the integrated network. `docs/system/chain-modules.md` in the monorepo lists parameter fields and `docs/system/governance.md` lists proposal types. Query the target network’s active values for financial decisions. See [native interfaces](https://docs.paxeer.app/precompiles), [asset units](https://docs.paxeer.app/assets), and [bridge controls](https://docs.paxeer.app/bridge). ## Chain Identifiers Use these identifiers when configuring a wallet or client. Confirm the connected node's chain ID before signing a transaction. | Parameter | Value | | --- | --- | | EVM chain ID | `125` / `0x7d` | | Consensus chain ID | `hyperpax_125-1` | | Account prefix | `pax1…` | | Validator operator prefix | `paxvaloper1…` | | Binary / default home | `paxd` / `~/.paxeer` | | Node source | `daemon/paxd/` and `node/` at the monorepo root | | Module manifest | `go.mod` at the monorepo root | ``` # Set EVM_RPC_URL to the node JSON-RPC URL and CONSENSUS_NODE to its consensus RPC URL. curl -sS "$EVM_RPC_URL" -H 'Content-Type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' paxd status --node "$CONSENSUS_NODE" ``` Public node JSON-RPC uses the root path. The expected `eth_chainId` result is `0x7d`. Public node namespaces are `debug`, `echo`, `eth`, `net`, `pax`, `test` and `txpool`; availability depends on node configuration. Compare `eth_blockNumber` across configured nodes when selecting one near the head. See [Public RPC](https://docs.paxeer.app/public-rpc). **Source:** `tools/hpx/publish.sh`, `node/params/config.go`, `node/const.go`, `rpc/info.go`. ## Native Denominations The native asset pays EVM gas. Node parameters name its human unit `hpx`. Cosmos CLI and bank APIs use `uhpx` for base-unit amounts. EVM clients use 18-decimal native amounts. ``` 1 hpx = 1,000,000 uhpx 1 uhpx = 1,000,000,000,000 EVM wei 1 hpx = 1,000,000,000,000,000,000 EVM wei ``` Use `uhpx` amounts for Cosmos CLI transactions and 18-decimal native amounts for EVM transactions. Address association joins the supported wallet representations; see [address precompiles](https://docs.paxeer.app/precompiles). **Source:** `node/params/config.go` — `UhpxExponent`; `modules/evm/state/utils.go` — `UhpxToSweiMultiplier`. ## Query Current Parameters Query the connected network for its active governance, staking, slashing, and consensus parameters. Cosmos queries use the consensus RPC endpoint; EVM requests use the EVM JSON-RPC endpoint. The examples use `CONSENSUS_NODE` for the CLI RPC URL and `CONSENSUS_HTTP_URL` for the consensus HTTP origin. ``` paxd query staking params --node "$CONSENSUS_NODE" paxd query slashing params --node "$CONSENSUS_NODE" paxd query gov params --node "$CONSENSUS_NODE" curl -sS "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/consensus_params" ``` | Default parameter | Value | Meaning | | --- | --- | --- | | Unbonding time | 21 days | Default staking unbonding duration | | Unbonding / redelegation entries | 7 | Limit for an individual delegation pair | | Standard governance period | 2 days | Default deposit and voting periods | | Expedited governance period | 1 day | Default expedited voting duration | | Governance minimum deposit | 10,000,000 base units | Query the active governance deposit requirement | | Expedited minimum deposit | 20,000,000 base units | Query the active governance deposit requirement | | Slashing fractions | 0 by default | Configured by chain governance | Governance approval requires a yes-vote ratio strictly greater than the configured threshold after abstentions are excluded. Validator jailing and equivocation handling apply alongside the configured slashing fractions. **Source:** `sdk/x/staking/types/params.go`, `sdk/x/gov/types/params.go`, `sdk/x/gov/keeper/tally.go`, `sdk/x/slashing/types/params.go`. ## Gas and Block Limits Query `eth_gasPrice`, `eth_feeHistory`, and `eth_maxPriorityFeePerGas` for EVM fee information. The node also has local admission prices and simulation limits. Consensus `block.max_bytes` is a block limit; `mempool.max-tx-bytes` is a separate transaction limit. See [JSON-RPC](https://docs.paxeer.app/json-rpc) and [Configuration](https://docs.paxeer.app/configuration) for the distinct EVM, consensus, and node settings. ## Performance and Endpoints Track block interval using block timestamps, throughput using transactions per block, and RPC latency using request metrics. Record the node revision and workload when comparing measurements. Use the RPC endpoint supplied by your node operator. The [HPX distribution and peer registry](https://docs.paxeer.app/admin-hpx) supplies chain metadata and peer information for its configured network. The hosted gateway `px_` API is separate from public node JSON-RPC. Obtain its URL and credentials from the operator. ## Kernel Integration The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. `modules/lxphost/` connects kernel execution to the chain. See [Paxeer and LayerX](https://docs.paxeer.app/paxeer-vs-layerx) for the integrated architecture. --- URL: https://docs.paxeer.app/node-troubleshooting # Troubleshoot a Node Diagnose Paxeer X sync stalls, peer failures, RPC errors, database locks, and AppHash mismatches before changing node state. Collect a small set of evidence before changing configuration: the running binary, configured network, current height, peer count, and recent logs. This lets you distinguish a local service problem from a network-wide halt or an application-state mismatch. ## Diagnose kernel and application dependencies Paxeer mainnet-beta runs kernel execution inside `paxd`. A healthy EVM RPC confirms one access surface. Trace an affected operation through its gateway or Human API, chain submission, execution receipt, and committed block. Keep the operation ID, transaction hash, receipt digest, and block height together. | Symptom | Evidence to inspect | Recovery direction | | --- | --- | --- | | Gateway rejects a request | Public method, authentication, registry route, dependency readiness, and receipt verification error | Correct the failing authorization or upstream dependency | | Node or hosted service fails startup | Node configuration, genesis, chain identity, state-directory ownership, and store lock | Use the matching artifacts and one process per state directory | | One node falls behind | Committed height, peers, storage latency, and the earliest sync error | Restore connectivity or recover from a matching verified snapshot | | Transaction remains pending | Original transaction hash, mempool admission, nonce, fees, and block progress | Resolve the original transaction before submitting another payment | | Committed payment proof fails verification | Transaction binding, receipt digest, block headers, commit signatures, and trusted validator set | Use matching proof material and the configured chain trust anchor | | Human or agent operation stalls | Identity, owner approval, provider readiness, key-management channel, and canonical receipt | Repair the responsible service boundary and resume the recorded operation | | Historical state is unavailable | Requested height, configured retention, and node profile; see [history access](https://docs.paxeer.app/relay-archive) and the `paxd` sync checks below | Use an endpoint retaining the required state | A receipt is final when its block is committed. Verify application evidence against the intended chain and transaction. Distinguish a pending submission from a rejected transaction or a receipt-verification error. Continue with [settlement](https://docs.paxeer.app/settlement) and [operator responsibilities](https://docs.paxeer.app/operators). ## Confirm the process and endpoints The examples use the systemd service named `paxd` installed by HPX. Set `CONSENSUS_HTTP_URL` to the consensus HTTP origin and `EVM_RPC_URL` to the EVM JSON-RPC URL for your node. Substitute your service name when using another deployment. ``` paxd version --long systemctl status paxd --no-pager systemctl show paxd -p ExecStart -p User ss -lntp curl --fail --silent --show-error "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/status" | jq '.result | {node_info, sync_info}' curl --fail --silent --show-error "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/net_info" | jq '.result.n_peers' curl --fail-with-body --silent --show-error "${EVM_RPC_URL:?Set the EVM JSON-RPC URL}" -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' ``` For the Paxeer X network documented here, compare the Cosmos network with `hyperpax_125-1` and the EVM result with `0x7d`. A local development cluster can use a different identifier. The binary found in your shell can differ from the absolute path in the service’s `ExecStart`. ## Match the symptom to the next check | Symptom | Inspect | Next action | | --- | --- | --- | | Connection refused | Service status and listening sockets | Confirm process startup and the bound address before investigating peers | | Zero peers | Network ID, configured peer IDs, DNS, and P2P connectivity | Use peers supplied for that exact network and release | | Peers present, height stalled | Earliest error before the stall, upgrade height, disk and memory pressure | Compare the same height with a known-good node | | Cosmos status works, EVM RPC fails | EVM enablement, port, and RPC namespace configuration | Check [application configuration](https://docs.paxeer.app/configuration) | | Historical query fails | Pruning and state retention at the requested height | Use an archive-capable endpoint with that state | ## Capture a sync stall Capture the height and latest block time twice, a short interval apart. Compare both samples with a known-good node on the same network. A changing height with increasing lag points toward throughput; an unchanged height with a repeating error points toward a specific blocker. ``` curl --fail --silent --show-error "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/status" | jq '.result.sync_info | {latest_block_height, latest_block_time, catching_up}' journalctl -u paxd --since '15 minutes ago' --no-pager -o short-iso df -h df -i free -h ``` Check storage capacity and inode exhaustion separately. For slow disks, use the host’s I/O monitoring to compare read latency, write latency, and saturation with the stalled period. Avoid changing several performance settings at once; preserve one baseline to compare against. ## Investigate AppHash mismatches An AppHash mismatch means the node’s computed application state disagrees with the block header. Record the exact height, expected and actual hashes, binary revision, genesis identity, and snapshot provenance. Use the binary assigned to that network’s upgrade schedule at the failing height. ``` journalctl -u paxd --since '1 hour ago' --no-pager | rg -n -i 'apphash|app hash|panic|corrupt|upgrade|handshake' # Set PAXEER_NODE_HOME to the data directory used by the service. sha256sum "${PAXEER_NODE_HOME:?Set the active node home}/config/genesis.json" ``` Handshake errors can follow a state mismatch; start with the earliest application error rather than repeatedly rotating peers. Reconcile the release, upgrade schedule, and snapshot with a known-good operator before choosing recovery steps. ## Handle database locks and recovery A database lock often means another process still holds the same data directory. Inspect the service and process list, including containers, before attempting another start. Keep one writer per data directory; stop the process holding the database before recovery. Rollback, snapshot restore, and reset commands change durable state and depend on the storage engine and release. Preserve a backup and use the recovery procedure for that exact node version. For validator recovery, preserve the existing signing state and confirm that only one signer is active. For a duplicate-signing alert, stop the affected signer and establish which instance owns signing before restarting. Retain the validator keys and signing history throughout recovery. ## Prepare an actionable report - Node role, network identifiers, binary version and checksum, and startup command. - Stalled or failing height and a comparison with a healthy node. - At least the logs leading into the first failure, including the complete panic stack when present. - Disk, memory, peer count, recent upgrade or restore activity, and snapshot checksum. - The relevant configuration changes, with RPC credentials and signing material removed. Use [Operators Guide](https://docs.paxeer.app/operators) for ongoing monitoring, [Configuration](https://docs.paxeer.app/configuration) for settings, and [Run a Node](https://docs.paxeer.app/run-node) for initial setup. **Paxeer source:** monorepo root — `daemon/paxd/cmd/root.go` (command registration), `node/app.go` (DefaultNodeHome), and `consensus/internal/rpc/core/status.go` (Status). --- URL: https://docs.paxeer.app/operators # Operators Guide Manage paxd nodes, whose LayerX kernel executes and orders transactions and builds blocks, and the validators that check and commit them. For stalled heights, peer failures, or state mismatches, start with [Troubleshoot a Node](https://docs.paxeer.app/node-troubleshooting). Record the binary revision and failing height before changing state. ## Operate the node and application services The LayerX kernel inside `paxd` executes and orders each transaction and builds each block; validators check and commit it. Paxeer mainnet-beta uses EVM chain ID 125. A receipt is final when its block is committed. Hosted gateways and user services support applications around the chain. Assign each deployed service its own health checks, storage policy, and recovery procedure. | Role | Responsibility | Operational evidence | | --- | --- | --- | | Chain node and validator | Execute EVM and Cosmos transactions; enforce active exchange, bridge, launchpad, ledger, and XWeb rules | Chain identity, synchronization, peers, application hash, upgrade version, and RPC health | | Embedded kernel | Execute ordered activities as part of chain block processing | Committed blocks, execution results, state roots, and receipts | | Receipt authority | Provide verified receipt material to hosted clients | Authorized receipt keys, transaction binding, and receipt digests | | Consensus validator set | Vote on blocks and establish BFT commits | Validator membership, voting power, commit signatures, and block identity | | Gateway and registry | Verify public receipts, route requests, and publish discovery records | Dependency readiness, receipt verification, registry identity, and routing health | | Agent and Human services | Serve identity, delegated execution, owner approval, security, movement, and key-management boundaries | Authorization outcomes, signed activity and receipt continuity, provider readiness | | Historical queries | Serve retained node state; see [history access](https://docs.paxeer.app/relay-archive) | Earliest available height and archive retention settings | Applications access node JSON-RPC or the hosted gateway methods appropriate to their integration. Core administration, signing APIs, and provider internals have separate authentication boundaries. Consensus and kernel execution remain within the node. See [kernel execution](https://docs.paxeer.app/layerx-kernel), [settlement](https://docs.paxeer.app/settlement), [public APIs](https://docs.paxeer.app/platform-api), and [configuration](https://docs.paxeer.app/configuration). ## Choose the Node Profile Full nodes serve queries and retain recent history. Archive nodes preserve available historical state. Validators use a signing profile with public application APIs disabled, and seed nodes serve peer discovery. Hardware sizing depends on traffic, retained history, and the selected stores. Use [Configuration](https://docs.paxeer.app/configuration) to choose a node profile and its enabled services. Validator participation also depends on on-chain registration and the active set. ## HPX Node Management HPX manages a native `paxd` systemd service and verifies installation artifacts against the selected distribution mirror’s checksum manifest. The mirror distributes installation material. From the monorepo root, inspect and run the checked-out bootstrap script: ``` less tools/hpx/get-hpx.sh sudo bash tools/hpx/get-hpx.sh # If setup was skipped during bootstrap: sudo env HPX_TYPE=fullnode hpx setup ``` The bootstrap script offers the setup wizard after installation. Select `HPX_TYPE=validator` instead of `fullnode` for validator setup. Run the HPX management commands below from a root shell. The selected artifact set includes the binary, architecture-specific Wasm runtimes, genesis, and configuration. Use the selected mirror's manifest to confirm the release and artifact checksums. ``` hpx # interactive menu hpx status hpx info hpx logs hpx start hpx stop hpx restart hpx peers show hpx statesync hpx validator keygen hpx validator stake hpx validator status hpx help ``` `hpx start|stop|restart` control the systemd service. `hpx validator keygen` generates this node's operator account, `hpx validator stake` submits create-validator from the funded operator account, and `hpx validator status` reports validator state. `hpx peers refresh` changes the peer configuration (a peers-refresh systemd timer is also installed); `hpx register` announces the node to the registry. Use `hpx update` as a planned version change after checking network compatibility. **Source:** `tools/hpx/get-hpx.sh`, `tools/hpx/hpx`, `tools/hpx/README.md`. ## Local Development Cluster From the monorepo root: ``` DOCKER_DETACH=true make -f chain.mk docker-cluster-start # Or start the cluster with monitoring: DOCKER_DETACH=true make -f chain.mk docker-cluster-start-monitoring ``` The targets in `chain.mk` stop the corresponding local cluster and replace generated configuration before startup. See [Docker](https://docs.paxeer.app/docker) for compose services and generated paths. ## Validator Accounts and Keys The operator account submits staking and governance transactions. The consensus key signs blocks. Use an existing operator account, or create one with the following commands: ``` paxd keys add operator paxd keys show operator -a paxd keys show operator --bech val -a paxd tendermint show-validator ``` A `pax1…` account address, `paxvaloper1…` validator address, and consensus public key are distinct arguments. Use the form required by each command. ### Register a Validator After the node is synchronized and the operator is funded, register it with `create-validator`. This example uses one PAX in base units. Choose your stake, moniker, and commission settings, taking the network's active validator set into account. ``` paxd tx staking create-validator \ --amount=1000000uhpx \ --pubkey="$(paxd tendermint show-validator)" \ --moniker="My Validator" \ --chain-id=hyperpax_125-1 \ --commission-rate="0.10" \ --commission-max-rate="0.20" \ --commission-max-change-rate="0.01" \ --min-self-delegation="1" \ --gas=auto \ --gas-adjustment=1.5 \ --gas-prices=0.02uhpx \ --from=operator ``` `--min-self-delegation` is expressed in base units. Set gas prices for the connected network. Choose either `--gas-prices` with a gas limit or an explicit `--fees` amount. ### Inspect Validator State ``` paxd query staking validator "$(paxd keys show operator --bech val -a)" paxd query staking delegations-to "$(paxd keys show operator --bech val -a)" paxd query slashing signing-info "$(paxd tendermint show-validator)" paxd query staking params paxd query slashing params ``` The staking module also exposes `edit-validator`, `delegate`, `redelegate`, and `unbond`. `paxd tx slashing unjail` is subject to the keeper's eligibility checks; it cannot reverse permanent tombstoning. **Source:** `sdk/x/staking/client/cli/tx.go`, `sdk/x/staking/client/cli/query.go`, `sdk/x/slashing/client/cli/query.go`, `sdk/client/tx/factory.go`. ## Monitoring ``` curl -sS "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/status" | jq '.result.sync_info' curl -sS "${CONSENSUS_HTTP_URL:?Set the consensus HTTP origin}/net_info" | jq '.result.n_peers' journalctl -u paxd -f ``` Enable the configured Prometheus listener as shown in [Configuration](https://docs.paxeer.app/configuration). Consensus metrics include block height, last-signed height, missed-block gauges, and syncing state. Build alerts from the emitted metric names and choose thresholds for your workload. Treat missed-block values as gauges. ## Peer and Signer Configuration Use `bootstrap-peers`, `persistent-peers`, and `private-peer-ids` under `[p2p]`. The peer ID can be read with `paxd tendermint show-node-id`. Keep signer access separate from public query services. Remote signers connect through the configured `[priv-validator]` socket or gRPC interface. For a hardware-backed signer, use an integration compatible with that interface and verify signing before activating the validator. ## Backup and Recovery | Data | Purpose | | --- | --- | | `config/priv_validator_key.json` | Consensus identity and signing key | | `data/priv_validator_state.json` | Last signed height, round, step, and signature | | `config/node_key.json` | Peer identity | | Selected keyring backend | Operator account keys | | Genesis, TOML configuration, and configured stores | Matching chain and state data | The node defaults to `~/.paxeer`. HPX defaults to `/root/.paxeer` and reads `HPX_HOME` to override that home. Stop the node before replacing its stores. Preserve the key and last-sign state together and ensure the original signer is offline before activating a replacement. Never start a second active signer with the same validator key. For snapshot recovery, verify the archive revision, checksum, backend, and layout before extraction. Reserve `unsafe-reset-all` for a planned state reset with complete backups. Use retention settings for routine pruning and `paxd rollback` for supported stopped-node state reconciliation. **Source:** `consensus/config/config.go`, `consensus/privval/file.go`, `sdk/server/rollback.go`, `sdk/x/evidence/keeper/infraction.go`. ## Planned Upgrades Match the network's upgrade plan and the release revision before replacing a binary. Record the installed version, preserve the previous binary and required state, stop the service, install the compatible release, and confirm synchronization after restart. Check the release's upgrade and snapshot compatibility requirements before installation. Governance upgrade proposals use the registered `software-upgrade` command. Expedited proposal support uses `--is-expedited`; query current deposit and voting parameters before submitting. --- URL: https://docs.paxeer.app/oracle-risk # Oracles & Market Risk Understand how Paxeer X accepts signed price observations, rejects stale or anomalous inputs, and applies market-specific risk limits. ## Prices enter the ledger as signed observations Paxeer X carries external market data into deterministic execution through signed `ORACLE_PUSH` activities. Execution consumes accepted observations; it does not make an external network request to obtain a price. This gives replay the same ordered market input that original execution used. An observation identifies a market, observation sequence, unsigned integer price, observation timestamp, and source identifier. The signed transport appends a signature to the observation (see the format below); the signer key itself is checked against the market's permitted set rather than carried in the transport. A market defines the permitted keys, freshness window, minimum and maximum prices, and maximum deviation from its preceding accepted observation. ## Price acceptance pipeline | Check | Acceptance rule | Refusal | | --- | --- | --- | | Canonical encoding | The payload has the exact expected length and re-encodes to identical bytes. | `LXP_ERR_NON_CANONICAL` | | Authorized signer | The public key belongs to the market permission set and verifies the domain-separated observation signature. | `LXP_ERR_UNAUTHORIZED_ORACLE` | | Freshness | Observation time is no later than sealed batch time, and age does not exceed maximum staleness. | `LXP_ERR_TIMESTAMP_REGRESSION` or `LXP_ERR_ORACLE_STALE` | | Price range | The integer price lies between configured minimum and maximum, inclusive. | `LXP_ERR_ORACLE_BOUNDS` | | Observation ordering | The incoming sequence is strictly greater than the preceding accepted sequence for this market. | `LXP_ERR_ORACLE_SEQUENCE` | | Deviation | Absolute change does not exceed the prior accepted price multiplied by the deviation limit in basis points. | `LXP_ERR_ORACLE_DEVIATION` | The deviation allowance is rounded down in integer price units. The first accepted observation has no preceding observation for a relative-deviation comparison, but it must still satisfy authorization, freshness, encoding, and configured bounds. ### Concrete acceptance example Suppose the last accepted price is 100,000 integer units and the permitted deviation is 200 basis points. The next observation may differ by at most 2,000 units. A price of 101,500 satisfies that deviation check; 103,000 does not. If maximum staleness is 5,000 milliseconds, an observation aged exactly 5,000 milliseconds satisfies the freshness boundary, while 5,001 milliseconds fails it. These are example parameters, not network-wide defaults. ## Canonical observation format The unsigned canonical observation is 72 bytes (`LX_ORACLE_OBSERVATION_BYTES`). The signed transport is 137 bytes (`LX_ORACLE_TRANSPORT_BYTES`): a 1-byte version (`LX_ORACLE_TRANSPORT_VERSION` = 1), the 72-byte observation, and a 64-byte signature, decoded by `lx_perps_oracle_transport_decode`. The transport carries no public key; activity authority supplies the signer identity, which must belong to the market's permitted set. Integer fields use big-endian encoding; price uses unsigned 128-bit units and timestamps use milliseconds. Verification binds the observation to the `LXP:ORACLE:OBSERVATION:v1` tag under the signature-preimage domain. These formats are defined in `include/layerx/lx_oracle.h` and `src/modules/perps/lx_perps_command.c`. ``` market_id: 32 bytes observation_sequence: 8 bytes price: 16 bytes observed_at: 8 bytes source_identifier: 8 bytes ``` Keep the market price scale with every decoded price. A source identifier describes the submitted observation; it does not replace signer authorization or make an unsigned price acceptable. ## Risk limits are market-specific Initial margin, maintenance margin, liquidation fees, funding caps, permitted oracle keys, and price acceptance bounds are explicit market parameters. A parameter version identifies the configuration revision. Market creation validates nonzero units and intervals, distinct system accounts, sorted unique permitted keys, and coherent margin and price bounds. Market halt state is an additional control. Risk-taking operations and funding execution enforce halt checks. Treat the halt flag as an operation-specific refusal boundary: an integration should inspect the receipt of each action rather than assume that all account or recovery operations have identical halt behavior. ### What accepted data proves An accepted observation proves that its canonical payload passed the configured signature and market checks at its place in execution. It does not prove the external source was economically correct, guarantee future prices, or remove liquidity and insurance constraints. Application risk policies can impose stricter freshness or exposure limits than the protocol minimums. ## Integration workflow 1. Load the market identifier, price scale, parameter version, permitted signer set, and risk thresholds. 2. Read the latest accepted observation with its sequence, timestamp, source identifier, and price. 3. Display observation age and market status beside price-sensitive actions. 4. Submit actions using canonical payloads and inspect execution receipts for price, margin, authorization, and halt refusals. 5. On a stale, out-of-range, or deviation refusal, obtain a new accepted observation or reassess the request. Repeatedly submitting the same invalid observation cannot make it valid. Registered oracle activities persist the latest accepted observation in the committed perps key-value state. The observation retains its sequence, timestamp, source identifier, and signer. Oracle ingestion does not transfer balances; authorized value movements use explicit ledger transfer sets. Keep observation acceptance and financial settlement separate in application accounting. ## Related documentation - [Perpetual positions, funding, and liquidation](https://docs.paxeer.app/perpetuals) - [Native Oracle module interfaces](https://docs.paxeer.app/modules/oracle) - [Module architecture](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/overview PAXEER X / NETWORK DOCUMENTATION # Applications. Payments. Programs. Build on Paxeer. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block. [Explore the network](https://docs.paxeer.app/unified-network)[Start with the XDK](https://docs.paxeer.app/xdk) LayerX kernelEVM chain ID `125`Native token `PAX` The LayerX kernel executes, orders and receipts every transaction; EVM applications run on the same sequence.EVM 125 · PAX On arrival, the kernel gives each transaction a position in one global sequence and returns a signed execution receipt. Validators check and commit each block it builds. NETWORK INTERFACES [**XDK**Developer toolkit](https://docs.paxeer.app/xdk) [**7 SDKs**Language quickstarts](https://docs.paxeer.app/sdk-quickstarts) [**MCP**Scoped daemon tools](https://docs.paxeer.app/mcp) [**JSON-RPC**EVM chain 125](https://docs.paxeer.app/json-rpc) [**CLI**Command line](https://docs.paxeer.app/cli) [**Execution you can reproduce**The node orders native activities and commits their state with BFT blocks. Deterministic execution supports replay with the required state and artifacts.](https://docs.paxeer.app/layerx-kernel) [**Authority with clear boundaries**Identity keys, scoped capabilities, delegated spending limits and revocation constrain authorized actions.](https://docs.paxeer.app/identity) [**Tools you already know**Deploy Solidity, connect wallets and call native precompiles through standard EVM tooling and JSON-RPC on chain 125.](https://docs.paxeer.app/evm) APPLICATION NEEDS - Reconcile payment outcomes - Identify an authorized actor - Link payment and delivery - Reproduce program execution - Check settlement evidence - Connect agent tools PAXEER X - Native transfer settlement (402LXP) - EVM address bound to a LayerX DID - Escrow, acceptance and receipts linked - Deterministic, replayable transitions - Signed receipts and committed blocks - Scoped MCP tools and agent budgets [Start with the XDK](https://docs.paxeer.app/xdk) AGENTS ### Configure agent authority. Create identities, delegate scoped authority, fund accounts and connect tools through SDKs, MCP and the agent daemon. This path covers: - Agent identities and DIDs - Budgets, mandates and revocation - Scoped MCP tools - Agent-to-agent tasks [Build an agent](https://docs.paxeer.app/agents) PAYMENTS START HERE ### Integrate native payments. Integrate transfers, escrow, budgets and payment streams. Connect service delivery to acceptance, receipts and disputes. This path covers: - Transfers, holds and escrow - Paid APIs and x402 / 402LXP - Payment streams and budgets - Receipts and settlement proof [Make your first payment](https://docs.paxeer.app/payments-quickstart) EVM APPLICATIONS ### Use the tools you know. Deploy Solidity, connect wallets and call native precompiles for account binding, native payments, exchange and asset launches. This path covers: - Solidity with Foundry and Hardhat - JSON-RPC on chain 125 - Native precompiles - Assets, launchpad and markets [Build on the EVM](https://docs.paxeer.app/evm) BUILD WITH THE FULL SYSTEM ## Find your interface. Follow it deeper. Architecture, integration guides and operational reference for Paxeer X. [### LayerX kernel Canonical sequencing, accounting, modules and deterministic execution.](https://docs.paxeer.app/layerx-kernel) [### Platform APIs Application gateways, hosted services, webhooks and integration surfaces.](https://docs.paxeer.app/platform-api) [### EVM JSON-RPC Wallet integration, chain requests, contracts and transaction inspection.](https://docs.paxeer.app/json-rpc) [### Operator guides Nodes, configuration, network services and settlement infrastructure.](https://docs.paxeer.app/operators) What is the difference between Paxeer X and LayerX? Paxeer X is the network and LayerX its kernel. LayerX executes each transaction on arrival, orders it, signs the receipt and builds the block that validators commit. EVM transactions run on the same sequence and call native precompiles. Receipt finality comes from the commit of the covering block. [Explore the network architecture](https://docs.paxeer.app/paxeer-vs-layerx) Which chain ID and token does the network use? EVM chain ID `125` (`hyperpax_125-1`) with native token `PAX`. Denominations, gas limits and endpoints are listed with the network parameters. [Network parameters](https://docs.paxeer.app/network-parameters) How does an agent get authority to spend? Through scoped, revocable delegation: primary and session keys, budget limits and mandates define exactly what an agent may do with money, and owners can revoke or rotate that authority. [Agent budgets](https://docs.paxeer.app/agent-budgets) How do I verify a payment actually settled? Verify the signed execution receipt against trusted receipt keys, check its transaction and outcome, and confirm the covering block is committed. [Receipts and proofs](https://docs.paxeer.app/receipts) Can I use my existing EVM tooling? Yes. Deploy Solidity with Foundry or Hardhat, connect wallets over JSON-RPC, and call native precompiles for account binding, native payments and markets on chain 125. [Build on the EVM](https://docs.paxeer.app/evm) How do I run a node or operate the network? Start with installation and configuration, then the operator guides for paxd nodes, validators, RPC endpoints and retained chain history. [Run a node](https://docs.paxeer.app/run-node) ## Build an application. Connect to Paxeer. Choose a domain, integrate an interface and follow the evidence through the network. [Open the developer toolkit](https://docs.paxeer.app/xdk)[Explore the network](https://docs.paxeer.app/unified-network) --- URL: https://docs.paxeer.app/paid-apis # Paid APIs and x402 Use x402 version 2 offers, EVM payments, and verified receipts to release paid HTTP resources on Paxeer mainnet-beta. A paid endpoint advertises its price through x402 version 2. The buyer selects an accepted offer, authorizes payment on the named EVM network, and retries with payment evidence. The seller releases the resource after verifying the receipt and required commitment. Exact, metered, and subscription schemes use this evidence-bound lifecycle. ## The HTTP payment exchange 1. The buyer requests the resource without payment. 2. The seller returns HTTP `402` with a `PAYMENT-REQUIRED` header and matching JSON body. 3. The buyer selects a supported scheme and network, verifies payee terms, and constructs a payment payload. 4. The buyer retries with `PAYMENT-SIGNATURE`, preserving the accepted offer and required extensions. 5. The seller verifies settlement and records fulfillment before returning the resource with `PAYMENT-RESPONSE`. 6. The buyer independently verifies the response receipt and settlement reference. HTTP headers carry standard-base64 JSON. MCP and A2A bindings carry the corresponding JSON values. Settlement identity stays consistent across transports, so redelivering the same payment through another binding retains the same economic identity. ## Define the offer | Field | Contract | | --- | --- | | `x402Version` | `2`. | | `resource` | HTTP(S) URL, with optional description, MIME type, service name, tags, and icon URL. | | `accepts` | One to 32 offers; buyer selection follows seller order among supported scheme/network pairs. | | `scheme`, `network` | `exact`, `metered`, or `subscription`, with an `eip155:` network identifier. Paxeer mainnet-beta uses `eip155:125`. | | `amount` | Positive canonical decimal string, represented exactly as an unsigned 128-bit integer. | | `asset`, `payTo` | 32-byte hexadecimal Asset and recipient identifiers. | | `maxTimeoutSeconds` | Positive integer request timeout, at most `2^32 - 1` seconds. | | `extra.layerx` | Commitment, account reference, currency, and scheme-specific grant terms. | The network is an `eip155:` chain identifier with a positive chain number that fits unsigned 32-bit range. For the typed money-movement buyer flow, `extra.layerx.account` names the destination account, such as `agent::main`, and `currency` names its money currency. The buyer checks that `payTo` corresponds to the offered account or its asset account before preparing payment. ## Add seller middleware The Node package `@sidiora/layerx-seller-middleware` lives at `services/platform/middleware/seller/`. It exports `SellerMiddleware`, `ReceiptPayloadAuthority`, and payment-header codecs. Configure trusted receipt keys, a payment authority, payment requirements, and a durable fulfillment repository. This handler follows `services/platform/examples/paid-api/index.mjs`; `middleware` is the configured seller instance. ``` import { PAYMENT_SIGNATURE_HEADER } from "@sidiora/layerx-seller-middleware"; const header = request.headers[PAYMENT_SIGNATURE_HEADER.toLowerCase()]; const paymentHeader = Array.isArray(header) ? undefined : header; const decision = await middleware.handle( "public-paid-api", paymentHeader, async () => resourceBody, ); const headers = decision.kind === "payment-required" || decision.kind === "refused" || decision.kind === "released" ? decision.headers : { "retry-after": "1" }; response.writeHead(decision.status, { "content-type": "application/json", ...headers, }); response.end(JSON.stringify( decision.kind === "payment-required" ? decision.body : decision.kind === "released" ? decision.resource : { state: decision.kind }, )); ``` The example serves `GET /paid`. Its configuration selects network, scheme, resource URL, port, and the environment-variable names for price, asset, recipient, account, currency, and receipt keys. Its offer requests `receipted` assurance. Set the resource URL to the endpoint the customer requests. ### Persist fulfillment A fulfillment record binds payment identity to the request digest, transaction hash, canonical receipt evidence, optional committed-block evidence, and returned resource. Matching retries return the stored resource; conflicting reuse is refused. The example durably records a claim before resource release, then synchronizes and publishes the result. An unresolved claim remains an unknown outcome until reconciled, so an uncertain release is not repeated. ## Integrate the buyer `BuyerMiddleware` in `services/platform/middleware/buyer/` accepts a production client, source account, supported scheme/network pairs, trusted receipt keys, an optional commitment resolver, and retry policy. `prepare(paymentRequiredHeader, callerIdempotencyKey)` prepares an exact payment through the typed quote workflow. `fetch` drives the HTTP exchange, while `captureSettlement` verifies the result. Use `fetchGrant` and `captureGrantSettlement` for grant-backed draw transactions. The buyer validates offered account and currency terms before quoting. Required extensions are echoed unchanged. Choose a stable caller idempotency key for one purchase and retain it with the accepted offer and activity identifier until the outcome is resolved. ## Metered requests and subscriptions A metered or subscription offer requires nonzero 32-byte hexadecimal `payer` and `purposeHash` terms. Subscription offers require a positive decimal-string `windowSeconds` below `2^64`; metered offers omit that field. Grant-backed payments use a signed EIP-1559 transaction calling the ledger precompile’s `draw` method. Its 228-byte calldata encodes the grant ID, recipient, unsigned 128-bit amount, idempotency key, unsigned 64-bit sequence, purpose hash, and context hash. Each metered request or subscription payment carries its own authorized draw. The seller requires the grant to be active and bound to the signed executor, payer, recipient, and asset. ``` { "rawTransaction": "", "idempotencyKey": "<64-hex key>" } ``` The grant payment authority checks the transaction’s chain ID, ledger destination, zero native value, calldata, amount, recipient, purpose, idempotency key, and executor. Receipt verification requires the matching `PaymentDrawn` event, including grant ID, payer, asset, amount, and context. A request with changed payment facts is refused. ## Select settlement assurance | Commitment | Required evidence | | --- | --- | | `receipted` | An authorized signed successful receipt bound to the raw EVM transaction and matching payment event. | | `committed` | Receipted evidence plus verified transaction and result inclusion, block headers, validator sets, and BFT commits. | | Trust configuration | Receipt keys are configured locally; committed verification also resolves the trusted chain identity and validator-set hash. | Set `extra.layerx.commitment` to `receipted` or `committed`. Committed verification requires a commitment resolver and a trusted validator resolver. A receipt is final when its block is committed; a signed receipt alone does not supply that proof. Missing evidence cannot lower the requested assurance. ### Receipt verification and capture The seller verifies canonical receipt encoding, the raw transaction and its chain ID, sender and destination binding, successful result, authorized receipt signature, receipt digest, and the accepted payment facts in ledger log effects. Successful settlement returns the verified EVM transaction hash in `transaction`. The buyer checks `success`, network, amount, payer, transaction hash, and the `layerx` extension. Portable evidence uses `format: "layerx-receipt-proof-v2"` and `verificationLevel: "receipted"` or `"committed"`, with raw transaction, signed receipt, receipt digest, and receipt-key metadata. The buyer verifies these against its prepared payment and configured trust. HTTP 200 alone does not establish payment. ## Recover uncertain payment outcomes Preserve the original raw transaction, its EVM hash, the accepted offer, and purchase idempotency key when a payment outcome is uncertain. The node’s `pax_sequencerReceipt` method supplies receipt data for the transaction; the hosted gateway also accepts that method. Verify recovered material before using it as payment evidence. Recover the original payment through the SDK or buyer-middleware settlement capture. Committed assurance requires recovered evidence to verify against the chain’s block headers, BFT commits, inclusion proofs, and trusted validator set. The seller’s durable fulfillment record resolves matching retries to the same resource. A replacement debit does not resolve the original purchase. | Seller outcome | HTTP | Application action | | --- | --- | --- | | Payment required | 402 | Select and authorize an offered payment. | | Pending | 202 | Honor retry guidance and recover the same activity. | | Refused or conflicting reuse | 402 or 409 | Inspect the refusal reason and preserve the original payment identity. | | Released | 200 | Verify PAYMENT-RESPONSE and consume the stored resource. | ## Facilitators and transport interoperability The interoperability service in `services/interop/` supplies x402 facilitator operations for supported offers, verification, and settlement. Verification validates the signed payment without submitting it; settlement uses the chain relay and verified receipt evidence. HTTP, MCP, and A2A bindings share payment semantics. Reuse the same settlement identity for recovery and reject a conflicting receipt for that identity. Use [service agreements](https://docs.paxeer.app/services) for work that needs deadlines, delivered artifacts, review, and disputes. Continue with the [SDK](https://docs.paxeer.app/sdk) and [native protocol modules](https://docs.paxeer.app/modules) for account, Asset, and activity integration. --- URL: https://docs.paxeer.app/parallelization # Design for Parallel Execution Reduce shared-state contention in Paxeer contracts, preserve on-chain invariants, and measure gas separately from throughput. Paxeer supports optimistic concurrency control (OCC): independent work proceeds concurrently, while conflicting access is detected and resolved in a deterministic order. In `node/app.go`, tenant-domain transactions use synchronous V2 processing. Other transactions use Giga OCC when `giga_executor.enabled` and `giga_executor.occ_enabled` are both `true` and synchronous processing is not selected. Both flags default to `true`. With Giga enabled, the remaining path is synchronous Giga execution. With Giga disabled, the context OCC setting and synchronous-processing decision select V2 OCC (`ProcessTXsWithOCCV2`) or synchronous V2 execution. Contract storage layout influences how much work is independent in any of these paths. See the [execution engine](https://docs.paxeer.app/engine) and [SDK integration](https://docs.paxeer.app/sdk). ## Find the shared writes Start by listing the state each entry point reads and writes, including state touched by external calls. Two different users can still conflict if both transactions update one total, one queue head, or the same pool. | Pattern | Contention source | Design option | | --- | --- | --- | | Global counter on every update | All writers touch the same slot | Use per-user state when the aggregate is only needed for display | | One order book for all markets | Unrelated markets share mutable state | Partition by market where business rules allow | | Large push distribution | One transaction writes many recipient balances | Use bounded batches or independent claims | | Shared token or pool call | External state reintroduces a common dependency | Include the external call’s storage accesses in your design | ## Partition state by the unit of work The following illustrative Solidity contract partitions quantities by caller and position ID, giving each pair its own storage entry. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract PositionNotes { mapping(address => mapping(uint256 => int256)) public quantities; event QuantityChanged(address indexed owner, uint256 indexed id, int256 quantity); function setQuantity(uint256 id, int256 quantity) external { quantities[msg.sender][id] = quantity; emit QuantityChanged(msg.sender, id, quantity); } } ``` Updates for different caller/ID pairs reach distinct mapping entries. Updates to the same entry still depend on one another. Calls from one sender also share nonce and balance state, so include sender distribution when measuring concurrency. ## Keep invariants authoritative Keep supply caps, collateral requirements, and conservation checks in on-chain state. These shared dependencies preserve the contract’s accounting rules. When an aggregate is used only for a dashboard, events can feed an indexer instead of requiring every transaction to update the same display counter. Preserve an explicit replay range and durable event cursor as described in [Query the EVM](https://docs.paxeer.app/querying-evm). ## Bound work and inspect packing - Bound arrays and loops that touch persistent storage; measure the largest permitted input. - Calculate temporary values in memory and write only the final required state. - Consider pull-based claims when recipients can act independently, while preserving authorization, funding, and reentrancy protections. - Inspect packed fields before combining them: two logical values in one storage slot can introduce a shared write. - Treat an external call as part of the access set, including shared token balances, allowances, and precompile-backed state. ## Measure the actual workload Use two workloads with the same contract and transaction shape: one distributes work across independent keys, and the other concentrates it on the same keys. Keep the binary revision, hardware, sender distribution, and submission rate fixed. 1. Measure single-call gas with Foundry or Hardhat before changing storage layout. 2. Run the workload against a Paxeer development cluster with the intended executor configuration. 3. Record submitted, included, successful, and failed transactions separately. 4. Compare throughput and latency percentiles at the same load, and inspect available conflict/re-execution diagnostics. 5. Check the resulting state and invariants after every run, including retries and contention cases. ``` forge test --gas-report forge snapshot ``` Track gas per call and network throughput separately. Fewer conflicts can improve scheduling while the gas charged per transaction stays the same. Use the development-cluster workload to compare throughput and latency. ## Review before adoption Keep a storage-access sketch beside benchmark results: which keys are independent, which invariants require a shared dependency, and which external calls can serialize work. Compare each change against the same workload and check that the resulting state remains correct. Continue with [transaction diagnostics](https://docs.paxeer.app/debugging-transactions) to inspect execution failures and [storage architecture](https://docs.paxeer.app/storage) for the underlying state engines. **Paxeer source:** `engine/executor/config/config.go` (OCCEnabled), node/app.go (ExecuteTxsConcurrently and ProcessTXsWithOCCGiga), and modules/evm/types/params.go (DefaultPaxSstoreSetGasEIP2200). --- URL: https://docs.paxeer.app/paxeer-vs-layerx # Paxeer X and LayerX The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block. ## One Network, Kernel In-Process Paxeer X uses EVM chain ID `125`. `paxd` supplies the Cosmos SDK chain and native EVM. The LayerX kernel runs inside the node through `modules/lxphost`, executes and orders each transaction and builds each block; validators check and commit it. Each transaction receives the next position in one global sequence and a signed execution receipt. EVM smart contracts, autonomous agent execution, and programmable finance share that sequence, with finality at block commit. `node/sequencer` supplies execution ordering within the node. Applications compose both through native EVM precompiles and protocol receipts. The kernel runs inside `paxd`. Native wallet payments submit signed EVM transactions to the ledger precompile; protocol activity authorization binds the payment terms. Kernel state changes commit with the rest of the node's transaction state. A receipt is final once its block is committed. There is no later checkpoint or settlement step. | Capability | Paxeer surface | LayerX surface | | --- | --- | --- | | Application execution | Solidity contracts, native precompiles, Cosmos modules | Signed activities, economic modules, deterministic WASM programs | | Identity | EVM and Paxeer addresses | Agent DIDs, sessions, scoped grants, recovery and revocation | | Money | Native assets and bank balances | Payments, holds, escrow, budgets, streams and protocol balances | | Markets | `perps` at `0x1015`, `pricefeed` at `0x1020`, spot at `0x1021`–`0x1025`, launchpad at `0x1017`, bridge at `0x1016` | Kernel economic operations; the EVM perpetuals venue is implemented in `modules/perps` | | Evidence | Committed blocks; `pax_sequencerReceipt` | Signed receipts, ordered batches, state witnesses and replay | | Security authority | Validators and governance under BFT consensus | Actor authority, deterministic execution and independently replayed activity | ## Applications on the Shared Network ### Agent Financial Controls An agent operates through its own identity and bounded authority. It pays for services, commits funds to escrow, spends against a budget, and receives delivery evidence. Businesses issue assets and agents trade the resulting instruments. Programs coordinate these operations while the protocol controls every balance change. ### Solidity Applications That Understand Agent Activity A contract consumes a verified service receipt, proves a LayerX account balance, or checks a program result before applying its own rules. The merge precompiles at `0x101A`–`0x101E` and `0x0901`–`0x0908` expose ledger, payment, authorization, program, and tenant-domain surfaces. Select the interface for the upgrade active at the queried height. ### Markets and Assets `perps` is served at `0x1015`. Native applications also include `launchpad` at `0x1017`, `pricefeed` at `0x1020`, and `spot_pecor`, `spot_orders`, `spot_stoporders`, `spot_quoter` and `spot_vault` at `0x1021`–`0x1025`. Registered external chains connect through `layerxBridge` at `0x1016`. Each path retains its own economic and verification rules. ## A Shared Account, Explicit Authority The address precompile binds an EVM address to a `did:layerx` identity with consent from both keys. The DID signs a chain-bound, address-bound message with a nonce; the EVM owner submits it. Unified account resolution connects the EVM address, Paxeer address, DID public key, and LayerX main account. Binding makes identity discoverable across surfaces. Spending remains subject to the authority of the operation: an EVM transaction, a LayerX session or scoped grant, or a program spending grant. Revocation and expiry constrain delegated actions. ## Evidence and Finality 1. Execute payments, trades, deliveries, or program calls as signed activities or EVM transactions. 2. Receive a signed execution receipt. `pax_sequencerReceipt` reports `submitted`, `receipted`, or `committed`. 3. Treat the result as final only at `committed`, when the block covering its sequence batch has committed. `modules/lxphost` stages kernel writes in the transaction store, and the node commits them with the block. Receipt verification uses the authorized receipt key and evidence for the containing committed block. EVM callers use the ABIs in `precompiles/` for ledger, payment, authorization and program operations. The native asset pays EVM transaction gas. Its human-unit identifier in node parameters is `hpx`, with base unit `uhpx`. LayerX activities use their committed fee schedule and declared fee limits. Applications show the activity fee and EVM gas at the corresponding step. ## Choose Your Starting Point - Read [Unified Network Architecture](https://docs.paxeer.app/unified-network) for state, proof and authority boundaries. - Build contracts with [Foundry](https://docs.paxeer.app/foundry) or [Hardhat](https://docs.paxeer.app/hardhat), then explore [native precompiles](https://docs.paxeer.app/precompiles). - Explore [protocol modules](https://docs.paxeer.app/modules) and the [WASM runtime](https://docs.paxeer.app/wasm-runtime) for programmable execution. - Use [Network Parameters](https://docs.paxeer.app/network-parameters) for chain identity and [Building a Frontend](https://docs.paxeer.app/building-a-frontend) for wallet integration. --- URL: https://docs.paxeer.app/payments-quickstart # Your first payment Quote, commit, and verify a Paxeer X payment using the application SDK or a signed ledger transaction. ## Choose your integration Use the application SDK when you want account-level payment journeys and bearer-token authentication. Use the native CLI when you control the wallet identity and its EVM key and need explicit transaction signing, receipt policy, fee limits, and commitment selection. The CLI submits ledger calls as signed EIP-1559 transactions on chain ID 125. ## 1. Install the application packages ``` npm install @sidiora/layerx-sdk@0.1.0 @sidiora/layerx-buyer-middleware@0.1.0 ``` The packages require Node.js 22 or newer. Their sources are `services/agent/sdk/typescript` and `services/platform/middleware/buyer`. In the sample under `services/platform/examples/samples/first-payment-typescript`, configure `LAYERX_API_URL` with your environment's API base URL and `LAYERX_API_TOKEN` with its account bearer token. Use HTTPS outside a loopback emulator. These credentials identify your API account; do not embed them in browser bundles or logs. ## 2. Quote and commit the payment This SDK integration accepts your typed source, destination, and money values. Choose `paymentKey` from a persistent order identifier or request digest and retain it before committing. ``` import { LayerXPaymentHttpTransport } from "@sidiora/layerx-buyer-middleware"; import { ProductionClient, SecretBytes, idempotencyKey } from "@sidiora/layerx-sdk"; export const openLayerX = (apiUrl, apiToken) => new ProductionClient( new LayerXPaymentHttpTransport({ baseUrl: apiUrl, bearerToken: new SecretBytes(new TextEncoder().encode(apiToken)) }) ); export const pay = async (layerx, source, destination, money, paymentKey) => { const quote = await layerx.human("move.quote", { source, destination, money }); return layerx.human( "move.commit", { quote_id: quote.quote_id }, { idempotencyKey: idempotencyKey(paymentKey) } ); }; ``` The quote establishes the payment terms, mechanism, fee ceiling, arrival expectation, and irreversible legs. Present these terms for approval before committing. An expired quote must be refreshed and approved again. Monetary quantities use integer base units rather than floating-point arithmetic. ## 3. Follow the original journey Store the returned journey identifier alongside the purchase key. Read its progress through `journey.get` and resolve evidence references through `evidence.get`. A `layerx-receipt` reference identifies canonical receipt evidence. Finish only when the journey reaches `done` or `done-finalised` with verified evidence. | Observed outcome | Next action | | --- | --- | | `waiting-for-you` | Obtain the requested decision before expiry. | | `still-checking` | Track the existing journey; lock controls that could create a duplicate payment. | | `refused` | Read refusal authority and `money_left`. | | `done` / `done-finalised` | Verify evidence and record the settlement before fulfilment. | ## Native path: prepare a funded identity The CLI uses a selected local identity, its matching owner-only EVM key export, and an independently supplied receipt policy. The policy requires protocol version 2, network 125, a receipt signer identity and key, and a bounded height range. Prepare the matching identity and EVM key with the wallet derivation and import workflow in the CLI guide. Receipt verification also relies on the configured node connection. ``` cargo build --locked --manifest-path tools/platform/cli/Cargo.toml export PATH="$PWD/tools/platform/target/debug:$PATH" layerx wallet list layerx key default payer ``` In the examples below, `RPC_URL` is the node JSON-RPC root URL, and `GATEWAY_RPC_URL` is the hosted gateway root URL supplied by its operator. `GATEWAY_CREDENTIAL` names a locally stored gateway credential. These shell variables are sample inputs. Configure `RECEIPT_POLICY`, `EVM_KEY_FILE`, `FEE_LIMIT`, `ASSET_ID`, and `RECIPIENT_DID` for the selected wallet, fee ceiling and payment. The selected wallet must hold a spendable balance of the chosen Asset, and its EVM sender must hold enough native currency for gas. `EVM_KEY_FILE` must be a private-key export from `wallet derive --export-private-keys` for the same identity. Confirm the source account and recipient account through the hosted gateway before sending. ## Open the recipient account and send Select the recipient wallet to open its account for the chosen Asset, then select the funded payer wallet to transfer. The CLI reads the EVM sender nonce from the node and payment account state from the hosted gateway. The signing flow discloses the transaction and debit authorization, including recipient, amount, Asset, fee ceiling, expiry, network, and idempotency key. ``` # Run with the recipient wallet and its matching EVM_KEY_FILE selected. layerx --rpc "$RPC_URL" --gateway-credential "$GATEWAY_CREDENTIAL" wallet open-account \ --gateway-rpc "$GATEWAY_RPC_URL" --asset "$ASSET_ID" \ --evm-key-file "$EVM_KEY_FILE" --receipt-policy "$RECEIPT_POLICY" \ --fee-limit "$FEE_LIMIT" --wait committed # Select the funded payer and set EVM_KEY_FILE to its matching export. layerx key default payer layerx --rpc "$RPC_URL" --gateway-credential "$GATEWAY_CREDENTIAL" wallet send \ --gateway-rpc "$GATEWAY_RPC_URL" --evm-key-file "$EVM_KEY_FILE" \ --to "$RECIPIENT_DID" --asset "$ASSET_ID" --amount 10 \ --wait committed --receipt-policy "$RECEIPT_POLICY" \ --fee-limit "$FEE_LIMIT" ``` Choose `submitted` for an accepted transaction hash, `receipted` for a verified signed execution receipt, or `committed` for receipt and committed-block evidence. Only `committed` establishes finality. The amount is an integer in the Asset's base units. ## Recover a pending native payment Each new send creates a new payment idempotency key. The CLI journals the signed transaction before submission. Retain its transaction hash and use the journal-backed recovery flow when the response is uncertain. `wallet receipt` takes a transaction hash, with `--wait` and `--receipt-policy` as its options. ``` layerx --rpc "$RPC_URL" --gateway-credential "$GATEWAY_CREDENTIAL" wallet receipt \ "$TX_HASH" --receipt-policy "$RECEIPT_POLICY" --wait committed ``` `--timeout-seconds` (1 to 300, default 60) belongs to `wallet watch` and to write commands such as `wallet send`, not to `wallet receipt`. Use the recovered receipt and block evidence to establish the payment outcome. ## Node and hosted JSON-RPC The hosted gateway publishes `px_*` methods — including `px_register`, `px_getAccount`, `px_getBalances`, `px_listAssets`, and `px_requestFunds` — plus `pax_sequencerReceipt`. The node accepts signed transactions through `eth_sendRawTransaction` and reports receipt progress through `pax_sequencerReceipt`. The hosted gateway supplies account and asset reads at its separately configured origin. Use each endpoint for its declared methods and verify committed evidence before treating a payment as final. ## Handle common failures | Code or condition | Response | | --- | --- | | `idempotency-required` | Supply the persistent purchase key before committing. | | `idempotency-conflict` | Resolve the original request; do not reuse its key for a different body. | | `rate-limit` | Respect the carried retry timing. | | `unknown-outcome` | Recover the original payment by key and evidence. | | `budget-refusal` | Inspect the funded budget and approved spending limits. | | Invalid signature, stale sequence, missing scope, or evidence mismatch | Resolve the specific refusal before preparing any new payment. | ## Next steps - [Payment lifecycle and merchant workflows](https://docs.paxeer.app/payments) - [Create an Asset and manage accounts](https://docs.paxeer.app/assets) - [Funding and money movement](https://docs.paxeer.app/funding) - [Charge for HTTP resources](https://docs.paxeer.app/paid-apis) - [Estimate fees and set limits](https://docs.paxeer.app/fees) - [Public payment API reference](https://docs.paxeer.app/platform-api) --- URL: https://docs.paxeer.app/payments # Payments Build transfers, paid APIs, merchant checkout, metered usage, and subscriptions on Paxeer X with explicit approval, bounded fees, and verifiable settlement. ## One payment lifecycle For native Asset payments on Paxeer X, the LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Applications quote a move, commit the accepted quote under a stable idempotency key, and track a journey whose outcome is backed by evidence. The native wallet prepares a ledger precompile call, discloses its terms, signs an EIP-1559 transaction, submits it to the node and verifies receipt progress. 1. **Quote:** identify payer, recipient, Asset or currency, amount, mechanism, fee ceiling, expected arrival, and irreversible legs. 2. **Approve and commit:** bind approval to those terms. An expired quote returns `quote-expired` rather than silently changing the payment. 3. **Track:** retain the journey or activity identifier and idempotency key through interruptions. 4. **Verify and fulfil:** validate canonical evidence and payment facts before delivering goods or releasing a protected resource. ## Choose a payment experience | Experience | Flow | Settlement rule | | --- | --- | --- | | Wallet or application transfer | Quote and commit a move, or sign a ledger payment transaction | Verify the receipt and selected commitment | | Paid HTTP resource | x402 exact offer and receipt-backed retry | Release only after the offer is paid and verified | | Merchant cart | Catalog quote, persistent order, payment, fulfilment | Bind order and settlement to the same request digest | | Metered usage | Ledger grant and authorized executor draws | Validate purpose, grant limits, expiry, and each draw | | Subscription | Recurring grant with a declared billing window | Signed draw and distinct period key for every renewal | ## Journey states | State | Application behavior | | --- | --- | | `getting-ready` | The payment is accepted and its legs are being prepared. | | `sending` | At least one leg is in flight. | | `waiting-for-you` | Request the required human decision before its deterministic expiry. | | `processing` | The payment is submitted and settling. | | `still-checking` | The outcome is unknown. Keep duplicate-capable controls locked and resolve the original payment. | | `done` | Settlement is backed by a verified receipt or finality proof. | | `done-finalised` | The human API uses this label for receipt-backed completion with committed evidence. Inspect the evidence as well as the journey state; a `done` journey can also carry committed evidence. | | `refused` | Inspect `refused_by` and `money_left` before reporting the result. | | `awaiting-approval` | The native engine exposes its awaiting-approval leg phase while the journey awaits approval. It is not receipt-backed completion. | | `closed` | A closed journey is read-only and cannot resume signing or execution. Inspect its evidence to determine the movement outcome. | ## Merchant checkout `@sidiora/layerx-merchant-middleware` prices catalog lines and creates a `PAYMENT-REQUIRED` offer. A cart contains at most 256 lines, with unique SKUs and positive integer quantities. All lines share one Asset, recipient, scheme, and network. Amount multiplication and summation use integer arithmetic within the 128-bit amount range. The order store opens the order before the seller decision. The quote digest binds its lines, total, Asset, recipient, scheme, network, and timeout. Repeating an unchanged checkout resolves the same order; a catalog price change produces a different digest. Store responses are checked for matching `checkoutKey` and `requestDigest`, with mismatches refused as `order-conflict`. | Checkout result | Action | | --- | --- | | `payment-required` | Return HTTP 402 with the decision headers. | | `pending` | Preserve the order while settlement completes. | | `refused` | Record the refused order and expose its refusal. | | `paid` | The order is `paid-verified` and carries the receipt digest and transaction. | Late settlement uses verified webhooks. The merchant checks signature, freshness, replay protection, order identifier and request digest, then resolves and verifies canonical receipt evidence. It recomputes the receipt digest before marking the order paid. ## Buyer and HTTP payment flow 1. The seller responds with HTTP 402 and `PAYMENT-REQUIRED`. 2. The buyer selects an offered requirement unchanged and checks supported scheme, network, Asset, recipient, amount, and commitment. 3. The buyer pays under the purchase idempotency key and retries with `PAYMENT-SIGNATURE`. 4. The seller verifies the payment before release and supplies `PAYMENT-RESPONSE`. 5. The buyer verifies captured settlement against receipt evidence. `@sidiora/layerx-buyer-middleware` provides `fetch(url, init)` for the complete loop, plus `parseOffer`, `prepare`, and `captureSettlement` for custom workflows. Unsupported requirements fail before payment. The human-plane transport uses HTTPS, protects bearer tokens with `SecretBytes`, and carries `Idempotency-Key` on mutations. ## Metered payments and subscriptions A metered or subscription challenge binds `extra.layerx.payer`, `purposeHash`, and `commitment`; subscriptions also bind `windowSeconds`. A payer authorizes a ledger grant for a specific executor. The executor signs an EIP-1559 `draw` call to `0x101A` for each charge. The seller checks the active grant, executor, source account, recipient, Asset, amount, purpose and network against the offer, then verifies the receipt and payment log. Grant limits and expiry are enforced by the ledger. Keep one persistent idempotency key for each usage charge or subscription period. The middleware binds that key to the signed draw. A pending payment returns HTTP 202 while the original transaction is tracked; release the resource after the required evidence is verified. ## Commitments and evidence | Commitment | Required evidence | | --- | --- | | `submitted` | An accepted transaction hash; execution is not yet established. | | `receipted` | A verified signed protocol receipt bound to the transaction, successful result and expected payment log. | | `committed` | Receipt inclusion in a committed block, its signed consensus commit and a validator set matched to an independently trusted validator hash. | x402 accepts `receipted` or `committed` in `extra.layerx.commitment`; it defaults to `receipted` when the LayerX terms are absent. Only committed block evidence establishes finality. Successful settlement uses the `lxp:` reference. The middleware verifies the signed raw transaction, receipt signature, receipt digest and payment facts, plus consensus evidence when committed settlement is requested. ## Retries, sequences, and unknown outcomes Choose one stable key per purchase or order. Repeating a human-plane mutation under that key returns its original journey; a different body under the same key is `idempotency-conflict`. Native wallet sends consume the EVM sender nonce and bind debit authorization to payment account state. Retain the signed transaction and its hash when a response is lost. Recover its receipt and journaled submission before creating a new payment. On the human plane, retriabilities are `retriable`, `retriable-after`, `structural`, and `final`. The SDK `ProductionClient` reports its own retry classes: `never`, `safe`, `after`, and `unknown-outcome`. Map between the two vocabularies explicitly rather than treating them as one list. Respect carried rate-limit timing. An `unknown-outcome` result or human-plane `still-checking` requires tracking and evidence recovery, with duplicate controls locked. ## Fees and refusal EVM payment transactions pay gas in the native asset. The CLI queries gas prices and estimates the exact ledger call at pending state, then checks the estimate against `--fee-limit` in wei. Keep enough native balance for gas as well as enough Asset balance for the transfer. A transaction hash or pending response does not establish a successful debit. Inspect the execution result, payment event and requested receipt rung. An executed EVM transaction can consume its nonce and gas even when its call reverts. Program fees and occupancy charges have their own accounting rules; see the fee guide. ## Continue building - [Make your first payment](https://docs.paxeer.app/payments-quickstart) - [Assets and token accounts](https://docs.paxeer.app/assets) - [Public payment API](https://docs.paxeer.app/platform-api) - [x402 transport](https://docs.paxeer.app/paid-apis) - [Fee schedules](https://docs.paxeer.app/fees) --- URL: https://docs.paxeer.app/perpetuals # Perpetual Futures Trade long and short exposure through the native order book, USDL cross margin, governed market parameters and committed transaction receipts. Paxeer Xtrades is the trading workspace in `apps/perps`. Its web application lives in `apps/perps/apps/web`, while the shared market, wallet and chain clients live in `apps/perps/packages/paxeer-backend`. The workspace README covers installation, checks, builds, runtime settings and the client order contract. ## A market is a complete risk configuration The perpetuals venue is implemented in `modules/perps` and exposed to EVM callers at `0x1015`. Its ABI is `precompiles/perps/abi/abi.json`; `precompiles/perps/Perps.sol` declares the Solidity interface. Collateral is the configured USDL ERC-20 with 6 decimal places. Prices, USD notionals, P&L and fees use 18-decimal fixed point. Every precompile method is nonpayable. | Parameter group | What it controls | | --- | --- | | Tick size, lot size and order-value bounds | Valid price and base-size increments and permitted order notionals. | | Leverage limits and margin tiers | Initial margin from leverage and maintenance requirements from the market tiers. | | Liquidation fees, slices and cooldown | Fees and bounded closing orders used to resolve an undercollateralized cross account. | | Premium sampling and funding cap | Sampling cadence, interest and premium adjustments, and the hourly rate cap. | | Oracle symbol and price freshness | The pricefeed index source and whether current prices permit risk-taking operations. | | Market enabled state and venue pause | Whether a market is active and which venue operations are permitted. | Read `getMarketConfig`, `getMarginTiers`, `getMarkPriceDetails` and `getFeeTier` before sizing an order. `getMarketConfig` returns the market leverage cap as a plain integer; order leverage arguments use 18-decimal fixed point. Margin is shared across the account's positions. ## Open, increase, and close exposure 1. Use `getActiveMarketIds` and inspect the selected market configuration and price freshness. 2. Hold the configured collateral token, approve the precompile to spend it, and call `deposit` to fund the cross account. 3. Submit `placeOrder` with the complete order tuple, including side, size, leverage, time in force, price constraints and deadline. 4. Inspect fills, order status and `getPositionDetails`. Use `addCollateral` to increase collateral without changing position size. 5. Monitor `getAccount` and funding. Close through `closePosition`, `partialClose` or `closePositionWithParams`, then withdraw eligible collateral. The `isLong` field selects long or short exposure. Cancel an order by `cancelOrder(orderId)` or `cancelByCloid(marketId, cloid)`. A successful order submission can leave a resting order or a partial fill; inspect the order and fill events to determine exposure. ### Leverage and initial margin Leverage is notional exposure divided by posted margin. For example, 10,000 USD of notional against 1,000 USD of collateral represents 10× exposure; against 2,000 USD it represents 5×. These illustrative values do not define a market limit. Initial margin, maintenance tiers and existing cross-account exposure constrain an actual order. ### Profit and loss For a long position, price P&L follows `(mark price − entry price) × sizeBase ÷ 10^18` with 18-decimal prices and base size; the sign reverses for a short. Use `getPositionDetails` for unrealized P&L and funding, and `getAccount` for account equity and withdrawable collateral. Keep USD fixed-point values separate from 6-decimal USDL amounts. ## Funding follows block time The venue samples the order-book premium against the pricefeed index using block time. At each new whole hour, `SettleFunding` in `modules/perps/keeper/funding.go` updates the cumulative funding index for elapsed hours. Positions realize the index difference when they are settled. The hourly rate combines the mean premium with the governed interest and premium clamp, divides the eight-hour rate into hourly units, and applies the governed hourly cap. Funding settlement converts USD values to USDL with payments rounded up and receipts rounded down. The rounding residue stays in the venue. `getCurrentFundingRate`, `getFundingDetails` and `getPositionFunding` expose funding state. The position funding result is negative when the position pays and positive when it receives. Include funding separately from price P&L when displaying equity. ## Maintenance, liquidation, and insurance Liquidation operates on the cross account when equity falls below its maintenance requirement. `checkLiquidatable` and `getAccount` expose the account risk state. `liquidate(positionId)` identifies an account through a position, settles its funding, cancels open orders and closes exposure against the order book. Large positions use governed slices and cooldowns. 1. Read fresh market prices and recompute cross-account equity and maintenance requirements. 2. Cancel open orders and attempt reduce-only market closes within the configured bounds. 3. Settle realized P&L, funding and fees against account collateral. 4. Handle deficits through insurance, backstop exposure and bounded auto-deleveraging. Insurance and auto-deleveraging are handled in `modules/perps/keeper/insurance.go` and `modules/perps/keeper/adl.go`. `getInsuranceBalance` and `getADLRank` expose their state. End-block processing bounds scans, liquidations and closing slices. The caller recorded in a liquidation event receives no keeper payout. ## EVM method reference | Method | Purpose | | --- | --- | | `getMarketConfig / getActiveMarketIds` | Read governed market parameters and active markets. | | `getMarkPriceDetails` | Read mark, index, midpoint and price freshness. | | `placeOrder / cancelOrder` | Submit a typed order or cancel an owned order. | | `openPosition / addSize / closePosition` | Manage exposure through the order-book compatibility methods. | | `getFundingDetails / getPositionFunding` | Read cumulative funding and the position amount owed or received. | | `liquidate / getADLRank` | Liquidate an undercollateralized account or inspect position deleveraging rank. | Use the exact tuple layouts and parameterless custom errors in `precompiles/perps/Perps.sol`. Methods reject attached native value, delegatecall and writes under staticcall. Check the error selector on a reverted call. Verify successful fills and the containing committed block before treating a trade as final. ## Continue building - [Oracle acceptance and market risk controls](https://docs.paxeer.app/oracle-risk) - [Fees and settlement](https://docs.paxeer.app/fees) - [Paxeer X modules](https://docs.paxeer.app/modules) --- URL: https://docs.paxeer.app/platform-api # Platform API Accounts, balances, history, assets, registration, funding and consensus evidence over the hosted gateway, plus the Agent API for policy-governed writes. ## Choose an interface Use the node JSON-RPC root for signed chain transactions and EVM reads. Configure the hosted gateway origin separately with coordinates supplied by its operator. Its `px_` methods provide account, balance, asset, history and consensus reads. EVM chain ID `125` identifies the network. The gateway serves `GET /openrpc.json` for its method contract and authenticated `GET /v1/routes` for product route discovery. Source: `services/platform/hosted/gateway/openrpc.json` and `services/platform/hosted/gateway/src/rpc.rs`. | Surface | Transport | Purpose | | --- | --- | --- | | Gateway RPC | `POST /` | Seventeen `px_` / `pax_sequencerReceipt` methods: accounts, balances, assets, history, registration, funding and consensus reads. | | Node JSON-RPC | `POST /` | `eth_` and `net_` calls at the node root, including `eth_sendRawTransaction` for signed EVM transactions. See [EVM JSON-RPC](https://docs.paxeer.app/json-rpc). | | Agent API | Contract major 2, minor 0 | Scoped identities, disclosures, approvals, budgets and event streams. | The gateway exposes hosted reads and route discovery; the Agent API provides governed preparation and tracking. Use signed native transactions for network execution. The node reports receipt progress through `pax_sequencerReceipt`, and a receipt is final when its containing block is committed. ## Authentication and signing Public account and consensus reads do not require a gateway key. Route discovery requires a gateway API key in the `Authorization` header, using the `LayerX-Key` scheme. Funding requests require an identity bearer session and the matching signer public key. Registration proves possession of its signing key. Authentication and scope requirements follow the individual route; transaction signatures authorize the exact chain action. Use [scoped identities and credentials](https://docs.paxeer.app/identity) and [budget controls](https://docs.paxeer.app/agent-budgets). ## Query gateway state ``` POST / Content-Type: application/json {"jsonrpc":"2.0","id":1,"method":"px_getNetwork","params":[]} ``` Parameters are positional, in the order listed. The hosted dispatcher serves the following seventeen methods. JSON-RPC batches contain between 1 and 32 requests. Unsupported methods return `-32601`; unavailable configured backends return explicit errors. | Method | Parameters | Purpose | | --- | --- | --- | | `px_getNetwork` | none | Configured network identity, node head and consensus availability. | | `px_getAccount` | `account`; or `did`, `asset` | Account resolution and node state; the two-argument form reads a DID account for one Asset. | | `px_resolveAccount` | `account` | Resolve an account reference to its account record. | | `px_getBalances` | `account` | Balances held by one account, read through the bank precompile. | | `px_listAssets` | optional `cursor` | Native asset list. | | `px_register` | `signer_public_key`, `registration_signature`, optional `email_or_verification_token` | Key-bound principal registration or signup verification. | | `px_requestFunds` | `did`, `signer_public_key` | One bounded testnet funding request, authenticated by identity session. | | `pax_sequencerReceipt` | `txHash` | The node's sequencer receipt and commitment rung, relayed unchanged. | | `px_getCommit`, `px_getValidators`, `px_getSequenceBatch` | `height` as a positive decimal string | Signed commit, validator set and sequence batch at one block height. | | `px_getReceiptKeys` | none | Published receipt signing keys for local receipt verification. | | `px_getHistory`, `px_getUnifiedHistory` | `account`, optional `cursor`, `limit`, `kind` | Paged account history from the indexer read API; the unified variant tags the side each record answers for. | | `px_listHolderRecords` | `address`, `kind`, optional `cursor`, `limit` | Paged holder records of one kind for one address. | | `px_getCapabilities` | none | Which product surfaces are currently available on this endpoint. | | `px_getRouteCatalogue` | none | Authenticated product route catalogue and dependency readiness. | Node-side signing methods (`eth_accounts`, `eth_coinbase`, `eth_sendTransaction`, `eth_sign`, `eth_signTransaction`, `eth_signTypedData`, `eth_signTypedData_v4`, `eth_mining`) and `eth_subscribe` / `eth_unsubscribe` are refused at the gateway rather than relayed. A raw transaction addressed to a precompile surface that `px_getCapabilities` reports false is refused with `-32003 surface_unavailable`; check capabilities before submitting. ## Submit through the Agent API Governed writes use the Agent API pipeline (prepare, sign, submit, track, wait). Native wallet writes submit signed EVM transactions to the node root. The steps are: 1. Verify the network with `px_getNetwork` and read the current account state. 2. Prepare canonical activity bytes with an actor, authority, time bounds, fee limit, payload and stable idempotency key. 3. Inspect the decoded disclosure and sign the exact signing preimage. 4. Submit and retain the submission reference, transaction hash and receipt. 5. Verify the receipt signature under independently trusted receipt keys, compare published keys through `px_getReceiptKeys`, and verify the commit and trusted validator set at the landing height before releasing goods, funds or dependent work. ### Idempotency and uncertain outcomes A timeout does not establish rejection. Reconcile the existing submission and reuse its idempotency key rather than creating a second payment. Agent mutations return the same result for the same body and key; a changed body under the same key returns `IdempotencyConflict`. ## Follow activity Poll `px_getHistory` or `px_getUnifiedHistory` with a retained cursor for account activity, follow EVM heads and logs on the [chain WebSocket endpoints](https://docs.paxeer.app/public-rpc), and use [agent subscriptions](https://docs.paxeer.app/subscriptions) for durable, acknowledged tenant-scoped streams. ### Agent event streams Agent subscriptions support create, list, health, acknowledge, pause, resume and delete. Their persisted cursor enables recovery. Scope evaluates tenant, capability, then filters for agents, accounts, activity types, modules, assets, counterparties and result classes. Delivery is at least once: deduplicate by `deduplication_id` and handle Event, Gap and Truncated variants. ## Agent API pipeline The wire envelope contains contract major and minor as big-endian u16, request ID as big-endian u64, operation as UTF-8 and a canonical-map payload. Amounts, sequences, limits and timestamps are decimal strings. Settlement domain is Paxeer. | Operation | Inputs and outcome | | --- | --- | | `prepare` | Actor, authority, account sequence, timestamp bound, idempotency key, fee limit, payload and payload hash produce unsigned canonical bytes, signing preimage, disclosure, preparation reference and expiry. | | `sign`, `submit` | Preparation reference and signature bind the signed activity and tracked submission. | | `track` | Submission reference returns state, evidence, rung and transitions. | | `wait` | Submission reference, requested rung and deadline return the actual rung and whether the deadline elapsed. | | Reads | `read.balance`, `read.account`, `read.module_state`, `read.history`, `read.batch`, `read.checkpoint`, `read.proof_bundle`. | | Availability and projection | `availability.fetch`, `export.offline`, `project`. Projection is an estimate rather than a verified read. | Submission progresses through Prepared, Signed, Queued, Submitted, Unknown, Executed, Committed, Failed and Expired. Unknown is a first-class pending state. On the wire, progress is reported as one of three rungs — `submitted`, `receipted` and `committed` — and `wait` reports the actual rung with `deadline_elapsed` when its deadline expires. A `receipted` result proves execution; `committed` establishes block finality. ## Errors and retries | Code | Meaning | Action | | --- | --- | --- | | `-32600` | Invalid request envelope. | Correct the JSON-RPC framing. | | `-32601` | Method not found in the hosted dispatcher. | Use the hosted method catalogue or send node methods to the node root. | | `-32003` | `surface_unavailable`: a raw transaction targets a precompile surface reported false by `px_getCapabilities`. | Check capabilities; do not resubmit to a disabled surface. | Agent errors distinguish TransportFailure, Deadline, ProtocolIncompatibility, UnavailableCapability, CoreRejection, VerificationFailure, PolicyRefusal, CapabilityRefusal, BudgetRefusal, RateLimit, IdempotencyConflict and InternalFault. Resolve authority and verification failures before retrying. Continue with [CLI workflows](https://docs.paxeer.app/cli), [SDK integration](https://docs.paxeer.app/sdk) and [EVM JSON-RPC](https://docs.paxeer.app/json-rpc). --- URL: https://docs.paxeer.app/precompiles # Precompiles Call native Paxeer X capabilities from the EVM with the correct addresses, ABIs, permissions, and token units. **Source:** `precompiles/setup.go` and each precompile's `abi.json` and Go implementation. ## Kernel and native application precompiles Paxeer X extends the EVM with the LayerX kernel and native financial applications. The tables use shortened addresses; pad each address to 20 bytes for an EVM call. | Address | Interface | Operations | | --- | --- | --- | | `0x1012` | Disabled verification surface | Calls revert with `LXP_MODULE_DISABLED` | | `0x1013` | Disabled custody surface | Calls revert with `LXP_MODULE_DISABLED` | | `0x1014` | Anchor reads | Read-only queries use the available anchor store. Writes revert with `LXP_MODULE_DISABLED`. Network finality is block commit | | `0x1015` | Perpetuals | `addCollateral`, `addSize`, `closePosition`, `executeOrder`, `cancelOrder`, account, balance, and market queries; every method is nonpayable. Use `precompiles/perps/abi/abi.json` and `modules/perps` for the served venue | | `0x1016` | Bridge | `bridgeIn`, `bridgeOut`, `getChain`, `getAttestors`, `getCap`, `isNullified`, `isPaused` | | `0x1017` | Launchpad | Market creation, quotes, buys and sells, reserves and price snapshots, fee strategies, fee claims, burns, airdrops, and LP rewards | | `0x1018` | Fee token | `setFeeDenom`, `getFeeDenom`, `clearFeeDenom` select an approved fee denomination | | `0x1019` | XWeb | `request`, `fulfil`, `fulfilProgram`, `refund`, `getRequest`, `getResult`, `getProgramResult`, `getKernelNetworkId`, attestors, threshold, fee, and parameters | | `0x1020` | Price feed | `getPrice`, `getPriceBySymbol`, `getPrices`, market and observation queries, feed-key registration and revocation | | `0x1021`–`0x1025` | Spot (PECOR) | Market and swap rail (`0x1021`), limit orders (`0x1022`), stop orders (`0x1023`), read-only quoter (`0x1024`), and liquidity vault (`0x1025`); see the [spot exchange guide](https://docs.paxeer.app/spot-exchange) | ### Kernel constructs and agent functions The kernel constructs and agent functions are listed in `MergeAddressTable` in `precompiles/setup.go`. They are served through registered constructors and are gated by the merge activation height. Use the ABI for the address and queried height. | Address | Interface | | --- | --- | | `0x101a` | `layerxledger` | | `0x101b` | `layerxpay` | | `0x101c` | `layerxauth` | | `0x101d` | `layerxprograms` | | `0x101e` | `layerxchains` | | `0x0901`–`0x0908` | Agent functions: `orob`, `clearing`, `oracle aggregator`, `pofq`, `scheduler`, `streams`, `tee attestor`, `eip712` | Use each precompile's ABI for exact tuple layouts, argument types, mutability, and events. Perpetuals and pricefeed ABIs are under `precompiles/perps/abi/` and `precompiles/pricefeed/abi/`; spot ABIs are under `precompiles/spot/abi/`. Solidity interfaces for the bank, address, JSON, WASM and XWeb surfaces are in `contracts/src/precompiles/`. Verify the operation result and its committed block before treating execution as final. ### One account across execution surfaces The address precompile also exposes `bindLayerX`, `unbindLayerX`, `layerXBindNonce`, `getLayerXDid`, `getEvmAddrByLayerX`, and `getUnifiedAccount`. The unified account returns EVM, Cosmos, DID public key, and LayerX main account identifiers. Binding requires the account signature and current nonce; applications retain each identifier in its native encoding. Continue with [XDK](https://docs.paxeer.app/xdk) for client bindings, [settlement](https://docs.paxeer.app/settlement) for receipt verification and block finality, [bridge transfers](https://docs.paxeer.app/bridge), and [assets](https://docs.paxeer.app/assets) for denomination and pointer rules. ## Fixed addresses and interfaces Paxeer X implements precompiles natively in the node. Call them with their matching ABI rather than expecting deployed Solidity bytecode. Match your client bindings to the node revision you use. | Address | Capability | Current interface | | --- | --- | --- | | `0x1001` | Bank | Native balances, metadata, supply, pointer-authorized sends, native value transfers | | `0x1002` | CosmWasm | `instantiate`, `execute`, `execute_batch`, `query` | | `0x1003` | JSON | Extract bytes, byte lists, unsigned integers, and array elements | | `0x1004` | Address association | `getPaxAddr`, `getEvmAddr`, `associate`, `associatePubKey` | | `0x1005` | Staking | Delegation and validator transactions, queries, pagination, pool, and parameters | | `0x1006` | Governance | `vote`, `voteWeighted`, `deposit`, `submitProposal` | | `0x1007` | Distribution | Reward queries, withdrawals, withdrawal address, and validator commission | | `0x1008` | Oracle | Both price-query methods revert with an explicit disabled-query error | | `0x1009` | IBC transfer | `transfer`, `transferWithDefaultTimeout` | | `0x100a` | Pointer lookup | Native, CW20, CW721, and CW1155 pointer address, version, and existence | | `0x100b` | Pointer creation | `addNativePointer`, `addCW20Pointer`, `addCW721Pointer`, `addCW1155Pointer` | | `0x100c` | Solo asset claims | `claim(bytes)`, `claimSpecific(bytes)` using signed Cosmos transaction payloads | | `0x1011` | P-256 signatures | `verify(bytes)` | Addresses in the table are shortened for readability. Pad them to 20 bytes, for example `0x0000000000000000000000000000000000001001`. `precompiles/common/` supplies shared gas, payment, ABI, and error handling; it is not another callable precompile. ## Address association `getPaxAddr(address)` resolves an existing EVM-to-Paxeer association. `getEvmAddr(string)` performs the reverse lookup. Account addresses use `pax1`; validator operator addresses use `paxvaloper1`. These lookups can fail when no association exists; they are not interchangeable with a bech32 encoding of the same 20 bytes. The manual association methods derive both addresses from a public key or signature. Use the key belonging to the account being linked. Creating a new random wallet would associate a different account. Signature construction must match the exact message bytes expected by `precompiles/addr/addr.go`. Use `layerXBindNonce` when preparing the consent message for `bindLayerX`. ## Bank balances and transfers Bank amounts are integers in the supplied base denomination. The native bank denomination is `uhpx`: one PAX equals `1,000,000 uhpx`, while EVM transaction value uses `10^18` wei per PAX. The internal human-unit identifier is `hpx`; see [network parameters](https://docs.paxeer.app/network-parameters) for the unit mapping. ``` // Minimal read ABI; the complete interface is precompiles/bank/abi.json. import { Contract, JsonRpcProvider, formatUnits } from 'ethers' export async function readBankBalance(rpcUrl, account) { const provider = new JsonRpcProvider(rpcUrl) if ((await provider.getNetwork()).chainId !== 125n) throw new Error('Wrong chain') const bank = new Contract( '0x0000000000000000000000000000000000001001', ['function balance(address,string) view returns (uint256)', 'function decimals(string) view returns (uint8)'], provider, ) const amount = await bank.balance(account, 'uhpx') console.log('bank base units:', amount.toString()) console.log('PAX:', formatUnits(amount, 6)) console.log('bank denomination decimals:', await bank.decimals('uhpx')) // 0 } ``` `bank.decimals(denom)` returns `0` because the ABI represents base-denomination integers. It does not return the display exponent of PAX. The `name` and `symbol` methods require bank denomination metadata. - `send(address from, address to, string denom, uint256 amount)` is nonpayable and restricted to the registered ERC-20 native pointer for that denomination. An arbitrary wrapper or wallet cannot call it successfully just by supplying a sender. - `sendNative(string toAddress)` is payable, sends EVM value to a Paxeer bech32 recipient, and preserves both whole `uhpx` and the smaller wei remainder. The caller must be associated; delegatecall is rejected. - `all_balances(address)` and `supply(string)` also expose base-denomination amounts. ## Staking and distribution Staking writes act for the immediate caller's associated account. A contract wrapper therefore controls its own position; querying its deployer's delegation does not inspect that position. Delegatecall is rejected. Payable staking methods receive EVM value and convert it into the native staking denomination; amount arguments and query results are denomination integers or fixed-point share and reward values whose exact scale is defined by each method's handler. Read the scale for a method in `precompiles/staking/` and `precompiles/distribution/` before converting a result for display, and keep delegation shares, pending rewards, and withdrawn amounts as separate quantities. The staking ABI also exposes validator creation and editing; validator, delegation, unbonding, and redelegation queries; historical information; `pool`; and `params`. Read current parameters for unbonding time and entry limits. Paginated queries return a bytes cursor: with ethers, an empty cursor is `0x`, whose JavaScript string length is two. Distribution supports `setWithdrawAddress`, `withdrawDelegationRewards`, `withdrawMultipleDelegationRewards`, `withdrawValidatorCommission`, and `rewards`. The withdrawal target must be associated. Some validator addresses are indexed strings in EVM events; an indexed string topic is a hash, not the original bech32 text. ## Governance transactions The governance ABI exposes writes only: `vote`, `voteWeighted`, `deposit`, and `submitProposal`. Use the native module query APIs to inspect proposals and live deposit or voting parameters. Take the exact argument and message shapes from `precompiles/gov/abi.json` and `precompiles/gov/handler.go` for the node revision you target, and confirm a submission through the native governance queries rather than assuming a particular EVM event. ## JSON extraction The JSON ABI provides `extractAsBytes(bytes,string)`, `extractAsBytesList(bytes,string)`, `extractAsUint256(bytes,string)`, and `extractAsBytesFromArray(bytes,uint16)`. Keys select a literal top-level field. To read a nested field, first extract its containing object. Byte-list results preserve each element's JSON representation, including quotes around strings. Decode returned hex bytes before parsing JSON. Integer extraction accepts decimal integers and quoted integer strings, rejects negative or oversized values, and does not implement floating-point conversion. ``` // With json connected to the current precompiles/json/abi.json: const document = toUtf8Bytes(JSON.stringify({ user: { count: '42' }, tags: ['one'] })) const user = await json.extractAsBytes(document, 'user') const count = await json.extractAsUint256(user, 'count') // 42n const tags = await json.extractAsBytesList(document, 'tags') const firstTag = JSON.parse(toUtf8String(tags[0])) // 'one' ``` The helper functions `toUtf8Bytes` and `toUtf8String` above are ethers exports. The implementation charges 100 gas per ABI argument byte, excluding the selector; total transaction gas includes other execution and transaction costs. ## P-256 signature verification At `0x1011`, `verify(bytes)` takes exactly 160 payload bytes: a 32-byte digest followed by 32-byte `r`, `s`, public-key `x`, and public-key `y`. Valid signatures return ABI-encoded `bytes` containing a 32-byte word with value one. Invalid signatures return empty low-level call data rather than an ABI-encoded result; handle that case before decoding. Malformed payload length reverts. This is an ABI call with a dynamic bytes argument. The 160-byte payload occupies 224 argument bytes after its offset and length words, so the precompile charges `224 × 300 = 67,200` precompile execution gas, before other call or transaction costs. P-256 verification is one part of a passkey flow; challenge, origin, authenticator data, and replay handling belong to the complete application ceremony. ## Cross-runtime and cross-chain calls The [CosmWasm guide](https://docs.paxeer.app/wasm) covers matching the native coin list to payable EVM value. [WASM bindings](https://docs.paxeer.app/wasmbinding) expose calls in the other direction. The [IBC guide](https://docs.paxeer.app/interchain) covers the transfer ABI, which does not expose channel queries. Pointer lookup returns the pointer address, a version, and an existence flag for one supplied native denomination or CosmWasm address. It does not provide a list-all query. Solo claims consume signed Cosmos transaction payloads; they are asset-claim operations rather than a general administrative interface. ## Oracle query behavior `getExchangeRates` and `getOracleTwaps` at `0x1008` revert with `oracle precompile is retired; oracle data queries are disabled`. See the [Oracle module guide](https://docs.paxeer.app/modules/oracle) for native module queries. The EVM pricefeed read interface is at `0x1020`. ## ABI and failure handling Use the matching `precompiles//abi.json`, simulate the real caller and value, and inspect revert data before sending a transaction. Module-backed precompiles can meter native execution dynamically; kernel constructs and the perpetuals venue use method gas tables. Use the gas policy of the specific precompile. An off-chain read needs no funded signer, while an on-chain call still consumes gas. In particular, address lookup is `getPaxAddr` in this tree. An SDK package targeting another chain can carry different selectors, chain IDs, prefixes, or addresses even when its API looks similar. --- URL: https://docs.paxeer.app/program-workspace # Programs Developer Workspace Build deterministic Paxeer X programs with runtime crates, language SDKs, fixtures, policies and reproducible development workflows. ## Start with the execution contract The Programs workspace contains the deterministic WebAssembly execution surface for the LayerX kernel domain of Paxeer X. Applications deploy artifacts and interfaces, execute under explicit capabilities, and express monetary effects as authenticated native transfer sets. Read [Programs](https://docs.paxeer.app/programs) before choosing entrypoints, account seeds, and spending grants. Rust workspace packages use edition 2021 and declare a minimum Rust version of 1.91.1. Cargo resolves dependencies from the checked-in vendor tree in offline mode, and the interpreter is pinned to `wasmi = 0.31.2`. Run Cargo from inside `programs/` so its local configuration applies. Lockfiles, source checksums, and frozen ABI vectors make builds and byte contracts reproducible. ## Choose the right package | Workspace area | Responsibility | | --- | --- | | `programs/crates/layerx-programs-runtime` | Validation, budgets, metering, host imports, storage, cross-program calls, transfer authorization, occupancy, replay, and kernel FFI. | | `programs/crates/layerx-programs-registry` | Receipt-bound deployment journals, interfaces, program account bindings, account proofs, and lifecycle exits. Its `chain_proof` module verifies committed chain evidence for program-state reads. | | `programs/crates/layerx-programs-ai-market` | PAXAI schema-1 common contracts and the direct native Programs entrypoint. | | `programs/crates/layerx-programs-interpreter` | Bounded deterministic scripts with canonical input validation before effects. | | `programs/crates/layerx-programs-market` | Compute leases, usage claims, challenge windows, provider stake, attesters, and bisection disputes. | | `programs/crates/layerx-programs-arbiter` | Sandbox trace replay and disputed single-step adjudication. | | `programs/crates/layerx-programs-sandbox` | Bounded lease lifecycle, isolated execution, snapshots, and restore. | | `programs/sdk/` and `programs/porting/` | Rust, C, and AssemblyScript guests; migration guides and reference guests for EVM, Solana, and CosmWasm developers. | | `programs/fixtures/`, `programs/tests/`, `programs/fuzz/`, `programs/benches/` | Canonical artifacts, cross-implementation vectors, hostile guests, fuzz corpora, and interpreter comparisons. | ## Build a guest application 1. Choose a guest SDK and a reference application close to your use case. 2. Define canonical calldata and responses, entrypoint bounds, storage scopes, and required grants. Select the guest ABI that supplies those host imports. 3. Keep state transitions deterministic. Consume admitted oracle or web evidence through host calls rather than adding a network client to execution. 4. Compile a WASM artifact, generate its canonical interface, and retain the artifact hash and interface together. 5. Deploy with the chosen upgrade policy, verify the receipt, register any program-owned accounts, and fund them through native transfers. 6. Simulate a bounded call, submit the signed activity, and verify committed terminal evidence. Rust examples cover escrow, naming, LXT-721, merchant payments, constant-product swaps, LXT-20, vaults, and web readers. C and AssemblyScript provide paid-counter guests. A reference application is an executable contract: preserve its documented selectors and authorization requirements when adapting it. ``` # From the repository root cd programs cargo build --locked --manifest-path sdk/rust/examples/token-lxt20/Cargo.toml \ --target wasm32-unknown-unknown --release ``` ## Build and validate the workspace The repository Makefile coordinates Rust and native C checks. Run these commands from the repository root; they enter the Programs directory where required. ``` make programs-build make programs-lint make programs-abi-drift make programs-test ``` | Gate | What it establishes | | --- | --- | | `programs-build` | Builds the locked workspace and sandbox host FFI used by native integration. | | `programs-lint` | Checks runtime module boundaries, Clippy, dependency and vendoring policy, advisories, sources, and dependency bans. | | `programs-abi-drift` | Checks frozen vectors and the runtime linker against the canonical guest import contract. | | `programs-core-test` | Exercises native registration, lifecycle, calls, monetary invariants, occupancy, fees, accounts, and wind-down. | | `programs-adversarial` | Checks guest isolation, composition, and monetary-law refusal paths. | | `programs-fuzz-smoke` | Replays validation, instantiation, and execution corpora. | | `programs-differential` | Checks deterministic replay and serial versus parallel execution behavior. | | `programs-interpreter-conformance` | Builds the interpreter WASM and exercises it through the runtime. | | `programs-test` | Combines protocol, native, guest SDK, porting, adversarial, fuzz, ABI, and differential checks. | ## Preserve ABI compatibility Frozen guest ABI versions 1 through 5 have independently pinned vector checksums in `programs/abi-frozen.sha256`. The ABI gate compares generated canonical bytes, manifests, validator allowlists, and SDK declarations with those baselines. An existing frozen import contract is immutable; add a new ABI version for a new surface. Keep the canonical vectors, interface generators and clients aligned with the selected ABI version. Deployment validation, host imports and response decoding use that version to select the same byte contract. ## Maintain runtime boundaries Host-function families register through their own modules and access execution state through `RuntimeState`. The boundary gate rejects forbidden sibling dependencies, legacy monolithic modules, and production paths into qualification-only helpers. The workspace denies unsafe code by default; explicitly bounded FFI adapters carry the reviewed boundary work. Dependency policy excludes entropy, clocks, arbitrary networking, dynamic registration, database engines, and alternate execution engines from the deterministic boundary. It verifies vendored checksums, the exact interpreter revision, approved licenses, and integer-only consensus-adjacent code. Workspace linting also rejects unchecked unwraps, expects, and float arithmetic. ## Canonical fixtures Lifecycle, capability, executed-receipt, and reference-program fixtures keep native encoders and SDKs aligned. Use the check targets when validating existing output; generation targets intentionally write new fixtures. ``` make programs-check-capability-fixture make programs-check-native-lifecycle-fixtures make programs-check-executed-v4-fixture # Rebuild reference artifacts when intentionally changing their source make programs-reference-fixtures ``` Retain the artifact hash, interface and chosen ABI with each deployed program. Applications verify deployment and execution receipts, including committed block evidence, before relying on a final program outcome. Continue with [bounded storage scans](https://docs.paxeer.app/storage-scan) and [sandbox execution](https://docs.paxeer.app/sandbox). **Technical references:** `programs/Cargo.toml`, `programs/.cargo/config.toml`, `Makefile`, `programs/abi-frozen.sha256`, `scripts/programs/dependency-policy.sh`, and `tests/programs/runtime-module-boundaries.sh`. --- URL: https://docs.paxeer.app/programs # 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](https://docs.paxeer.app/sandbox), [native Assets](https://docs.paxeer.app/assets), and [payments](https://docs.paxeer.app/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. --- URL: https://docs.paxeer.app/proofs # Receipts & Proofs Verify Paxeer outcomes independently with signed receipts, native state witnesses, custody proofs, and mirror archives. ## Choose the evidence for your decision Paxeer executes transactions inside the node and returns signed execution receipts. A merchant verifies payment facts before releasing a resource; an auditor preserves the signed outcome; an account owner verifies state against an authenticated root. Finality requires the covering block to commit. | Evidence | Establishes | Use | | --- | --- | --- | | Portable receipt (v2) | Canonical outcome authenticated by a pinned receipt key | Offline receipt validation and outcome accounting | | Native state witness | A canonical account or module fact is included in a composite state root | Balance and module-state verification | | Custody state proof | Custody state at verified heights under a pinned chain identity | Paxeer custody verification | | Mirror archive | A receipt belongs to an archive matching an independently observed mirror commitment | Independent receipt verification from Ethereum or Solana mirrors | ## Portable receipt format The portable format is `layerx-receipt-proof-v2`, implemented by `PortableReceiptV2` in `layerx-portable`. Verification runs offline against a receipt-key list pinned independently by the caller. The portable object establishes receipt authentication; it does not by itself prove block commitment. | Member | Value | | --- | --- | | `format` | `layerx-receipt-proof-v2` | | `verificationLevel` | `receipted` | | `signedReceipt` | Exact signed canonical receipt bytes; lowercase `0x` hex | | `receiptDigest` | 32-byte receipt digest; lowercase `0x` hex | | `receiptKey` | Object with `keyId` and `publicKey` (32 bytes each, `0x` hex) and `firstHeight` / `lastHeight` (`0x` quantities): the inclusive height window in which that key signs | | `inclusionHeight` | `0x` quantity; must not precede the signed receipt height | | `rawTransaction` | Optional; raw transaction bytes as `0x` hex, bound to the receipt activity ID | Byte strings are lowercase `0x` hex and heights are `0x` quantities. Unknown JSON members are refused. The JSON input limit is 1,500,000 bytes; the signed receipt must contain between 1 and 1,048,576 bytes. ### Establish the trust root first The trust root is your pinned `ReceiptKeys` list of `ReceiptKeyEntry` values (key ID, Ed25519 public key, first and last signing height). The `receiptKey` carried in the JSON names the entry that signed; it is trusted only after it equals the entry selected from your own pinned list. Copying the key out of the incoming JSON does not authorize it. ``` // Rust: json_bytes and receipt_keys (your pinned list) are supplied by your application. let verified = layerx_portable::PortableReceiptV2::verify_json( &json_bytes, &receipt_keys, )?; ``` `from_json` parses the bounded representation without establishing trust; `verify_json` parses and verifies it against your pinned keys. Export uses `PortableReceiptV2::export(signed_receipt, receipt_key, inclusion_height)`, or `export_with_transaction` to also bind raw transaction bytes. Export verifies the signed receipt before producing its JSON representation. `from_sequencer_receipt` exports the signed receipt of a `receipted` or `committed` RPC answer and refuses `submitted` answers. ### What verification checks 1. Parse the bounded JSON and decode every field in its canonical `0x` form. 2. Verify the node receipt key’s Ed25519 signature on the signed receipt against the pinned key list. 3. Select the pinned entry by the receipt key ID and require the carried `receiptKey` to equal it exactly. 4. Require `inclusionHeight` to be at or after the signed receipt height. 5. Recompute the receipt digest and require it to equal `receiptDigest`. 6. When `rawTransaction` is present, require its Keccak-256 hash to equal the receipt activity ID. ``` receipt_digest domain: "LXP/v1/receipt\0" ``` A cryptographically verified rejected outcome remains rejected. The portable proof authenticates the signed receipt. Its inclusion height is checked against the signed height, but is not an inclusion proof. Verify the covering block and its receipt coverage separately when commitment is required. **Source:** `services/interop/crates/layerx-portable/src/receipt.rs` — `PortableReceiptV2`, `verify_json`, `export`. ## Native state witnesses Native witnesses prove a canonical key/value leaf through its module subtree into the composite state root. Account leaves with module ID 0 and a 33-byte key beginning with byte 4 include a separate positional account-registry path, followed by the module-zero `account-tree` binding and the module wrapper. Lengths, indices, leaf counts, path depths and trailing bytes are checked. Odd-width Merkle levels duplicate the final node and require that exact sibling. The native leaf hash places both lengths before the key and value: ``` SHA256("LXP/v1/state-leaf\0" || key_len:u32be || value_len:u32be || key || value) SHA256("LXP/v1/state-node\0" || left[32] || right[32]) ``` **Source:** `services/agent/crates/layerx-proof/src/state_witness.rs`. ## Custody state proofs The Go `custodyproof` package verifies custody state bundles under the format version `paxeer-custody-state-v3`. `Verify(request, now)` checks a decoded request against an `Expected` pin set by the caller: genesis hash, Comet chain ID, EVM chain ID, custody identity, module hash, asset ID and confirmation count. It verifies the light-block history from genesis and the state membership proofs at the requested heights before returning a result. `Decode` parses the bounded JSON input. Pin the expected values from your own configuration. Values copied out of the incoming bundle do not authorize themselves. **Source:** `custodyproof/verify.go`, `custodyproof/decode.go`. ## Archive and mirror verification The Ethereum and Solana mirror tooling reads archives under configured source identities and read policies. `layerx-mirror-verify` checks the archive against the observed source commitment, requires a committed block coordinate, and verifies selected receipts against pinned receipt-key windows. It reports source provenance and freshness. The implementation is in `services/interop/crates/layerx-mirror/src/verify.rs` and its `src/bin/layerx-mirror-verify.rs` entry point. For long-term evidence, retain signed receipts, your pinned receipt-key list, authenticated block evidence, state proofs and mirror publication references. Preserve exact bytes rather than reconstructed display JSON. See [Data Availability](https://docs.paxeer.app/data-availability) for availability verification and [Finality](https://docs.paxeer.app/finality) for block commitment. ## Verification failures Handle typed refusals explicitly. Portable-receipt failures are distinct: JSON bounds or shape, receipt bounds, unsupported format or verification level, invalid hex, length or quantity, receipt verification failure, receipt-key mismatch, missing or mismatched digest, raw-transaction mismatch, a not-yet-receipted transaction, and an inclusion height preceding the signed height. Preserve the original activity ID for recovery and never upgrade a weaker evidence level to a stronger success. --- URL: https://docs.paxeer.app/public-rpc # Public RPC endpoints The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block on EVM chain ID 125. ## Connect to the node The LayerX kernel runs inside every `paxd` node, executes each transaction when it arrives, gives it the next position in one global sequence, returns a signed execution receipt and builds each block; validators check that block and commit it. The node exposes Ethereum JSON-RPC for contracts, balances, logs and broadcasts. A receipt is final once its covering block commits. | Interface | Endpoint | Purpose | | --- | --- | --- | | Node HTTP | `PAXEER_RPC_URL` | Your configured root JSON-RPC URL for reads and broadcasts. | | Node WebSocket | `PAXEER_WS_URL` | Your configured WebSocket URL for subscriptions and RPC sessions. | | Hosted gateway | `services/platform/hosted/gateway/openrpc.json` | Contract for the hosted gateway’s methods, parameters, results and errors. | Set the example variables to the endpoints supplied for your deployment. These are client-side variable names, not node configuration keys. HTTP JSON-RPC requests use the endpoint root. Node listener defaults and enabled methods are defined in `rpc/config/config.go` and `rpc/server.go`; public provider limits depend on its configuration. ## Verify the chain before signing | Setting | Value | | --- | --- | | EVM chain ID | 125 / `0x7d` | | Consensus identifier | `hyperpax_125-1` | | Native gas coin | `uhpx` (bond denom); bank metadata displays PAX at exponent 6 over `uhpx`. EVM amounts use wei, tracked as a sub-`uhpx` remainder. | ``` curl "$PAXEER_RPC_URL" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' ``` Check that the response is `0x7d`, then query `eth_blockNumber` to check head progress. Signing uses the configured chain ID for replay protection. ## Subscribe to chain heads ``` {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]} ``` Send the subscription request over your configured WebSocket connection. Reconnect a dropped connection and recreate subscriptions. Store your last processed block number so you can query missing logs after reconnecting. Deduplicate logs by transaction hash and log index; require covering-block commitment before treating an outcome as final. ## Fallback and request limits A node can trail another node. Compare block heights when freshness matters and use subscriptions where available. Bound event queries: `evm.max_blocks_for_log` defaults to 2000 and `evm.max_log_no_block` defaults to 10000. Operators can configure different limits. After a broadcast timeout, query the signed transaction's hash before deciding whether to rebroadcast the identical transaction. An interrupted transport does not establish rejection. Use `pax_sequencerReceipt` to distinguish submitted, receipted and committed transactions. The node’s governed receipt-key list is available through `px_getReceiptKeys`. ## Continue building - [Ethereum methods and compatibility](https://docs.paxeer.app/json-rpc) - [Unsupported Ethereum methods](https://docs.paxeer.app/json-rpc-unsupported) - [Hosted platform API reference](https://docs.paxeer.app/platform-api) - [Receipt and block commitment](https://docs.paxeer.app/finality) - [Wallet and frontend integration](https://docs.paxeer.app/building-a-frontend) --- URL: https://docs.paxeer.app/python # Python Quickstart Connect to Paxeer with web3.py, read PAX balances and ERC-20 state, and inspect transaction receipts without a signing key. Python is useful for application backends, data analysis, and operational scripts. This guide reads the Paxeer EVM through HTTP using web3.py. Every example is read-only and expects EVM chain ID 125, the mapping for `hyperpax_125-1`. The node also defaults unmapped chain identifiers to 125, so confirm the intended network and its genesis independently of this numeric check. ## Install in an isolated environment These examples use web3.py 7 as a client dependency in your own Python project. Create a virtual environment and keep the resulting dependency versions with that project. ``` python3 -m venv .venv source .venv/bin/activate python -m pip install "web3>=7,<8" ``` On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1`. Supply `PAXEER_RPC_URL` and `ACCOUNT_ADDRESS` through your shell or deployment environment. These variables are inputs to this example, not node configuration keys; the RPC URL uses the node endpoint’s root path. ## Read the chain and account Save this as `read_paxeer.py`, then run `python read_paxeer.py`. It validates the endpoint, captures one block, and reads the account at that height. ``` import os from web3 import Web3 w3 = Web3(Web3.HTTPProvider( os.environ["PAXEER_RPC_URL"], request_kwargs={"timeout": 30}, )) if not w3.is_connected(): raise RuntimeError("The EVM RPC endpoint did not respond") if w3.eth.chain_id != 125: raise RuntimeError("Expected Paxeer EVM chain ID 125") account = Web3.to_checksum_address(os.environ["ACCOUNT_ADDRESS"]) height = w3.eth.block_number balance = w3.eth.get_balance(account, block_identifier=height) nonce = w3.eth.get_transaction_count(account, block_identifier=height) print("Chain ID:", w3.eth.chain_id) print("Block:", height) print("Balance (PAX):", w3.from_wei(balance, "ether")) print("Nonce:", nonce) ``` `from_wei(..., "ether")` names an 18-decimal unit conversion in web3.py. On Paxeer the native currency being displayed is PAX. Use decimal values or integer base units for amounts; avoid converting balances through floating-point numbers. ## Read an ERC-20 balance Set `TOKEN_ADDRESS` and append this block to the script. The ABI is intentionally limited to the two methods being called. ``` from decimal import Decimal, localcontext abi = [ { "type": "function", "name": "decimals", "stateMutability": "view", "inputs": [], "outputs": [{"name": "", "type": "uint8"}], }, { "type": "function", "name": "balanceOf", "stateMutability": "view", "inputs": [{"name": "owner", "type": "address"}], "outputs": [{"name": "", "type": "uint256"}], }, ] token_address = Web3.to_checksum_address(os.environ["TOKEN_ADDRESS"]) if not w3.eth.get_code(token_address, block_identifier=height): raise RuntimeError("No contract exists at TOKEN_ADDRESS at this block") token = w3.eth.contract(address=token_address, abi=abi) decimals = token.functions.decimals().call(block_identifier=height) raw_balance = token.functions.balanceOf(account).call(block_identifier=height) with localcontext() as context: context.prec = 100 print("Token balance:", Decimal(raw_balance) / (Decimal(10) ** decimals)) ``` Use the token’s own decimals rather than PAX’s decimals. A missing method or unexpected return encoding indicates an ABI mismatch; obtain the ABI from the contract build or its verified deployment record. ## Inspect a transaction receipt Set `TX_HASH` to a transaction hash from the same network. Append this block to inspect execution status. A missing receipt can mean an unknown transaction or an unavailable indexed result. The node can expose a receipt from the open block, so use `pax_sequencerReceipt` and require its `committed` rung when finality matters. ``` from web3.exceptions import TransactionNotFound try: receipt = w3.eth.get_transaction_receipt(os.environ["TX_HASH"]) except TransactionNotFound: print("No receipt returned. Verify the network and transaction hash before retrying.") else: print("Execution:", "success" if receipt["status"] == 1 else "reverted") print("Block:", receipt["blockNumber"]) print("Gas used:", receipt["gasUsed"]) print("Logs:", len(receipt["logs"])) ``` ## Use the result in an application - Show an unavailable state when reads time out and offer a retry. - For repeated queries, preserve block numbers in your output so users can judge freshness. - Use bounded event ranges for indexers, following the [querying guide](https://docs.paxeer.app/querying-evm). - For transaction signing, add an explicit account-selection and transaction-review step. References: [web3.py 7 quickstart](https://web3py.readthedocs.io/en/v7.14.0/quickstart.html) and [contract calls](https://web3py.readthedocs.io/en/v7.14.0/contracts.html). **Paxeer source:** `rpc/state.go` (GetBalance and GetCode), `rpc/tx.go` (GetTransactionReceipt), `rpc/sequencer_receipt.go` (receipt rungs), and `modules/evm/config/config.go` (ChainIDMapping and DefaultChainID). --- URL: https://docs.paxeer.app/querying-evm # Query the EVM Read Paxeer balances, contract state, receipts, and bounded event ranges with JSON-RPC, Cast, and viem. Read-only queries work without a signer or a PAX balance. Choose an EVM JSON-RPC endpoint, confirm its network, and record the block number when several reads must describe the same state. ## Verify the endpoint Set `PAXEER_RPC_URL` to your EVM endpoint. For `hyperpax_125-1` the result of this request must be `0x7d`, which is decimal 125. The node defaults unmapped chain identifiers to 125 as well. Confirm the intended genesis and network independently; a matching numeric chain ID alone does not distinguish deployments. ``` : "${PAXEER_RPC_URL:?Set your Paxeer EVM RPC URL}" curl --fail-with-body --silent --show-error "$PAXEER_RPC_URL" -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' ``` HTTP 200 can still contain a JSON-RPC `error`. Check both the HTTP result and the response body. The consensus RPC server exposes routes such as `/status`; it is not interchangeable with the EVM JSON-RPC listener. ## Inspect accounts and contracts with Cast Set `ACCOUNT_ADDRESS` and `CONTRACT_ADDRESS` to addresses from your application or deployment records. The contract example assumes an ERC-20 token implementing `balanceOf` and `transfer`. Use its published ABI to encode and decode calls. ``` cast block-number --rpc-url "$PAXEER_RPC_URL" cast balance "$ACCOUNT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast nonce "$ACCOUNT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast code "$CONTRACT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast call "$CONTRACT_ADDRESS" 'balanceOf(address)(uint256)' "$ACCOUNT_ADDRESS" --rpc-url "$PAXEER_RPC_URL" cast calldata 'transfer(address,uint256)' "$ACCOUNT_ADDRESS" 42 ``` The final command only encodes calldata. It does not submit a transaction. `cast balance` returns native base units by default. A missing contract, wrong ABI, or unavailable historical state can make a read fail even when the RPC endpoint is healthy. ## Read token data at one block Install `viem` in your Node project with `npm install viem` and save this example as `read-token.mjs`. The repository’s wallet client also declares viem in `apps/wallet/package.json`. Set `TOKEN_ADDRESS` and `ACCOUNT_ADDRESS` to the EVM addresses you want to query, then run `node read-token.mjs`. ``` import { createPublicClient, formatUnits, getAddress, http, parseAbi } from "viem"; const rpcUrl = process.env.PAXEER_RPC_URL; if (!rpcUrl) throw new Error("Set PAXEER_RPC_URL"); const token = getAddress(process.env.TOKEN_ADDRESS ?? ""); const account = getAddress(process.env.ACCOUNT_ADDRESS ?? ""); const client = createPublicClient({ transport: http(rpcUrl) }); if (await client.getChainId() !== 125) throw new Error("Unexpected chain ID"); const blockNumber = await client.getBlockNumber(); const abi = parseAbi([ "function decimals() view returns (uint8)", "function symbol() view returns (string)", "function balanceOf(address owner) view returns (uint256)", ]); const [decimals, symbol, balance] = await Promise.all([ client.readContract({ address: token, abi, functionName: "decimals", blockNumber }), client.readContract({ address: token, abi, functionName: "symbol", blockNumber }), client.readContract({ address: token, abi, functionName: "balanceOf", args: [account], blockNumber }), ]); console.log({ block: blockNumber.toString(), symbol, balance: formatUnits(balance, decimals) }); ``` The requests run concurrently at the same block using ordinary contract calls. For tokens with a custom metadata interface, replace the example ABI with the contract’s published ABI. ## Fetch events in bounded ranges Save the following as `read-transfers.mjs`. Provide the token address, RPC URL, and an inclusive `FROM_BLOCK`/`TO_BLOCK` range. Start at the contract’s deployment block when building a full history. ``` import { createPublicClient, getAddress, http, parseAbiItem } from "viem"; const rpcUrl = process.env.PAXEER_RPC_URL; if (!rpcUrl || !process.env.FROM_BLOCK || !process.env.TO_BLOCK) { throw new Error("Set PAXEER_RPC_URL, FROM_BLOCK and TO_BLOCK"); } const address = getAddress(process.env.TOKEN_ADDRESS ?? ""); const client = createPublicClient({ transport: http(rpcUrl) }); if (await client.getChainId() !== 125) throw new Error("Unexpected chain ID"); const first = BigInt(process.env.FROM_BLOCK); const last = BigInt(process.env.TO_BLOCK); if (first < 0n || last < first) throw new Error("Invalid block range"); const event = parseAbiItem("event Transfer(address indexed from, address indexed to, uint256 value)"); const chunkSize = 500n; for (let fromBlock = first; fromBlock <= last; fromBlock += chunkSize) { const toBlock = fromBlock + chunkSize - 1n < last ? fromBlock + chunkSize - 1n : last; const logs = await client.getLogs({ address, event, fromBlock, toBlock, strict: true }); for (const log of logs) { console.log(JSON.stringify(log, (_, value) => typeof value === "bigint" ? value.toString() : value)); } } ``` Start with 500-block chunks and reduce the size if your provider returns a range or result-limit error. The node's default maximum `eth_getLogs` range is 2000 blocks, so 500-block chunks stay within it unless an operator configures a lower limit. A production indexer should commit processed logs and its cursor together, resume only after successful chunks, and deduplicate by chain ID, block hash, transaction hash, and log index. ## Keep transaction views consistent `eth_` methods provide the EVM view and exclude shell receipts and bank transfers. The `pax_` namespace additionally includes shell receipts, and `pax2_` additionally includes bank transfers, so the same block can list different transactions and indices per namespace; availability is configured by the node. Keep one namespace throughout an indexer and use hashes for lookup. See [JSON-RPC namespaces](https://docs.paxeer.app/json-rpc). For historical reads, the provider must retain state at that height. A recent balance read can work while an older `eth_call` fails. Inspect the receipt’s `status` for success or a revert. Open-block receipts can precede commitment; require `pax_sequencerReceipt` to report `committed` when finality is required. References: [viem contract reads](https://viem.sh/docs/contract/readContract), [event logs](https://viem.sh/docs/actions/public/getLogs), and [Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/). **Paxeer source:** `rpc/state.go` (StateAPI), `rpc/filter.go` (FilterAPI), `rpc/tx.go` (TransactionAPI), and `rpc/config/config.go` (query limits). --- URL: https://docs.paxeer.app/receipts # Receipts & Proofs Verify what the protocol executed, what it charged, and whether the covering block has committed. A receipt is evidence computed by the protocol. Clients submit signed activities; they do not choose receipt fields, balance outcomes, state roots, or result codes. Applications use verified receipts to reconcile payments, release paid resources, display completed work, and recover uncertain submissions. ## Activity receipt anatomy | Evidence | Native fields | What it establishes | | --- | --- | --- | | Identity and order | `activity_id`, `global_sequence`, `batch_id` | The activity and its position in ordered execution. | | State transition | `previous_state_root`, `resulting_state_root`, `activity_root` | The executed state transition and activity commitments. | | Outcome | `result_code`, `effects`, `fee_charged` | Success or refusal, computed effects, and execution charge. | | Rules | `protocol_version`, `module_id`, `module_version`, `parameter_version` | The execution rules needed for independent interpretation and replay. | | Authorization | `authorization_hash`, `context_hash`, `sequencer_signature` | The authorization and context commitments authenticated by the receipt signing key. | ## Payment evidence A successful payment operation provides protocol-computed before and after balances, asset and amount, sender and recipient account identifiers, sequence facts, transfer-set root, authorization and context hashes, chained state roots, batch identifier, timestamp, and signature. Client-supplied balances cannot establish payment. A failed payment produces a failure result with its result code and unchanged payment balances. It does not produce a signed successful payment receipt. The enclosing admitted activity can still incur protocol fee and sequence bookkeeping. Distinguish the payment’s economic outcome from the activity’s execution record. ### Programs produce receipt-native outcomes Program calls bind terminal success, failure, or resource exhaustion to the activity receipt. Outcome evidence includes runtime and ABI versions, fee and metering schedules, CPU fuel, memory and storage counters, output size, occupancy charges and evidence, call-graph commitments, terminal payload commitments, and transfer roots. A program’s local response or application log does not substitute for the protocol receipt. ## Finality rungs Node evidence is `pax_sequencerReceipt`. `px_getReceiptKeys` lists the node's pinned receipt keys. A receipt is final once its block is committed. There is no later checkpoint or settlement step. | Rung | Evidence | | --- | --- | | `submitted` | A known transaction without a signed execution receipt. | | `receipted` | A signed execution receipt awaiting block commitment. | | `committed` | A receipt covered by the committed block’s sequence batch. This is final. | An activity identifier or submission acknowledgement establishes neither execution nor finality. Authenticate the signed receipt against an independently pinned receipt-key list, match the intended operation, and require covering-block commitment before treating the result as final. The agent types crate accepts verification wire ranks 0, 1, 2, 3 and 6: `unverified`, `sequencer_signed`, `batch_included`, `state_proven` and `committed`. Receipt signature, batch inclusion and native state-witness checks do not authenticate a CometBFT commit. A parsed label alone does not establish verified evidence. ## Independent verification | Surface | Use | | --- | --- | | `layerx-proof` | Verify signed receipt bytes. | | `layerx receipt verify` | Perform a local check against caller-supplied batch facts. | | `layerx-portable` | Export and verify a `layerx-receipt-proof-v2` JSON object against independently pinned `ReceiptKeyEntry` values. | Portable verification runs offline. Its trust anchor is the caller’s independently pinned receipt-key list, including each key’s allowed signing heights. Merely packaging a receipt with a claimed signer does not make that signer authoritative. The portable proof authenticates a receipt but does not establish block commitment. For block-level verification, authenticate the block header and CometBFT commit, then verify transaction or state inclusion against the corresponding authenticated root. State proofs must name the relevant height and key. An unrelated newer head does not prove an earlier receipt's effects. ### Verification workflow 1. Decode canonical receipt bytes and authenticate the signature against the pinned receipt key valid at the signed height. 2. Match the activity identifier and require the expected success result. 3. For payment, compare asset, amount, source, destination, authorization, and context with the intended purchase or transfer. 4. Verify the covering block’s receipt coverage and any state proof against the corresponding authenticated root. 5. Require the `committed` rung from `pax_sequencerReceipt` when finality is required. 6. Persist the verified receipt identifier and evidence so retries and reconciliation refer to the original economic result. ## Unknown outcomes and honest UI states If submission fate cannot be determined, retain the signed transaction and its hash, then query the original receipt before considering a rebroadcast. Display the operation as still checking until verified evidence supports completion. An agent claims a result only after independently verifying node-produced evidence; a local success string is insufficient. ## Native receipt interfaces The C interface in `include/layerx/lxp_receipt.h` provides `lxp_receipt_encode`, `lxp_receipt_decode`, `lxp_receipt_sign`, `lxp_receipt_verify`, and `lxp_receipt_digest`. Program evidence is bound with `lxp_receipt_bind_program_outcome` and `lxp_receipt_bind_program_artifacts`. Supply validation is exposed through `lxp_receipt_validate_supply`. ## Continue reading - [Activity submission and recovery](https://docs.paxeer.app/activities) - [Payments](https://docs.paxeer.app/payments) - [Sequencing](https://docs.paxeer.app/sequencing) - [Finality](https://docs.paxeer.app/finality) - [Program execution evidence](https://docs.paxeer.app/programs) - [CLI verification](https://docs.paxeer.app/cli) --- URL: https://docs.paxeer.app/registry # Program Registry Resolve proof-verified program deployments, versioned interfaces and reproducible source in the hosted registry. ## A verified record of deployed programs The Paxeer X registry connects a program identity to its deployment receipts, executable code hashes, ABI versions, upgrade policy, lifecycle and value accounts. Applications resolve the current verified version before preparing calls. Publishers attach source that the registry rebuilds in a pinned environment and compares with the registered artifact. Registry records derive from authenticated deployment proofs and committed program state. Deploy the program on chain, then submit its canonical deployment evidence. Registration verifies that evidence and records the deployment; it does not submit a deployment transaction. ## Registry API | Method and path | Purpose | | --- | --- | | `GET /v1/programs/registry` | List registered program IDs with current verified head and freshness information. | | `GET /v1/programs/registry/{program_id}` | Resolve deployment history, current version, lifecycle and accounts. | | `GET /v1/programs/registry/{program_id}/interface` | Read the interface bound to the current verified version. | | `POST /v1/programs/registry/{program_id}/source` | Rebuild mirrored source and compare its artifact with the verified deployed program. | | `POST /__registry/deployments` | Verify canonical deployment admission evidence against chain trust and journal the accepted deployment. | | `POST /__registry/sources` | Publish an encoded source archive, build plan and source URI. | | `POST /__registry/head` | Refresh the journal head for the supplied program_id using the configured chain RPC. | Program IDs contain 32 hexadecimal-encoded bytes. Direct registry access requires mutual TLS and the appropriate Bearer credential. Request and source-publication credentials are separate. Source publication also resolves the `LayerX-Key` header to an authorized principal. ## Deploy and register 1. Build the program and deploy it on chain through the ordinary Programs deployment path. 2. Send canonical `DeploymentProof` bytes to `POST /__registry/deployments`, either as the raw body or in a JSON object whose `admission` member is the canonical proof as an array of byte values. A malformed or refused proof returns `422 deployment_proof_refused` (*deployment evidence must authenticate the registered program*). 3. The registry authenticates a current chain head and verifies the submitted proof under its persisted chain trust. `LAYERX_REGISTRY_CHAIN_RPC_URL` is required at startup for chain RPC access; registration does not submit an activity. 4. Invalid deployment evidence or version history returns `422 deployment_proof_refused`. The accepted record is journaled and the registry projection is rebuilt; persistence or rebuild failure returns `503 journal_unavailable`. Success returns `200`. 5. Resolve the program and its current interface before enabling application calls. The success response carries `transaction_hash`, `program_id`, `code_hash`, `abi_version`, `version` and `state: "deployed"`, derived from verified evidence. Register upgrades after their on-chain execution and retain the verified predecessor deployment. ### Deployment proof validation The registry verifies the deployment’s chain commitment, transaction execution and program-state evidence against a current authenticated head. It records the verified deployment in a sealed envelope. On rebuild, stored proofs are verified again against node state and their consumer exports are regenerated. ## Read a program record | Field group | What it tells an application | | --- | --- | | `program_id`, `latest_version`, `versions` | Stable program identity and numbered deployments with code hash, ABI and receipt digest. | | `upgrade_policy` | Immutable, or upgradeable with a named authority. | | `lifecycle`, `lifecycle_history`, `exit_routes` | Active, deprecated or tombstoned status and relevant exit information. | | `value_accounts` | Program account bindings and proof-verified balance information for account-capable ABIs. | | `state_root`, `observed_sequence`, `observed_at`, `valid_through` | The authenticated state and permitted freshness window. | | `receipt`, `source` | Deployment evidence and source verification status. | ABI 1 programs with no value accounts report `account-incapable-abi1`. Account-capable ABIs require current account-primary and state proofs matching the program, lifecycle, bindings and registry head. ABI 2 uses the account-primary profile; ABIs 3–5 use account profile 2, which additionally identifies the verified owner. ## Publish and verify source Publish the archive into the operator-controlled mirror using `source_uri`, encoded `plan` and `archive_hex`. The response returns the archive digest. The URI is an identifier for mirrored content; verification uses the retained archive and pinned build plan. ``` POST /v1/programs/registry//source Content-Type: application/json Idempotency-Key: verify-program-release-0001 Authorization: Bearer LayerX-Key: { "source_uri": "", "source_digest": "<32-byte-source-digest-hex>" } ``` The idempotency key contains 16–128 ASCII letters, digits, hyphens or underscores. Source verification binds the request to the resolved principal and verified deployment provenance. A changed deployment cannot inherit an earlier verification result. ### Reproducible build verdicts The builder runs offline in an isolated process tree using the pinned environment, runtime and supervisor digests. CPU, memory, process count, file size, workspace quota and deadline bounds constrain each build. The reproduced artifact digest must match the registered code hash. Source status is `unpublished`, `verified` or `mismatch`. Verified results include source and environment digests and pipeline information. A mismatch returns the expected deployed hash and reproduced artifact hash. Durable verification state and a publication outbox allow recovery to finish publication without relabeling unrelated evidence. ## The deployment journal The journal stores sealed `.envelope` units containing the canonical deployment record and proof under a domain-separated envelope with a SHA-256 seal. Publication writes a temporary file, synchronizes it, renames it and synchronizes the directory. The envelope is the atomic commit authority. Restart replay re-verifies complete records, rebuilds the registry projection and quarantines incomplete, corrupt or misfiled units. The verified source store is compared again with registered protocol state. Cached program state is hash-checked and refreshed against a verified current head before publication. ### Export evidence to consumers The journal's `pairs/` directory exports matching `.admission` and `.deployment` files. These use canonical DeploymentProof and DeploymentRecord encodings. Startup replay regenerates interrupted exports from committed envelopes; a consumer refuses an incomplete pair. Configure evidence consumers to read the exported pair directory. Preserve owner-only file modes and materialize exports through an authorized process when consumers run under another identity. Keep the journal, source mirror, verification state and chain trust in protected durable storage. ## Operate and troubleshoot `GET /healthz` reports registry readiness. Verify actual program reads and a current independently authenticated head before relying on registry data. The default freshness bound is 300 seconds and is configurable through `LAYERX_REGISTRY_MAX_STALENESS_SECONDS`. | Refusal | Action | | --- | --- | | `deployment_proof_refused`, `journal_unavailable` | Supply valid deployment evidence and restore the required journal and node-state dependencies. | | `stale_read`, `protocol_head_unavailable` | Restore head synchronization before using the record for a new call. | | `source_mismatch`, `build_not_reproducible` | Correct source or build inputs and publish a new verification request. | | `publication_principal_unresolved` | Resolve the publication key to its authorized identity. | | `protocol_state_unavailable` | Restore authenticated program-state reads and retain the committed deployment evidence. | Continue with [program discovery and safe resolution](https://docs.paxeer.app/discovery), or [identity and ownership](https://docs.paxeer.app/identity). **Technical references:** `services/platform/hosted/registry/src/` contains `routes.rs`, `journal.rs`, `node_state.rs`, `head_attestation.rs` and `builder.rs`. --- URL: https://docs.paxeer.app/relay-archive # Chain History & Archives Read retained chain history from full or archive nodes and verify exported receipt evidence. ## Full and archive nodes The chain node is `paxd`. Initialize with `--mode full` for recent query history or `--mode archive` to retain all available state history and blocks. The archive profile retains state history and blocks by setting its retention counts to zero; the generated application configuration includes `ss-keep-recent` under `[state-store]` and `min-retain-blocks`. Retention applies to the history the node has synchronized or restored. Choose retention for the queries your application needs. A recent read can succeed while a request for pruned state fails. A snapshot supplies only the history included in that snapshot. ## Read chain history through node RPC Use `eth_getBlockByNumber`, `eth_getTransactionReceipt` and bounded `eth_getLogs` queries at the node’s root JSON-RPC endpoint. Keep one transaction namespace throughout an indexer and retain block coordinates with each result. Use `pax_sequencerReceipt` to distinguish a signed execution result from one covered by a committed block. ## Verify receipt archives The mirror tooling under `services/interop/crates/layerx-mirror/` reads Ethereum or Solana archives under configured source trust. It checks archive commitments, committed block coordinates and receipt signatures. Preserve receipt-key pins and source provenance with the archive, and use its reported freshness when deciding whether the evidence is current. ## Continue reading For chain history and state, run a `paxd` full or archive node (see [Run a Node](https://docs.paxeer.app/run-node) and [Configuration](https://docs.paxeer.app/configuration)). For receipts and proofs, see [Receipts & Proofs](https://docs.paxeer.app/proofs) and [Data Availability](https://docs.paxeer.app/data-availability). For external mirrors, see [External Mirrors](https://docs.paxeer.app/mirrors). **Source:** `node/params/config.go`, `rpc/block.go`, `rpc/tx.go`, `rpc/filter.go`, `rpc/sequencer_receipt.go` and `services/interop/crates/layerx-mirror/src/verify.rs`. --- URL: https://docs.paxeer.app/rest-grpc # REST & gRPC APIs Cosmos SDK REST and gRPC interfaces for Paxeer chain modules and administration. **Source:** `api/` proto definitions, `node/app.go` route registration ## Overview Paxeer exposes Cosmos SDK-style gRPC and REST (gRPC-Gateway) endpoints for chain modules. These APIs complement the [JSON-RPC interface](https://docs.paxeer.app/json-rpc) and provide access to chain state, module parameters, and administrative operations. ### Protocol Buffers Chain-module and admin service definitions use Protocol Buffers v3 under `api/`. SDK, consensus and Wasm definitions also live in their own trees. Generation provides: - Go types at each file’s go_package path, including modules, precompiles and admin types - gRPC server and client interfaces - REST endpoints via `google.api.http` annotations - Swagger input from HTTP-annotated query definitions ### Code Generation Regenerate Go code from proto files, from the repository root: ``` ./scripts/protoc.sh ``` The script builds `protoc-gen-gocosmos` from cosmos-proto v0.3.1 and runs `buf generate` through `buf@v1.58.0`. It uses root `buf.yaml` / `buf.gen.yaml` and the two consensus/internal templates, then copies generated Go files into their package directories. See `api/README.md`. ## EVM Module Query Service The EVM module provides address mapping, static calls, and pointer queries. ### Address Mapping | Method | REST Endpoint | Purpose | | --- | --- | --- | | `PaxAddressByEVMAddress` | `GET /pax-protocol/paxchain/evm/pax_address` | Get Cosmos address from EVM address | | `EVMAddressByPaxAddress` | `GET /pax-protocol/paxchain/evm/evm_address` | Get EVM address from Cosmos address | ### Static Calls | Method | REST Endpoint | Purpose | | --- | --- | --- | | `StaticCall` | `GET /pax-protocol/paxchain/evm/static_call` | Execute read-only contract call | ### Pointer Queries Pointer queries resolve native denominations and CW20, CW721, CW1155 or ERC token mappings according to the requested pointer type: | Method | REST Endpoint | Purpose | | --- | --- | --- | | `Pointer` | `GET /pax-protocol/paxchain/evm/pointer` | Get a registered pointer for the requested type and pointee | | `Pointee` | `GET /pax-protocol/paxchain/evm/pointee` | Get the registered pointee for the requested pointer type and address | | `PointerVersion` | `GET /pax-protocol/paxchain/evm/pointer_version` | Get current pointer contract version | **Proto:** `api/evm/query.proto` ## Epoch Module Query Service The Epoch module tracks the current chain epoch for time-based operations: | Method | REST Endpoint | Purpose | | --- | --- | --- | | `Epoch` | `GET /pax-protocol/paxchain/epoch/epoch` | Get current epoch number and metadata | | `Params` | `GET /pax-protocol/paxchain/epoch/params` | Get epoch module parameters | **Proto:** `api/epoch/query.proto` ## Oracle Module Query Service The Oracle module provides exchange rates, price feeds, and validator vote tracking: ### Exchange Rates & Prices | Method | REST Endpoint | Purpose | | --- | --- | --- | | `ExchangeRate` | `GET /pax-protocol/pax-chain/oracle/denoms/{denom}/exchange_rate` | Get exchange rate for a denom | | `ExchangeRates` | `GET /pax-protocol/pax-chain/oracle/denoms/exchange_rates` | Get all exchange rates | | `Actives` | `GET /pax-protocol/pax-chain/oracle/denoms/actives` | List all active denoms | | `VoteTargets` | `GET /pax-protocol/pax-chain/oracle/denoms/vote_targets` | List vote target denoms | | `PriceSnapshotHistory` | `GET /pax-protocol/pax-chain/oracle/denoms/price_snapshot_history` | Get historical price snapshots | | `Twaps` | `GET /pax-protocol/pax-chain/oracle/denoms/twaps/{lookback_seconds}` | Get time-weighted average prices | ### Validator Vote Tracking | Method | REST Endpoint | Purpose | | --- | --- | --- | | `FeederDelegation` | `GET /pax-protocol/pax-chain/oracle/validators/{validator_addr}/feeder` | Get feeder delegation for validator | | `VotePenaltyCounter` | `GET /pax-protocol/pax-chain/oracle/validators/{validator_addr}/vote_penalty_counter` | Get oracle miss counter | | `SlashWindow` | `GET /pax-protocol/pax-chain/oracle/slash_window` | Get slash window information | | `Params` | `GET /pax-protocol/pax-chain/oracle/params` | Get oracle module parameters | **Proto:** `api/oracle/query.proto` ## TokenFactory Module Query Service The TokenFactory module manages custom token creation and metadata: | Method | REST Endpoint | Purpose | | --- | --- | --- | | `Params` | `GET /pax-protocol/paxchain/tokenfactory/params` | Get tokenfactory parameters | | `DenomAuthorityMetadata` | `GET /pax-protocol/paxchain/tokenfactory/denoms/{denom}/authority_metadata` (additional binding: `GET /pax-protocol/paxchain/tokenfactory/denom_authority_metadata`) | Get denom authority metadata | | `DenomMetadata` | `GET /pax-protocol/paxchain/tokenfactory/denoms/metadata` | Get denom metadata | | `DenomsFromCreator` | `GET /pax-protocol/paxchain/tokenfactory/denoms_from_creator/{creator}` | List denoms created by an address | | `DenomAllowList` | `GET /pax-protocol/paxchain/tokenfactory/denoms/allow_list` | Get denom allow list | | `DenomPaused` | `GET /pax-protocol/paxchain/tokenfactory/denoms/{denom}/paused` (additional binding: `GET /pax-protocol/paxchain/tokenfactory/denom_paused`) | Query the pause status and issuer DID of a denom | **Proto:** `api/tokenfactory/query.proto` ## Mint Module Query Service The Mint module exposes minting parameters and state: | Method | REST Endpoint | Purpose | | --- | --- | --- | | `Params` | `GET /paxchain/mint/v1beta1/params` | Get mint module parameters | | `Minter` | `GET /paxchain/mint/v1beta1/minter` | Get minter state (start/end dates, amounts) | **Proto:** `api/mint/v1beta1/query.proto` ## Other Module Query Services The `api/` tree also contains definitions for `launchpad`, `layerxagent`, `layerxpay`, `layerxprograms`, `pricefeed`, `xweb` and other chain modules. Read each service’s `query.proto` and its registration in `node/app.go` before selecting a method. HTTP bindings are declared per method; a gRPC method does not automatically have a REST route. This page details EVM, Epoch, Oracle, TokenFactory and Mint queries. ## Admin gRPC Service The Admin service provides runtime log level control. It runs on a separate loopback-only gRPC server (default port `9095`) and is disabled by default: | Method | Purpose | | --- | --- | | `SetLogLevel` | Change log level for loggers matching a pattern | | `GetLogLevel` | Get current log level for a logger | | `ListLoggers` | List all registered loggers and their levels | Enable in `app.toml`, replacing the address placeholder with a loopback IP and port: ``` [admin_server] admin_enabled = true admin_address = ":9095" ``` **Proto:** `api/pax/admin/v0/admin.proto` **Implementation:** `admin/` ## OpenAPI / Swagger Documentation The Swagger script generates OpenAPI documentation with Ignite, then embeds prepared assets with statik. To regenerate from the repository root: ``` ./scripts/update-swagger-ui-statik.sh ``` The script prepares `docs/swagger-ui/`, including `swagger.yml`, and writes the embedded assets to `docs/swagger/statik.go`. Use `./scripts/update-swagger-ui-statik.sh --assets-only` to embed existing assets without OpenAPI generation. ### Serving Swagger UI Enable in `app.toml`: ``` [api] enable = true swagger = true ``` The enabled API listener serves the embedded assets at `/swagger/`. **See:** `scripts/update-swagger-ui-statik.sh` and `scripts/swagger_assets.py` ## gRPC Endpoints Enabled gRPC listeners use port `9090` by default. Set `GRPC_ADDRESS` to your listener’s host and port; it is an example client variable. For a plaintext listener, `grpcurl` can list services and request epoch parameters: ``` grpcurl -plaintext "$GRPC_ADDRESS" list grpcurl -plaintext "$GRPC_ADDRESS" paxprotocol.paxchain.epoch.Query/Params ``` ## REST Gateway REST query routes are served via gRPC-Gateway on the API listener, whose default port is `1317`. The API is enabled by the full and archive initialization profiles. Only registered methods with HTTP bindings have the annotated REST paths. ## Transaction Services State-changing messages are declared in `Msg` services, including `api/evm/tx.proto` and `api/tokenfactory/tx.proto`. These differ from query methods. Encode and sign the appropriate transaction, then submit through the Cosmos SDK transaction service. --- URL: https://docs.paxeer.app/run-node # Run a Node Initialize a Paxeer X node, choose its role, connect to a network, and verify synchronization. ## Chain node and hosted services The chain node is `paxd`. The kernel executes inside the node, and the proposer executes transactions and proposes their block. A receipt is final once its block commits. Hosted applications such as the gateway and registry live under `services/platform/hosted/` and have their own configuration and state. This page covers the chain node. Initialize the node for its intended role, install the verified network genesis and configure peers before starting. Verify synchronization and receipt reads before admitting application traffic. See [operators](https://docs.paxeer.app/operators), [configuration](https://docs.paxeer.app/configuration), [chain history and archives](https://docs.paxeer.app/relay-archive), and [kernel architecture](https://docs.paxeer.app/layerx-kernel). ## Before You Start Install a `paxd` revision compatible with the network you intend to join. Obtain its genesis file, peer information, and any snapshot or state-sync checkpoint from that network's operator. Keep EVM RPC and consensus RPC endpoints separate. Size disk, memory, and CPU for your retained history and query workload. See [Installation](https://docs.paxeer.app/installation) for build requirements and [Configuration](https://docs.paxeer.app/configuration) for node profiles. ## Node Types - **Full:** Serves application and EVM queries and retains recent history by default. - **Archive:** Serves full-node APIs and retains available historical state and blocks. - **Validator:** Runs the signing node profile; active-set membership also requires an on-chain validator and sufficient stake. - **Seed:** Uses the peer-discovery profile. ## Initialize Node ``` paxd init my-node --chain-id hyperpax_125-1 --mode full ``` The default home is `~/.paxeer`. Init writes configuration and a local genesis. To join an existing network, install that network's verified genesis before starting. Validator operators should select `--mode validator` before configuring the signer and peer topology. ## Genesis and Peers Place the verified network genesis at `~/.paxeer/config/genesis.json`. Confirm its chain ID and expected checksum. Configure `bootstrap-peers` and `persistent-peers` under `[p2p]` in `config.toml` using the network's peer entries in `node-id@host:port` form. The default peer port is 26656. [HPX tooling](https://docs.paxeer.app/admin-hpx) provides distribution manifests, genesis, and peer registry handling for managed node setup. ## Sync Methods ### Block Replay A node with compatible genesis and an available block history can replay blocks. Use the correct binaries and upgrades for that history. ### State Sync State sync imports an application snapshot at a recent height. In `config.toml`, the `[statesync]` section uses `enable`, `rpc-servers`, `trust-height`, `trust-hash`, and `trust-period`. RPC-based state sync requires at least two RPC servers and a trusted checkpoint within the trust period. It starts only when the node has no local application state. Set `TM_RPC_URL` to your consensus HTTP endpoint and `TRUST_HEIGHT` to the checkpoint height. These are client-side variables for the following queries: ``` curl -sS "$TM_RPC_URL/status" | jq '.result.sync_info' curl -sS "$TM_RPC_URL/block?height=$TRUST_HEIGHT" | jq '.result.block.header, .result.block_id.hash' ``` Consensus JSON-RPC data is inside `result`. Check the response for a matching height and valid block hash before entering the checkpoint in your configuration. ### Snapshot Restore For a filesystem snapshot, stop the node first and verify the archive's layout, checksum, revision, and storage backend. Preserve the validator signing key and its last-sign state. Restore to the provider's documented directories, including any SC or SS paths configured outside the default home. Choose a snapshot covering the historical range your application needs. Archive retention preserves that imported history and subsequent state. ## Start Node ``` paxd start --home "$HOME/.paxeer" ``` To use a different data directory, set the example variable `NODE_HOME` to the initialized node home. The `--home` option selects that directory: ``` paxd start --home "$NODE_HOME" ``` ## Verify Synchronization ``` paxd status --node "$TM_NODE_URL" curl -sS "$TM_RPC_URL/status" | jq '.result.sync_info' curl -sS "$TM_RPC_URL/net_info" | jq '.result.n_peers' ``` Set `TM_NODE_URL` to the consensus RPC address accepted by `paxd status --node`, with its transport scheme. The default consensus RPC port is 26657. Confirm the expected chain identity, advancing block height and completed synchronization before directing application traffic to the node. ## Validator Setup After synchronization, create or select the operator account and fund it with the intended stake and fees. The consensus signing key is separate from that account. Use [Operators Guide](https://docs.paxeer.app/operators) for registration and last-sign-state handling. ## Local Docker Development From the repository root, start the local Docker cluster with the target forwarded to `chain.mk`: ``` make docker-cluster-start ``` See [Docker](https://docs.paxeer.app/docker) for the local cluster and monitoring targets. **Source:** `daemon/paxd/cmd/init.go`, `node/params/config.go`, `consensus/config/config.go`, `consensus/rpc/jsonrpc/types/types.go`, `consensus/privval/file.go`. --- URL: https://docs.paxeer.app/sandbox # Bounded Sandboxes Lease isolated deterministic computation with explicit resource ceilings, receipt-backed lifecycle transitions, metered snapshots, and resumable execution. ## A lease is the execution boundary Paxeer X sandboxes run validated guest images inside a bounded lease. Each lease binds a renter principal, host program, image, private storage namespace, resource limits, lifetime, escrow, and fee schedule. Execution derives its authority from this lease rather than inheriting unrestricted host-program access. Use a sandbox for isolated computation whose state and execution must remain replayable and whose cost and duration must remain bounded. Native financial application logic uses the broader [Programs execution surface](https://docs.paxeer.app/programs); a sandbox guest receives only lease-scoped storage authority. ## Receipt-backed lease lifecycle | State | Meaning and next step | | --- | --- | | Requested | The lease holds a principal concurrency slot. Fund it or let it expire. | | Funded | Escrow is established. Activate execution or restore an eligible snapshot into this target. | | Active | Execute within the lease bounds, persist an authorized snapshot, begin settlement, or expire. | | Settling | Finalize usage and the lease's economic disposition; proceed to expiry. | | Expired | The concurrency slot is released. Destroy storage with the required evidence. | | Destroyed | Terminal state. The same lease cannot be funded, activated, or revived. | The ordinary lifecycle is Requested → Funded → Active → Settling → Expired → Destroyed. Snapshot preserves the Active state. Expiry can also close a Requested, Funded, or Active lease once its batch-sequence deadline is reached. A Settling lease can expire through its settlement path. Transitions consume verified receipt evidence and reject replayed evidence or undeclared state edges. A principal has at most 32 concurrent leases. Requested, Funded, Active, and Settling all count toward this limit. Expiry releases the slot; destroying an already expired lease does not release it a second time. ## Resource limits and closure Declare execution ceilings, namespace capacity, lifetime in protocol batches, and escrow before activation. Usage observations are monotonic: a later observation cannot reset consumed resources. Execution refuses an exhausted resource budget or a request at or after expiry. Recording usage beyond a resource bound, at expiry, or beyond escrow requires verified `CloseBoundExceeded` transition evidence tied to that observation; the lease then moves from Active to Settling. Without that evidence, the usage update is refused. | Dimension | Protocol declaration ceiling | | --- | --- | | CPU fuel | 1,000,000,000 | | Linear memory | 1 GiB | | Storage reads / writes | 1 GiB each | | Output bytes | 1 GiB | | Output values | 65,536 | | Table elements | 1,048,576 | | Namespace storage | 1 GiB, including persisted snapshot records | | Lifetime | 1,000,000 protocol batches | Escrow is also capped: a lease escrow must be nonzero and at most 1,000,000,000,000,000,000,000,000. Each lease records at most 64 snapshots and 70 lifecycle transitions. These are maximum declarations, not allocations promised to every workload. Each lease selects its own admitted limits and fee coverage. Meter memory, state, outputs, snapshot persistence, and restoration together when planning a resumable workload. ## Authority that cannot escape the lease The execution principal and storage namespace derive from the host program and lease identity. The capability set contains only `StorageRead` and `StorageWrite`. Shared storage, native transfers, balance reads, receipt reads, event emission, and calls to other programs are absent. A guest that imports event or call functions does not gain their authority. Attempted event emission refuses; a call to an unleased program fails the composition capability check. The refused operation leaves sandbox storage unchanged. The boundary is enforced by capability derivation rather than by trusting the guest to follow a convention. ## Persist execution state and resume it ### Canonical snapshots A renter-authorized snapshot captures the source lease, host program, namespace prefix, linear memory, globals, continuation, and ordered namespace cells. Canonical encoding begins with `LayerX/programs/sandbox/snapshot/v1` followed by a NUL byte. SHA-256 commits the exact encoded state. Persistence stores a 44-byte manifest containing the digest, byte length, and chunk count, followed by chunks of up to 65,536 bytes. Metered storage includes keys and values. Snapshot records share the lease's namespace capacity with live state, so repeated snapshots cannot bypass the storage ceiling. ### Restore into a funded target Restore requires the canonical snapshot state, a recognized snapshot digest, a Funded target lease, the same owner principal, the same host program, the same image hash and a guest that supports continuation. Live cells are rebound to the target namespace. Restoration charges the canonical snapshot bytes and reconstructed cells before instantiation; reconstructing memory and the continuation also consumes runtime resources. A successful restore preserves the captured memory, globals, continuation entry point and arguments, and namespace cells. Retain the canonical snapshot bytes before destroying the source storage. The target is a new bounded lease. Destroying the source lease does not make its identity reusable. ## End-to-end workflow 1. Validate and identify the guest image. Choose the host program and renter principal. 2. Request a lease with explicit resource, namespace, lifetime, escrow, and fee-schedule bounds. Retain the verified request evidence. 3. Fund and activate through the admitted lifecycle transitions. 4. Run under derived lease capabilities and record monotonic usage evidence. 5. If resumption is required, persist a renter-authorized snapshot while Active and retain its canonical bytes and digest. 6. Settle, expire, and destroy the source lease with the required evidence. 7. Fund a compatible target lease, restore the snapshot with sufficient reconstruction budget, and continue under the new lease's bounds. ## Results and verification Retain the lease ID, image hash, transition receipt digests, batch sequences, usage observations, and snapshot digest where applicable. These identify what ran, under which bounds, which state was captured, and how the lease reached its final state. A guest return value alone does not prove funding, settlement, or destruction. Sandbox trace replay also supports deterministic compute-market dispute adjudication: the arbiter checks the step to which a bisection dispute resolves. The sandbox remains storage-only even when a surrounding market program manages stake, claims, or settlement. Read [Programs](https://docs.paxeer.app/programs) for deployment, broader capability grants, native value accounts, and atomic transfer settlement. **Technical references:** `programs/crates/layerx-programs-sandbox/src/` contains `lease.rs`, `execute.rs`, `snapshot.rs` and `expiry.rs`; market replay verification in `programs/crates/layerx-programs-arbiter/src/market.rs`. --- URL: https://docs.paxeer.app/sdk-quickstarts # SDK quickstarts Register a principal, fund an account, submit a signed transaction, and verify execution evidence with the Paxeer X SDKs. ## Register, fund, send, verify Choose a node transaction flow or a Human payment journey before selecting a client. `eth_sendRawTransaction` submits signed EVM transactions to the node; `px_register` creates a principal binding through the hosted gateway. Retrieve progress with `pax_sequencerReceipt` and trusted signing-key data with `px_getReceiptKeys`. Faucet funding requires an authorized identity session. ## Rust Use `RpcClient` for node access and hosted registration. Sign the digest from `register::binding` before registering. Node connections use `RpcClient::connect_node`; `RpcClient::get_balance` reads an EVM balance, and `RpcClient::send_raw_transaction` submits signed transaction bytes. ### Registration binding ``` use layerx_sdk::register::{binding, TENANT}; use layerx_sdk::rpc::{RpcClient, RpcError}; fn registration_digest(public_key: &[u8; 32]) -> [u8; 32] { binding(TENANT, public_key) } fn register(rpc: &RpcClient, public_key: [u8; 32], signature: &[u8; 64]) -> Result { rpc.register(public_key, signature) } ``` ### Read an EVM balance ``` use layerx_sdk::rpc::{RpcClient, RpcError}; fn balance(rpc: &RpcClient, address: &str) -> Result { rpc.get_balance(address) } ``` ### Submit a signed EVM transaction ``` use layerx_sdk::rpc::{RpcClient, RpcError}; fn send(rpc: &RpcClient, raw: &[u8]) -> Result<[u8; 32], RpcError> { rpc.send_raw_transaction(raw) } ``` ### Connect to a node ``` use layerx_sdk::rpc::{RpcClient, RpcError}; fn connect(endpoint: &str) -> Result { RpcClient::connect_node(endpoint, None) } ``` The Rust committed-wait example uses a caller-supplied receipt policy. Configure the client with a runtime clock and independently pinned node consensus authority before waiting for committed inclusion. ### Verify committed inclusion (Rust) ``` use std::time::Duration; use layerx_sdk::rpc::{Commitment, RpcClient, RpcError}; use layerx_sdk::rpc_verification::{ReceiptPolicy, VerifiedRpcReceipt}; fn wait_for_commit( rpc: &RpcClient, transaction_hash: [u8; 32], policy: &ReceiptPolicy, ) -> Result { rpc.wait_for(transaction_hash, Commitment::Committed, policy, Duration::from_secs(30)) } ``` ## TypeScript Use `JsonRpcClient` for node reads and signed EVM transaction submission. `ProductionClient` provides Human operations through a configured Human transport. Registration and faucet calls use the hosted gateway contract. ### Connect and submit a transaction ``` import { JsonRpcClient } from "@sidiora/layerx-sdk"; export function openNode(endpoint: string): JsonRpcClient { return new JsonRpcClient(endpoint); } export function send(rpc: JsonRpcClient, signedTransaction: Uint8Array): Promise { return rpc.sendRawTransaction(signedTransaction); } ``` ### Quote and commit a Human payment ``` import { ProductionClient, idempotencyKey } from "@sidiora/layerx-sdk"; type MoveRequest = { source: string; destination: string; money: { amount: string; currency: string }; }; export async function pay( client: ProductionClient, request: MoveRequest, paymentKey: string, ): Promise> { const quote = await client.human("move.quote", request); return client.human<{ quote_id: string }, Record>( "move.commit", { quote_id: quote.quote_id }, { idempotencyKey: idempotencyKey(paymentKey) }, ); } ``` ### Verify canonical receipt bytes ``` import { verifySequencerReceipt } from "@sidiora/layerx-sdk"; import type { SequencerReceiptKey, SequencerReceiptVerification } from "@sidiora/layerx-sdk"; export function verify( signedReceipt: Uint8Array, rawTransaction: Uint8Array, receiptKeys: readonly SequencerReceiptKey[], ): Promise { return verifySequencerReceipt(signedReceipt, rawTransaction, receiptKeys); } ``` ## Python `PaymentRpc` sends node methods at the root path `/`. The hosted gateway client handles registration and faucet methods at its configured service endpoint. Registration takes lowercase hexadecimal keys and signatures; funding requires a Bearer identity session. ### Hosted registration ``` from layerx_sdk.x402_rpc import HostedGatewayRpc def register(rpc: HostedGatewayRpc, signer_public_key: str, registration_signature: str) -> dict: result = rpc.call("px_register", [signer_public_key, registration_signature]) if not isinstance(result, dict): raise ValueError("Invalid registration response") return result ``` ### Authenticated funding ``` from layerx_sdk.x402_rpc import HostedGatewayRpc def request_funds(gateway_endpoint: str, session_token: str, did: str, signer_public_key: str) -> dict: rpc = HostedGatewayRpc(gateway_endpoint, {"Authorization": f"Bearer {session_token}"}) result = rpc.call("px_requestFunds", [did, signer_public_key]) if not isinstance(result, dict): raise ValueError("Invalid funding response") return result ``` ### Submit a signed EVM transaction ``` from layerx_sdk import PaymentRpc def send(rpc: PaymentRpc, raw_transaction: str) -> str: return rpc.send(raw_transaction) ``` ### Quote and commit a Human payment ``` from layerx_sdk import IdempotencyKey, ProductionClient def pay(layerx: ProductionClient, source, destination, money, payment_key): quote = layerx.human("move.quote", {"source": source, "destination": destination, "money": money}) return layerx.human("move.commit", {"quote_id": quote["quote_id"]}, idempotency_key=IdempotencyKey(payment_key)) ``` ### Verify canonical receipt bytes ``` from layerx_sdk import ReceiptKey, SequencerReceiptVerification, verify_sequencer_receipt def verify( signed_receipt: bytes, raw_transaction: bytes, receipt_keys: tuple[ReceiptKey, ...], ) -> SequencerReceiptVerification: return verify_sequencer_receipt(signed_receipt, raw_transaction, receipt_keys) ``` ## Go Use `NewHumanHTTPTransport` and `Client.Human` for a quote followed by an idempotent commit. The Go package is in sdk/platform/go; its import path is declared by that directory's go.mod. ### Quote and commit a Human payment ``` package main import ( "context" "net/http" layerx "github.com/Sidiora-Labs/LayerX-Network/sdk/platform/go" ) type Money struct { Amount string `json:"amount"` Currency string `json:"currency"` } type MoveQuoteRequest struct { Source string `json:"source"` Destination string `json:"destination"` Money Money `json:"money"` } type MoveQuote struct { QuoteID string `json:"quote_id"` } type MoveCommitRequest struct { QuoteID string `json:"quote_id"` } type Journey struct { JourneyID string `json:"journey_id"` State string `json:"state"` } func pay(ctx context.Context, apiURL, apiToken, source, destination, paymentKey string, money Money) (Journey, error) { authorize := func(request *http.Request) error { request.Header.Set("Authorization", "Bearer "+apiToken) return nil } transport, err := layerx.NewHumanHTTPTransport(apiURL, nil, authorize) if err != nil { return Journey{}, err } client, err := layerx.NewClient(transport, nil) if err != nil { return Journey{}, err } key, err := layerx.NewIdempotencyKey(paymentKey) if err != nil { return Journey{}, err } var quote MoveQuote if err := client.Human(ctx, layerx.HumanOperationMoveQuote, MoveQuoteRequest{Source: source, Destination: destination, Money: money}, "e, layerx.CallOptions{}); err != nil { return Journey{}, err } var journey Journey if err := client.Human(ctx, layerx.HumanOperationMoveCommit, MoveCommitRequest{QuoteID: quote.QuoteID}, &journey, layerx.CallOptions{IdempotencyKey: key}); err != nil { return Journey{}, err } return journey, nil } ``` ### Verify the JSON receipt view ``` package main import layerx "github.com/Sidiora-Labs/LayerX-Network/sdk/platform/go" func verify(receiptJSON, rawTransaction []byte, keys layerx.ReceiptKeys) (layerx.SequencerReceiptVerification, error) { return layerx.VerifySequencerReceipt(receiptJSON, rawTransaction, keys) } ``` ## JVM Configure `HttpProductionTransport` with the Human and agent origins. Human payments use `ProductionClient.human` and typed options. The JVM SDK source is in sdk/platform/jvm. ### Quote and commit a Human payment ``` import com.fasterxml.jackson.databind.JsonNode; import com.sidiora.layerx.sdk.HttpProductionTransport; import com.sidiora.layerx.sdk.IdempotencyKey; import com.sidiora.layerx.sdk.ProductionClient; import com.sidiora.layerx.sdk.SecretBytes; import java.net.URI; import java.nio.charset.StandardCharsets; import java.util.Map; public final class Pay { public static JsonNode pay( String humanOrigin, String agentOrigin, String apiToken, String source, String destination, Map money, String paymentKey ) { var credential = new HttpProductionTransport.BearerCredential( new SecretBytes(apiToken.getBytes(StandardCharsets.UTF_8))); var layerx = new ProductionClient( HttpProductionTransport.create(URI.create(humanOrigin), URI.create(agentOrigin), credential)); var quote = layerx.human( "move.quote", Map.of("source", source, "destination", destination, "money", money), JsonNode.class, ProductionClient.Options.none()).toCompletableFuture().join(); return layerx.human( "move.commit", Map.of("quote_id", quote.path("quote_id").asText()), JsonNode.class, ProductionClient.Options.idempotent(new IdempotencyKey(paymentKey))) .toCompletableFuture().join(); } private Pay() {} } ``` ### Verify bytes and JSON execution evidence ``` import com.fasterxml.jackson.databind.JsonNode; import com.sidiora.layerx.sdk.verify.LocalVerifier; import com.sidiora.layerx.sdk.verify.LocalVerifier.ReceiptKeys; import com.sidiora.layerx.sdk.verify.LocalVerifier.SequencerReceiptVerification; public final class Verify { public static SequencerReceiptVerification verify( byte[] receiptBytes, byte[] rawTransaction, ReceiptKeys keys, JsonNode receiptJSON, byte[] previousSequenceHash ) { return LocalVerifier.verifySequencerReceipt( receiptBytes, rawTransaction, keys, receiptJSON, previousSequenceHash); } private Verify() {} } ``` ## Swift Use `PlatformClient` with `HumanHTTPTransport` for a payment quote and commit. Access tokens and idempotency keys use dedicated types. The Swift package is in sdk/platform/swift. ### Quote and commit a Human payment ``` import Foundation import LayerXSDK func pay( serviceURL: URL, apiToken: String, source: String, destination: String, money: JSONValue, paymentKey: IdempotencyKey ) async throws -> JSONValue { let token = try AccessToken(Data(apiToken.utf8)) let layerx = PlatformClient(transport: try HumanHTTPTransport(baseURL: serviceURL, accessToken: token)) let quote = try await layerx.humanMoveQuote(.object([ "source": .string(source), "destination": .string(destination), "money": money, ])) guard let quoteID = quote.objectValue?["quote_id"]?.stringValue else { throw PlatformSDKError(code: .invalidArgument, retry: .never) } return try await layerx.humanMoveCommit(.object(["quote_id": .string(quoteID)]), idempotencyKey: paymentKey) } ``` ### Verify bytes and JSON execution evidence ``` import Foundation import LayerXSDK func verify(receiptBytes: Data, rawTransaction: Data, keys: [ReceiptKeys], receiptJSON: [String: JSONValue], prevSeqHash: Data) throws -> SequencerReceiptVerification { try LocalVerifier.verifySequencerReceipt(receiptBytes, rawTransaction: rawTransaction, keys: keys, receiptJSON: receiptJSON, prevSeqHash: prevSeqHash) } ``` ## .NET Use `PlatformClient` with `HumanHttpTransport`, `AccessToken`, and `IdempotencyKey` for the Human payment flow. The .NET project is in sdk/platform/dotnet. ### Quote and commit a Human payment ``` using System; using System.Collections.Generic; using System.Text; using System.Threading.Tasks; using LayerX.Sdk; static async Task Pay( Uri apiUrl, string apiToken, string source, string destination, JsonValue money, string paymentKey) { using var token = new AccessToken(Encoding.UTF8.GetBytes(apiToken)); var layerx = new PlatformClient(new HumanHttpTransport(apiUrl, accessToken: token)); var quote = await layerx.HumanMoveQuoteAsync(JsonValue.Object(new Dictionary { ["source"] = JsonValue.String(source), ["destination"] = JsonValue.String(destination), ["money"] = money, })); if (quote is not JsonValue.ObjectValue record || !record.Value.TryGetValue("quote_id", out var value) || value is not JsonValue.StringValue quoteId) throw new InvalidOperationException("Invalid quote response"); return await layerx.HumanMoveCommitAsync( JsonValue.Object(new Dictionary { ["quote_id"] = JsonValue.String(quoteId.Value) }), new IdempotencyKey(paymentKey)); } ``` ### Verify the JSON receipt view ``` using System; using LayerX.Sdk; static SequencerReceiptVerification Verify( ReadOnlyMemory receiptJSON, ReadOnlyMemory rawTransaction, ReceiptKeys keys) => LocalVerifier.VerifySequencerReceipt(receiptJSON, rawTransaction, keys); ``` ## Verify sequencer receipts against trusted keys Receipt verifiers check the signed receipt, raw transaction hash, and independently trusted receipt-key identifiers, public keys, and height ranges. TypeScript and Python take canonical receipt bytes; Go and .NET take the JSON receipt view. The JVM and Swift examples take canonical bytes, the JSON view, and authenticated previous-sequence context. A receipt signature proves execution under that key; committed finality additionally requires authenticated block inclusion and consensus evidence. The TypeScript `Commitment` type is `"submitted" | "receipted" | "committed"`. The node reports progress as `submitted`, `receipted`, or `committed`. Verify signatures at the `receipted` stage and consensus inclusion for `committed`. Rust exposes its committed wait through a separate typed policy API. ## Program execution evidence A program call returns execution status, return data, and event evidence committed by its transaction receipt. Verify those receipt commitments and the expected program outcome before acting on a result. Receipt verification uses language-specific APIs: TypeScript `verifySequencerReceipt`, Python `verify_sequencer_receipt`, Go `VerifySequencerReceipt`, JVM `LocalVerifier.verifySequencerReceipt`, .NET `LocalVerifier.VerifySequencerReceipt`, and Swift `LocalVerifier.verifySequencerReceipt`. The JVM Programs client additionally exposes `ProgramsClient.verifyTerminalV5` for terminal evidence. Supply the trust inputs required by the selected API. Continue with [XDK API families](https://docs.paxeer.app/xdk), [Programs](https://docs.paxeer.app/programs), and [MCP tools](https://docs.paxeer.app/mcp). --- URL: https://docs.paxeer.app/sdk # Cosmos SDK Fork Paxeer X’s in-tree Cosmos SDK fork with Paxeer X-specific modifications and extensions. **Source:** `sdk/` ## Choose the right development surface The in-tree Cosmos SDK powers `paxd` and native chain modules. The [XDK](https://docs.paxeer.app/xdk) provides application clients for node transactions, receipts, identity, and native precompiles. The [platform API](https://docs.paxeer.app/platform-api) connects paid resources, merchant checkout, agent spending, receipts, and webhooks. Chain maintainers work in `sdk/`, `modules/`, and `node/`. Application developers use `services/agent/sdk/` (TypeScript, Python), `services/agent/crates/layerx-sdk` (Rust), `sdk/platform/` (Go, JVM, Swift, .NET), and `sdk/wallet`. `docs/system/sdk.md` indexes exported SDK symbols and their source paths. ### Cross-surface application lifecycle 1. Resolve the account identity and select the native asset denomination or ERC-20 pointer. 2. Use the matching client or native ABI to submit a signed transaction for the intended operation. 3. Track the transaction hash, execution receipt, and covering committed block. 4. Verify receipt signatures and committed inclusion before treating a payment as final. The [network overview](https://docs.paxeer.app/unified-network) explains how these execution surfaces compose. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. An execution receipt becomes final when validators commit its covering block. ## Overview Paxeer X vendors a fork of the Cosmos SDK directly in the monorepo under `sdk/`. These packages are **part of** the root Go module. It is an in-tree dependency for the `paxd` binary and Paxeer chain modules. ### Fork capabilities Paxeer X maintains a fork to support: - Custom storage engines - EVM integration and pointer contracts - Chain-specific module and precompile integration - Paxeer X-specific consensus and execution optimizations - Co-location with Paxeer modules and WASM runtime ## Upstream Base The fork includes its own application framework, stores, account types, and module implementations. Its imports resolve through the root Go module. **Warning:** Do not assume drop-in compatibility with standard Cosmos SDK tooling or libraries. Paxeer X’s SDK is a custom fork. ## Directory Structure | Path | Purpose | | --- | --- | | `baseapp/` | Application framework (ABCI, routing, ante handlers) | | `client/` | CLI framework and transaction builders | | `server/` | Node server, gRPC, REST gateway | | `types/` | Core SDK types (messages, coins, errors, context) | | `x/` | Standard Cosmos modules (bank, auth, staking, gov, etc.) | | `proto/` | Protobuf definitions for SDK modules | | `store/` | State store abstraction and implementations | | `storev2/`, `codec/`, `crypto/` | Store v2, codec, and cryptography support | | `platform/`, `wallet/`, `js/` | Platform language SDKs, wallet SDK, and the first-party @pax-js/cosmos package | ## Key Modules Paxeer X’s SDK includes standard Cosmos modules: | Module | Purpose | | --- | --- | | `x/auth` | Account authentication and transaction signing | | `x/bank` | Token transfers and balance management | | `x/staking` | Proof-of-Stake validator set and delegation | | `x/distribution` | Staking rewards and fee distribution | | `x/gov` | On-chain governance and proposals | | `x/slashing` | Validator penalties for misbehavior | | `x/authz`, `x/feegrant` | Authorization grants and fee grants | | `x/capability`, `x/genutil`, `x/simulation` | Capability keeper, genesis utilities, and simulation | | `x/evidence` | Double-sign evidence submission | | `x/params` | Module parameter management | | `x/upgrade` | Coordinated chain upgrades | Chain module source directories under `modules/`: - `evm` — EVM execution and JSON-RPC - `epoch` — Epoch tracking - `oracle`, `pricefeed` — Price feeds - `tokenfactory` — Custom token creation - `mint` — Token minting - `launchpad`, `spot`, `perps`, `sequencer`, `store`, `xweb`, `lxphost` - `layerxagent`, `layerxanchor`, `layerxauth`, `layerxbridge`, `layerxchains`, `layerxcustody`, `layerxexchange`, `layerxgov`, `layerxledger`, `layerxpay` - Anchor — writes retire at the v7.0 upgrade height and bonds return to their owners; archive reads remain until the separate anchor-store deletion plan. - Custody — calls retire at the v7.0 upgrade height; remaining balances move to the custody authority and pending claims are cancelled. ## BaseApp The core application framework (`baseapp/`) handles: - ABCI interface to Tendermint consensus - Message routing to module handlers - Ante handlers (gas, signatures, nonces) - Transaction execution and state commits - Query routing Paxeer extends BaseApp for EVM transaction routing and concurrent execution (OCC). ## Client & Server The SDK provides: - **CLI:** `paxd` command-line interface (transaction builders, queries) - **gRPC:** Module query and transaction services - **REST:** HTTP gateway (gRPC-Gateway) - **Tendermint RPC:** Block and transaction queries See [REST & gRPC](https://docs.paxeer.app/rest-grpc) for API documentation. ## State Store The SDK's `sdk/store/` abstraction is implemented by Paxeer X’s custom storage engines. The engine implementations live under `storage/`: - Database engines under `storage/db_engine/`: `litt`, `pebbledb`, `rocksdb`, and `dbcache`. See [Storage](https://docs.paxeer.app/storage) for engine details. ## Protobuf Definitions SDK types are defined in `sdk/proto/`. Regenerate Go code with: ``` # From the repository root bash scripts/protoc.sh ``` The script builds the pinned `protoc-gen-gocosmos` plugin and runs `buf generate` via `go run github.com/bufbuild/buf/cmd/buf@v1.58.0`. See `api/README.md`. ## Building Against the SDK Paxeer modules import the SDK from the in-tree path: ``` import ( sdk "github.com/Sidiora-Labs/Paxeer-X-Network/sdk/types" "github.com/Sidiora-Labs/Paxeer-X-Network/sdk/store" ) ``` There is no `sdk/go.mod`: the SDK packages belong to the single root module `github.com/Sidiora-Labs/Paxeer-X-Network`, so no replacement directives are needed. ## Makefile Targets The repository Makefile includes SDK-related targets: ``` # Build paxd from the unified repository root make paxeer-build # Run the chain tests make paxeer-test ``` ## Documentation Use `docs/system/sdk.md` for exported SDK symbols and source paths. The first-party @pax-js/cosmos package in `sdk/js` is edited in place and aligned to the protos of this repository. ### Upstream Resources - [Cosmos SDK Docs](https://docs.cosmos.network/) (upstream, may diverge from Paxeer) - [Cosmos Tutorials](https://tutorials.cosmos.network/) (upstream concepts apply) - [GoDoc](https://pkg.go.dev/github.com/cosmos/cosmos-sdk) (upstream SDK, not Paxeer X’s fork) **Warning:** Upstream documentation describes the standard Cosmos SDK, not Paxeer X’s fork. Treat it as reference only. ## Contributing to the Fork Changes to `sdk/` affect the entire Paxeer chain. Test thoroughly: 1. Edit code under `sdk/` 2. Rebuild `paxd`: `make paxeer-build` 3. Run chain tests: `make paxeer-test` 4. Test with [Docker cluster](https://docs.paxeer.app/docker): `make docker-cluster-start` 5. Run Human service integration tests: `make human-test-integration` ## Differences from Upstream Cosmos SDK Paxeer X’s SDK fork diverges from upstream in several areas: - Custom storage backends - EVM module integration and pointer contracts - Optimistic concurrency control (OCC) for parallel execution - Receipt indexing and synthetic transactions - Paxeer X-specific ante handlers and gas metering - Chain-specific upgrade logic Do not assume compatibility with standard Cosmos SDK tooling (e.g., CosmJS, Keplr) without testing. ## Go Module Path ``` github.com/Sidiora-Labs/Paxeer-X-Network ``` There is no separate SDK module. Paths such as `github.com/Sidiora-Labs/Paxeer-X-Network/sdk/types` are package paths inside the single root module, not a standalone published module. --- URL: https://docs.paxeer.app/security # Security and trust boundaries Verify signed execution receipts from the LayerX kernel inside paxd and the blocks it builds that validators check and commit. The LayerX kernel runs inside every paxd node, executes each transaction when it arrives, gives it the next position in one global sequence, returns a signed execution receipt and builds each block; validators check that block and commit it. A transaction is final when its covering block is committed. A signed execution receipt establishes a narrower claim before commitment. Applications verify the evidence needed before releasing goods or updating balances. ## The trust boundaries | Boundary | Verification responsibility | Remaining dependency | | --- | --- | --- | | Signer to node | Signed transaction, chain identifier, nonce, gas, and balance checks. | Key custody and correct transaction construction. | | Node to client | Canonical receipt, authorized receipt key, raw transaction hash, and execution status. | Receipt-key trust and node availability. | | Proposer to validators | Sequence-batch signature, sequence continuity, and transaction replay. | Consensus validator set and deterministic execution. | | Block to application | Transaction inclusion and consensus commit under a trusted validator set. | Authenticated chain and validator-set trust. | | Application to hosted service | Authenticated request, scoped authorization, and evidence for the resulting operation. | Service availability and credential custody. | ## Evidence levels are consequential A submission response identifies a transaction. A signed receipt authenticates execution under a pinned receipt key. A covering block and verified consensus commit establish committed inclusion. Applications retain the signed transaction and check its hash, receipt outcome, and block evidence together. Native balances and EVM execution belong to the same network. Receipt signatures authenticate the signer and payload; consensus commitment establishes finality. Neither service authentication nor a matching chain identifier proves a payment. ## Canonical execution and replay The node validates the ordered sequence batch and re-executes proposed transactions. Sequence continuity, signatures, and committed roots bind the execution order. Query indexes expose derived views and do not replace consensus evidence. Program monetary effects pass through protocol transfer sets and the asset module. Storage occupancy is accounted for during deterministic execution. Applications check the resulting execution status and transfer evidence before treating a program call as successful. ## Verify receipt authority The node exposes signed execution receipts bound to the raw EVM transaction hash. Clients authenticate the signing key against independently trusted key identifiers, public keys, and valid height ranges, then check the canonical receipt and execution outputs. ### Trusted receipt keys Receipt-key entries come from `px_getReceiptKeys`. Their key identifiers, public keys, and inclusive height ranges describe the governed receipt-signing authority. Establish trust in that key list independently of the receipt response. 1. Start with the exact signed transaction and its hash on the intended network. 2. Retrieve its canonical receipt and authenticate the signing key for the receipt height. 3. Check the signature, transaction binding, execution status, and expected payment or program effect. 4. Authenticate committed block inclusion before treating the transaction as final. A signature over another transaction does not establish the requested payment. A root or signing key copied from an untrusted response does not authenticate execution or consensus membership. ### Refusals and retry behavior Authentication failures, unknown transactions, execution refusals, and unavailable dependencies have different meanings. Confirm the identifier when a transaction is unknown, inspect the execution outcome when it is refused, and retain the original transaction when transport failure leaves its outcome uncertain. A liveness or readiness response reports service availability. It does not certify a transaction, establish receipt-key authority, or prove a block commit. ## Keys, roles, and custody Owner keys, identity sessions, scoped gateway keys, capabilities, and budgets carry distinct authority. Grant only the operations, assets, amounts, and lifetime the application needs. Check revocation and current authorization before signing. Validator governance and receipt-key governance serve different verification roles. The `modules/sequencer` module stores the leader list, receipt keys, and committed sequence position. See [consensus and signing roles](https://docs.paxeer.app/guarantors) when selecting the trust inputs for receipt verification. ## Emergency response and upgrade control Upgrade controls follow the specific chain or contract authority. Contract timelocks restrict permitted calls, role assignments, delays, and execution windows. Applications inspect those deployed parameters rather than inferring authority from a service response. During an outage, preserve signed transactions, receipts, and block inclusion evidence. Resume lookup using the original transaction hash and establish its outcome before authorizing another economic action. ## Integration review - Pin the chain, validator set, and receipt-key authority. - Reject noncanonical encodings and evidence bound to another transaction or sequence. - Keep retries idempotent and retain the original transaction hash. - Distinguish submission, authenticated execution, and committed inclusion. - Inspect current role assignments, thresholds, delays, and limits when evaluating contract authority. Continue with [verification roles](https://docs.paxeer.app/guarantors), [Governance](https://docs.paxeer.app/governance), and [Finality](https://docs.paxeer.app/finality). --- URL: https://docs.paxeer.app/sequencing # Sequencing & Finality Follow a signed transaction through ordered execution, receipt verification, and BFT block commitment. On Paxeer mainnet-beta, the LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it, and the committed chain records the resulting order. A signed receipt can be available before its covering block is committed. The proposer places `MsgSequenceBatch` at transaction index zero of each block at or above the sequencing activation height. Validators verify that batch and re-execute its transactions. See [block commitment](https://docs.paxeer.app/checkpoints) for the evidence boundary. ## Global ordering and sequence batches A nonempty batch starts at the stored last sequence plus one and binds the preceding sequence hash. The keeper rejects a discontinuity, an invalid receipt-key signature, a mismatched height, or a second sequence batch in one block. EVM account nonces separately enforce sender ordering. | Batch commitment | Fields | | --- | --- | | Block height | `Height`, `FromSeq`, `ToSeq` | | Sequence continuity | `PrevSeqHash`, `LastSeqHash`, `TxRoot` | | Receipt-key authority | `KeyId`, `Sig` | | Hash widths | `PrevSeqHash`, `LastSeqHash`, `TxRoot` are each 32 bytes. | | Key and signature widths | `KeyId` is 32 bytes; `Sig` is a 64-byte Ed25519 signature. | | Canonical encoding | The domain prefix is followed by big-endian positions, hashes, key ID, and signature; `Height` names the covering block. | The canonical sequence-batch transaction is 241 bytes, including its domain prefix and signature. For an empty batch, `ToSeq` equals `FromSeq` minus one, the sequence hash is unchanged, and the transaction root is SHA-256 of the empty input. ## Evidence stages | Level | Evidence | Responsibility | | --- | --- | --- | | Submitted | The node holds the transaction without a signed receipt. | Track its transaction hash. | | Receipted | A signed receipt binds the raw transaction to its execution outcome. | Authenticate the receipt key and check the outcome. | | Committed | A committed block covers the receipt sequence. | Verify block inclusion and the consensus commit. | A `submitted` result carries no execution receipt. A `receipted` result authenticates execution when verified under a trusted receipt key. Finality is established when the covering block is committed by BFT consensus. ## Replay 1. Retrieve the exact signed transaction and its canonical execution receipt. 2. Authenticate the receipt signature using a trusted key with a height range covering the receipt. 3. Check the sequence-batch signature, transaction order, and sequence-hash continuity. 4. Authenticate the covering block and its consensus commit before accepting committed inclusion. A failed replay or sequence check rejects the proposal. Consensus execution uses the ordered transaction input and block context so validators can reproduce the transition before committing it. ## Public receipt states The node receipt API reports `submitted`, `receipted`, and `committed`. These values describe transaction progress; applications verify the evidence behind the reported value. | Receipt state | Required evidence | | --- | --- | | `submitted` | Transaction hash, nonce, and progress state. | | `receipted` | Canonical signed receipt, authenticated signing key, and matching execution view. | | `committed` | Receipt evidence plus the covering block number and block hash; independent finality verification authenticates inclusion and the consensus commit. | Retrieve transaction progress with `pax_sequencerReceipt`. Preserve the original signed transaction and obtain `px_getSequenceBatch` and `px_getCommit` evidence for independent committed inclusion checks. A transaction hash or successful HTTP response alone is not a receipt. The final rung is `committed`. ## Data availability and recovery Committed inclusion verification requires the exact transaction, receipt, covering sequence batch, block inclusion path, consensus commit, and a trusted validator set. A root without authenticated reconstruction and inclusion evidence is insufficient. Node recovery restores committed sequence state from the module store. The proposer executor also keeps a write-ahead log of accepted transactions and sealed blocks so recovery can reconcile uncommitted execution with the committed head. ### Proposal validation The signed sequence batch binds its height, ordered range, transaction root, and sequence hashes. Validators check the proposer against the governed leader schedule and reject inconsistent sequence or replay results. ## Execution in one network Transfers, program calls, service operations, and market operations execute within the same network. Applications inspect the operation result and affected account state in addition to its transaction position. If consensus cannot commit a block, an available execution receipt remains evidence of signed execution. Clients retain that receipt and wait for authenticated committed inclusion before treating its effects as final. ## Continue reading - [Deterministic kernel execution](https://docs.paxeer.app/layerx-kernel) - [Block commitment](https://docs.paxeer.app/checkpoints) - [Data availability and reconstruction](https://docs.paxeer.app/data-availability) - [Deposits, withdrawals, and exits](https://docs.paxeer.app/bridge) - [Receipt and proof verification](https://docs.paxeer.app/receipts) - [Paxeer consensus](https://docs.paxeer.app/consensus) --- URL: https://docs.paxeer.app/services # Services and agreements Publish paid capabilities, agree on deliverables, attest execution, and resolve delivery through the Paxeer X service lifecycle. Paxeer X turns a service into a verifiable agreement between a provider and a customer. An offer defines price, Asset, terms, deliverable specification, deadlines, and acceptance policy. Agreements bind those terms to an escrow; commitments and execution attestations establish the work performed; delivery records bind the resulting artifacts to their availability references. ## Choose a service model | Model | Use it for | Completion evidence | | --- | --- | --- | | Deliverable agreement | Research, generated assets, analysis, computation, and agent tasks. | Commitments, signed tool execution, delivery hashes, acceptance or dispute ruling. | | Paid API | Immediate access to a query result, data resource, or tool endpoint. | Verified payment receipt and a durable fulfillment record. | | Receipt-gated resource | A single paid HTTP request for a resource or tool result. | A signed transaction receipt bound to the requested payment. | Use the service module for negotiated work with delivery and acceptance. Use [paid API middleware](https://docs.paxeer.app/paid-apis) for an HTTP resource that releases its response after receipt verification. The service module records agreement state; payment operations resolve its linked escrow. Paid HTTP resources verify the payment transaction receipt before fulfillment. ## Register and discover an offer Publish an offer with `LX_SERVICE_OFFER_PUBLISH`. Give customers the offer identifier and a human-readable description of its terms and deliverable specification. Content hashes commit to the exact documents; host the documents and artifacts where the customer can retrieve and verify them. Discovery identifies a suitable offer; the customer checks its Asset, price, expiry, and policy before proposing an agreement. | Offer field | Meaning | | --- | --- | | `offer_id`, `asset_id`, `price` | Nonzero offer identity, payment Asset identity, and positive integer price. | | `terms_hash` | Commitment to the terms the customer accepts. | | `deliverable_specification_hash` | Commitment to the expected result. | | `delivery_deadline`, `offer_expiry` | Delivery deadline and offer expiry in milliseconds, checked against batch time. | | `acceptance_window`, `dispute_window` | Nonzero durations in milliseconds: review ends at the delivery deadline plus the acceptance window; the dispute window follows. | | `default_outcome` | `1` accepts or `2` rejects when the review policy applies. | Withdraw an offer with `LX_SERVICE_OFFER_WITHDRAW`. An unavailable offer or mismatched terms prevents a new agreement from proceeding. ## From offer to invocation 1. Read the offer and verify the terms and deliverable documents against their hashes. 2. Prepare payment escrow through the payment lifecycle and retain its identifier. 3. Propose an agreement with `agreement_id`, `offer_id`, `terms_hash`, and `escrow_id` using `LX_SERVICE_AGREEMENT_PROPOSE`. 4. The provider accepts with `LX_SERVICE_AGREEMENT_ACCEPT`. 5. Commit a task using `LX_SERVICE_COMMIT_TASK`, binding its task hash, escrow, positive deadline, and resource bound. 6. Execute the agreed capability, publish signed execution attestations, and report progress. 7. Deliver artifacts for customer acceptance; resolve escrow through the payment lifecycle. ### Commitments and execution attestations A task commitment records `commitment_id`, `agreement_id`, `task_hash`, `escrow_id`, `deadline`, and `resource_bound`. An abandoned commitment carries an explicit reason through `LX_SERVICE_COMMIT_ABANDON`. `LX_SERVICE_TOOL_EXEC_ATTEST` records the tool identifier, input and output commitments, execution window, resource units, attestor identity, availability reference, public key, and signature. Verification checks the attestor; invalid signatures or execution evidence are refused as `LXP_ERR_INVALID_ATTESTATION`. `LX_SERVICE_PROGRESS_REPORT` binds a report and note hash to a commitment and availability reference. Progress is an integer from `1` through `10000` basis points. Each report must strictly increase the previous progress value. ## Deliver and review `LX_SERVICE_DELIVER` carries one to sixteen artifacts. Each item contains a hash, a positive byte size, and a nonzero availability reference; a zero size or zero availability reference is refused as non-canonical. Every deliverable hash must equal the offer's `deliverable_specification_hash`, and delivery must arrive by the agreement deadline. Delivery is accepted from the committed state and again from the rejected state, which permits redelivery after rejection. Retain the bytes corresponding to every declared hash so the customer can verify the result. ``` version:u16be (00 01) || delivery_id32 || agreement_id32 || count:u8 || { hash32 || artifact_size:u64be || availability_reference32 } × count ``` The customer accepts with `LX_SERVICE_ACCEPT` or rejects using `LX_SERVICE_REJECT`, a rejection reason, and contested hashes. Protocol batch maintenance applies the agreement's default review policy when the acceptance window ends. ### Disputes and resolution `LX_SERVICE_DISPUTE_OPEN` binds a dispute identifier and evidence hashes to the agreement. The agreement must be in the rejected state, the raiser must be the provider or the buyer, the escrow link must match the agreement, and the escrow must name a nonzero arbiter (`LXP_ERR_ARBITER_REQUIRED`); the dispute must open within its window. `LX_SERVICE_DISPUTE_RESOLVE` must come from that escrow arbiter (`LXP_ERR_UNAUTHORIZED_ARBITER` for any other caller) and supplies a nonzero ruling, the provider's allocation in basis points, and the escrow resolution identifier. Allocation ranges from zero to `10000`. ## Activity reference The service module ID is `5`; payload version is `1`, encoded by the prefix bytes `00 01` for all activities except tool execution attestations. That activity uses the 416-byte execution record directly. Identifiers and hashes are 32 bytes. The codecs are in include/layerx/lx_service.h and src/modules/service/lx_service_payload.c. | Activity | Type | Canonical payload bytes | | --- | --- | --- | | Offer publish / withdraw | `0x00050001 / 0x00050002` | 179 / 34 | | Agreement propose / accept | `0x00050003 / 0x00050004` | 130 / 34 | | Task commit / abandon | `0x00050005 / 0x00050006` | 146 / 36 | | Tool execution attest / progress | `0x00050007 / 0x00050008` | 416 / 134 | | Deliver / accept | `0x00050009 / 0x0005000a` | 67 + 72 per item / 34 | | Reject / dispute open | `0x0005000b / 0x0005000c` | 37 + 32 per hash / 67 + 32 per hash | | Dispute resolve | `0x0005000d` | 72 | ## Handle refusals and retries Preserve the agreement, commitment, activity, and escrow identifiers across retries. Check status before resubmission after a timeout. Sequence reuse, unauthorized debit, unavailable offers, terms mismatch, and invalid agreement state are distinct refusals; changing payment identity to escape uncertainty can create a second economic action. Delivery errors distinguish `LXP_ERR_DELIVERABLE_MISMATCH` (a hash that does not equal the specification hash), non-canonical zero sizes or availability references, and `LXP_ERR_DELIVERY_DEADLINE_PASSED`. Dispute errors distinguish an unauthorized actor from a closed window. Correct the refused condition before submitting a new action. ## Continue building Connect immediate resource access with [paid APIs and x402](https://docs.paxeer.app/paid-apis), explore [SDK integrations](https://docs.paxeer.app/sdk), and inspect the [protocol modules](https://docs.paxeer.app/modules). --- URL: https://docs.paxeer.app/settlement # Settlement & committed evidence Verify signed execution, transaction inclusion, and committed block evidence on Paxeer X. ## Execution and settlement form one history Paxeer mainnet-beta has EVM chain ID `125`. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. Receipts are final once validators commit their covering block. Payments, program calls, transfers, and storage charges participate in the chain execution history. | Level | Evidence | Meaning | | --- | --- | --- | | Submission | Transaction hash | The node has accepted a transaction for processing. | | Signed execution | Canonical execution receipt | The receipt binds the transaction to its execution outcome. | | Outcome verification | Receipt and execution outputs | The authenticated result matches the intended payment or program operation. | | Block coverage | Sequence batch and transaction inclusion | The transaction is included in the identified block and ordered sequence. | | Commitment | BFT consensus commit | The covering block is committed under the trusted validator set. | A signed receipt authenticates an execution claim under a receipt key. To establish finality independently, authenticate the covering block, the transaction and sequence-batch inclusion evidence, and the BFT commit under a trusted validator set. ## Node receipt and consensus reads The node provides `pax_sequencerReceipt` for execution progress and `px_getCommit` for consensus evidence. The receipt response binds the transaction hash to its signed receipt and, when committed, identifies the covering block. | Method | Purpose | | --- | --- | | `eth_sendRawTransaction(raw)` | Submit a signed EVM transaction and obtain its hash. | | `pax_sequencerReceipt(txHash)` | Read submitted, receipted, or committed progress and execution evidence. | | `eth_getTransactionReceipt(txHash)` | Read the EVM execution receipt. | | `px_getCommit(height)`, `px_getValidators(height)` | Acquire the signed consensus header and validator information. | | `eth_getBlockByNumber(height, false)`, `eth_getTransactionByHash(txHash)` | Acquire block and transaction data for reconciliation. | | `px_getSequenceBatch(height)` | Acquire the canonical sequence-batch transaction and its block inclusion proof. | | `px_getReceiptKeys()` | Acquire governed receipt-key identifiers, public keys, and valid height ranges. | The receipt rungs are `submitted`, `receipted`, and `committed`. Verify the evidence behind the reported rung. The response contract is implemented in `rpc/sequencer_receipt.go`. ## Sequence-batch coverage Each sequenced block begins with `MsgSequenceBatch`. Retrieve its canonical transaction, activity identifiers, and block inclusion proof with `px_getSequenceBatch(height)`. Obtain the corresponding consensus header and commit with `px_getCommit(height)`. | Item | Contents | Commitment | | --- | --- | --- | | Ordered activity commitment | The batch binds fixed-width activity identifiers in their execution order. | `SHA256(activity_id32 \|\| ...)`, stored in the batch TxRoot field. | The batch commits to the ordered activity identifiers and sequence hashes. Use `px_getValidators(height)` to acquire validator data and `px_getReceiptKeys` for receipt-key data, authenticating both against independently trusted chain state. ### Receipt and consensus signing roles Receipt-signing keys authenticate execution receipts and sequence batches within their governed height ranges. Consensus validator keys authenticate block commits. A receipt signature alone does not establish the validator quorum or committed inclusion. ``` Sequence-batch transaction: 241 bytes "PAXEER/v1/sequence-batch" || 0x00 || Height:u64be || FromSeq:u64be || ToSeq:u64be || PrevSeqHash[32] || LastSeqHash[32] || TxRoot[32] || KeyId[32] || Sig[64] ``` The `Sig` field is an Ed25519 signature over the chain-bound sequence-batch digest. Verify it with the pinned receipt key valid at the batch height, then verify the batch transaction against the committed block. ## Committed inclusion workflow 1. Retain the signed transaction and verify its hash against the receipt. 2. Authenticate the receipt key, height range, signature, and execution outcome. 3. Acquire the covering sequence batch and verify its signature, sequence hashes, and ordered transaction identifiers. 4. Authenticate the covering block and consensus commit using a trusted validator set. 5. Check the expected account changes or payment effect before completing the application action. ## Verify the transport and the money Clients check TLS trust and chain identity before consuming evidence. A healthy endpoint or matching chain ID establishes connectivity. Finality requires authenticated committed inclusion and a verified execution outcome for the intended transaction. Continue with [account and custody interfaces](https://docs.paxeer.app/custody), [Paxeer consensus](https://docs.paxeer.app/consensus), and [native EVM interfaces](https://docs.paxeer.app/precompiles). --- URL: https://docs.paxeer.app/sidiora # Sidiora The SID asset on Paxeer X: native balances, its stable ERC-20 address, bridge-controlled supply, and sponsored or native gas payments. ## Asset Identity Sidiora is the second official coin of Paxeer X. Its native denomination and ERC-20 interface represent one asset, giving wallets, contracts and Cosmos applications a consistent balance model. | Property | Value | | --- | --- | | Symbol | `SID` | | Decimals | `6`; one SID is `1,000,000` base units | | ERC-20 address | `0x21f7b20a555199fa73A238B1a91FD0f549068fEe` | | Native denom | `factory/pax1dzfx9mk4fl9kl2mysjmtvk2xp75ljumk6nynhf/usid` | | Mint and burn authority | The `layerxbridge` module account | | Proxy administration | The proxy owner; a restricted timelock can hold this role | PAX uses the native base denom `uhpx` with six decimal places; EVM value uses eighteen-decimal wei units. Keep SID and PAX scaling separate in displays, approvals, transfer amounts, fee quotations and accounting. Read supply from the native bank state or ERC-20 `totalSupply` for a current value. ## One Asset Across Native and EVM Interfaces The native ERC-20 implementation reads `balanceOf` from the bank balance of the SID denom and `totalSupply` from its bank supply. Transfers move that denom through the bank precompile. A failed bank operation reverts the contract call. The pointer record resolves the denom to the same stable ERC-20 address. The proxy address remains constant through implementation upgrades. Native token metadata and allowances use an ERC-7201 storage namespace. Allowances are read from that namespace. Applications query current allowances before building spending transactions and request the approval required by the current interface. ### Bridge-Controlled Supply The bridge module account administers the tokenfactory denom. Attested bridge-in credits mint SID and bridge-out operations burn the departing amount. Denom creation verifies the bridge-derived creator, expected admin and remote asset mapping. Ordinary holders and application contracts have no minting authority. ## SID gas-payment mechanisms | Property | Sponsored gas | Native fee preference | | --- | --- | --- | | Execution | EIP-7702 account batch and quote service | Chain fee processing | | SID payment | Atomic transfer to the sponsor inside the batch | Fee debit in SID before execution | | Pricing | Signed quote checked against the paymaster rate | Governance-controlled conversion rate | | Replay protection | Account batch nonce and sponsor quote nonce | Normal transaction replay protection and account preference | | Unused gas | Governed by the signed sponsorship quote | Refunded in the selected fee denom | | PAX transaction value | The account still supplies value it sends | The account still supplies value it sends | ## Sponsored Transaction Workflow 1. Build the application calls and request a sponsor quote for the declared gas cost. 2. Verify the configured sponsor, SID token, six-decimal units, chain ID, deadline, quoted amount and maximum. 3. Sign the account batch, covering its nonce, calls hash and quote digest, and authorize the EIP-7702 execution. 4. Execute through `BatchCallAndSponsor`; the account runs the calls and repays the sponsor in SID in the same transaction. The sponsor signature binds chain ID, executing account, sponsor, token, maximum amount, offered amount, deadline, quote nonce and declared gas cost. The account signature must recover to the account itself. Used quote nonces and account batch nonces prevent replay. ### Pricing and Atomicity The paymaster checks a positive, sufficiently fresh rate and requires the offered amount to fall within five percent of the amount implied by the declared gas cost. Expired quotes, zero amounts, an incorrect token or invalid sponsor are refused. A failed application call or SID repayment reverts the whole batch. The configured quote service checks its budget and rate freshness before signing. The executing account verifies the quote against the implementation's rate source. Validate the returned quote and signatures locally before building `executeSponsored`. ## Native Fee Preferences The fee-token precompile at `0x0000000000000000000000000000000000001018` exposes the account preference: ``` function setFeeDenom(string calldata denom) external; function getFeeDenom(address account) external view returns (string memory denom); function clearFeeDenom() external; ``` Call `setFeeDenom` with the SID native denom to select it for the caller, query with `getFeeDenom`, or clear the preference to return to the network coin. The fee-token feature must be enabled and the denom allowed before selection. The precompile rejects value and delegatecall; static calls cannot change preferences. ### Charging and Refunding When fee-token charging is enabled for an allowed preferred denom, EVM fee processing converts the maximum gas charge, including a blob fee when applicable, into the chosen denom. The account must have sufficient spendable SID for that charge and sufficient PAX for any transferred value. The fee debit replaces the PAX gas purchase. Unused gas returns in the same denom. Cosmos transactions can offer allowed fee denoms, whose governed conversion is used for minimum-gas-price checks. ## Governed Rates and Fee Routing Fee conversion uses a governance-controlled rate for each allowed denom. Only allowed fee denoms can be selected through the fee-token precompile. Applications read the current fee parameters before presenting a fee option, and re-estimate when a rate or policy changes. PAX fees keep their ordinary collection path through the fee collector. ## Upgrade Authority When configured as the proxy owner, the Sidiora timelock accepts only governance-scheduled `upgradeToAndCall(address,bytes)` operations targeting the proxy with zero value. The implementation must be a contract distinct from the proxy and timelock. Upgrade and initialization execute together. A designated executor runs an operation after its delay and within its grace period. A guardian can cancel before readiness. The timelock constructor sets the minimum delay, delay floor, and grace period. Read these parameters and the proxy owner from the deployed contracts before evaluating upgrade authority. ## Integration Checklist - Use six-decimal SID amounts and query the current balance and allowance. - Resolve the native denom and stable ERC-20 address as the same asset. - Display the signed sponsorship amount or estimated native fee in SID before approval. - Distinguish gas from PAX value sent by the transaction. - Refresh rates and quotes before submission and preserve transaction evidence for accounting. Explore [Unified Network](https://docs.paxeer.app/unified-network), [Contracts](https://docs.paxeer.app/contracts), [Precompiles](https://docs.paxeer.app/precompiles) and [xweb](https://docs.paxeer.app/xweb), which accepts SID for agent web requests. --- URL: https://docs.paxeer.app/spot-exchange # Spot Exchange Trade asset pairs on Paxeer X with deterministic order books, price-time matching, escrowed liquidity, and immediate two-leg settlement. ## Markets and ownership The LayerX spot module gives each market a base asset, quote asset, tick size, lot size, and administrator. A bid buys the base asset with quote units; an ask sells base units for quote units. Market identifiers, asset identifiers, account identifiers, and order identifiers are 32-byte values. Prices and quantities use unsigned 128-bit integer values: integrations apply the assets' unit conventions before constructing an activity. Spot runs in the LayerX execution kernel as module `10`. It settles through the asset module and uses the same deterministic price-time book engine as perpetuals. The Cosmos Go spot module (`modules/spot`) exposes swap, order, vault, share, and quote operations through `precompiles/spot`. Its EVM rails use their own ABIs; the native book encoding below applies to kernel spot activities. ## Choose an order | Order | Price | Time in force | Remaining quantity | | --- | --- | --- | --- | | Limit GTC | Nonzero limit | Good till cancelled | Rests on the book with escrow after matching | | Limit IOC | Nonzero limit | Immediate or cancel | Does not rest | | Market | Zero in the payload | Immediate or cancel | Does not rest | For native spot, `side` is bid or ask, `kind` is `1` for limit and `2` for market, and limit time in force is `1` for GTC or `2` for IOC. A market order executes against available opposing liquidity. Use a limit IOC when the strategy needs an explicit price boundary. ## Matching and fills The matching engine selects the best opposing price first, the earliest global sequence second, and the order identifier as the final deterministic tie breaker. Every fill uses the resting maker's price. Matching reduces the maker's remaining quantity and escrow; a completely filled maker leaves the book. ### Worked example An ask offers 5 base units at a price of 100 quote units per base unit. An incoming limit bid for 3 units at 105 crosses that ask. The trade executes at the maker price of 100: the buyer receives 3 base units, the seller receives 300 quote units, and the ask retains 2 units. This example uses whole units for readability; encoded values follow the market's asset-unit, tick, and lot conventions. ## Escrow and settlement A resting ask escrows its remaining base quantity. A resting bid escrows the quote amount required by its price and remaining quantity. Each fill settles the base transfer and quote transfer immediately as `lxp_transfer_leg` entries with reason `LXP_REASON_ESCROW_CAPTURE` (`5`); locking escrow uses `LXP_REASON_ESCROW_LOCK` (`4`) and refunds use `LXP_REASON_ESCROW_RELEASE` (`6`). Spot keeps no separate shadow balance: asset-module ownership, pause rules, account namespaces, and debit authorization apply to settlement. After cancellation or execution, reconcile the order's remaining quantity and the asset account state together. An accepted submission identifies an attempted activity; the resulting receipt and state establish the execution outcome. An agent should record its order identifier before submission and retain the corresponding activity and receipt evidence. ## Native activity reference | Activity | Type | Canonical payload | | --- | --- | --- | | Create market | `0x000A0001` | Market, base asset, quote asset, tick size, lot size, administrator | | Place order | `0x000A0002` | Market, order, base account, quote account, side, kind, time in force, price, quantity | | Cancel order | `0x000A0003` | Market and order identifiers | | Halt market | `0x000A0004` | Market identifier | | Resume market | `0x000A0005` | Market identifier | ``` ORDER_PLACE: 163 bytes market_id[32] || order_id[32] || base_account_id[32] || quote_account_id[32] || side:u8 || kind:u8 || time_in_force:u8 || price:u128be || quantity:u128be ORDER_CANCEL: 64 bytes market_id[32] || order_id[32] ``` Market creation uses a 160-byte payload; halt and resume use 32 bytes. Escrow identifiers are derived from the market and asset rather than supplied by the caller. Encode canonical big-endian integers and exact field widths. ## Agent trading workflow 1. Resolve the market's base and quote assets, trading increments, and halted state. 2. Check the strategy's authorized accounts and available asset balances. 3. Choose a price boundary, quantity, order kind, and time in force; allocate and persist an order identifier. 4. Submit the signed transaction carrying the native operation and retain its transaction hash. 5. Verify the receipt, account changes, fills, and residual order state before updating inventory. 6. Cancel a residual quote using its market and order identifiers. Reconcile the cancellation result before treating its reserved inventory as available for another order. Market-making agents can quote both sides, cancel stale quotes, and adjust inventory using the same accounts and matching rules as other principals. Strategy decisions remain outside consensus; order authorization, matching, and settlement follow deterministic protocol rules. ## EVM spot interfaces Contracts use the PECOR swap rail implemented by `precompiles/spot/pecor.go` at `0x0000000000000000000000000000000000001021`. Separate rails provide limit orders, stop orders, quotes, and vault operations. These calls execute through the Cosmos spot keeper within the same chain. The order rail is at `0x1022`, stop-order rail at `0x1023`, quoter at `0x1024`, and vault at `0x1025`, each left-padded to a 20-byte address. Their ABI definitions are in precompiles/spot/abi. Use each rail's published function parameters and integer units when constructing an EVM call. ## Capacity and operational refusals The native module supports 64 markets and 256 resting orders per market. One activity produces at most 8 fills and 18 transfer legs. These are compile-time execution bounds: strategies split large operations and reconcile each result rather than assuming unlimited book traversal. A duplicate market returns `LXP_ERR_MARKET_ALREADY_EXISTS`; order placement on a halted market returns `LXP_ERR_MARKET_HALTED`. Asset mismatch, paused assets, unauthorized debits, unknown account namespaces, sequence reuse, and noncanonical payloads also refuse execution. Correct the underlying account, market, or encoding condition before submitting a new operation. ## Continue building See [Market Makers](https://docs.paxeer.app/market-makers) for quoting and ramp inventory workflows, [Precompiles](https://docs.paxeer.app/precompiles) for contract integration, and [Modules](https://docs.paxeer.app/modules) for execution capabilities. **Protocol references:** `include/layerx/lx_spot.h`, `src/modules/spot/lx_spot_market.c`, `src/modules/spot/lx_spot_book.c`, `src/modules/spot/lx_spot_dispatch.c`, and `precompiles/spot/spot.go`. --- URL: https://docs.paxeer.app/storage-scan # Bounded Storage Scans Iterate Paxeer X program state with deterministic ordering, explicit page budgets, scope-bound continuation cursors, and metered canonical results. ## Read a namespace in bounded pages The guest host function `layerx_v2.storage_scan_scoped` returns ordered key/value pairs matching a byte prefix. Every call declares an entry ceiling and a complete encoded-page byte ceiling. A portable continuation token resumes after the last returned key across activities without retaining a host iterator or allocator handle. This function belongs to the frozen ABI v2 namespace, `layerx_v2`. The runtime declares its nine i32 parameters and i32 result in the versioned ABI manifest. A program must declare an ABI version that includes this namespace. Use scans for bounded indexes, application inventories, and paginated state processing. Design keys with stable prefixes and choose page sizes that fit the call's storage-read budget and guest output buffer. Returning scan data as an activity response also consumes the response output budget. The function scans one authorized namespace. ## Host-call contract ``` storage_scan_scoped( raw_selector: i32, prefix_pointer: i32, prefix_length: i32, cursor_pointer: i32, cursor_length: i32, max_entries: i32, max_bytes: i32, output_pointer: i32, output_capacity: i32 ) -> i32 ``` | Input | Contract | | --- | --- | | Selector 1 | Principal-scoped namespace; requires `StorageRead` and the matching access declaration. | | Selector 2 | Shared program namespace; requires `SharedStorageRead` and the matching access declaration. | | Prefix | At most 256 bytes. An empty prefix selects all keys within the namespace. | | Cursor | Empty starts a scan. A nonempty token must match the same namespace, prefix, and limits. | | Entry ceiling | Between 1 and 64 entries per page. | | Page byte ceiling | Between 5 and 67,126,228 complete encoded bytes. | | Output range | A valid guest-memory buffer large enough for the encoded result. | | Return value | Nonnegative encoded byte length on success; a negative host status on refusal. | The host validates the output range before reading the prefix and cursor. It previews and encodes the page, checks output capacity, charges the storage-read meter, then copies bytes to guest memory. A negative length, invalid selector, out-of-memory range, or denied read is rejected before output is written. ## Decode the canonical page All lengths below are big-endian. Parse only the number of bytes returned by the host, validate each length against the remaining buffer, and require the cursor fields to agree. | Field | Width | | --- | --- | | Entry count | u16 | | For each entry: key length, key | u16 followed by key bytes | | For each entry: value length, value | u32 followed by value bytes | | Has-cursor flag | u8: 0 or 1 | | Cursor length, cursor | u16 followed by cursor bytes; zero length when no cursor | ``` # Empty terminal page: 5 bytes 00 00 00 00 00 # One entry, key "a", value "b", no continuation: 13 bytes 00 01 00 01 61 00 00 00 01 62 00 00 00 ``` The complete encoding consumes the storage-read budget, including counts, lengths, cursor bytes, and the five-byte empty page. Allocate room for continuation metadata as well as the key/value content. A page with one short entry and a continuation can be larger than a terminal page with several short entries. ## Resume without changing scan identity The cursor binds version, canonical namespace, prefix, entry ceiling, byte ceiling, and the last returned key. Treat its bytes as an opaque continuation token in application code. Reuse them exactly with the same selector, program, principal where applicable, prefix, and both limits. Changing a limit to increase page size requires starting a new scan with an empty cursor. A principal cursor cannot resume in shared scope or under another program. Corrupted bytes, trailing bytes, empty last-key fields, and keys inconsistent with the prefix are invalid. The maximum encoded cursor size is 591 bytes. ### Pagination workflow 1. Choose the authorized scope and stable prefix. Select both page ceilings and allocate a guest output buffer. 2. Call with an empty cursor and check the signed return status before decoding memory. 3. Decode the complete page, process its entries, and retain the exact continuation bytes. 4. When a cursor is present, invoke again with unchanged scan identity and limits. 5. Stop when the page has no continuation cursor. Each resumed activity reads its current authorized state. The cursor identifies a position and scan contract; it does not claim that all pages share a frozen historical state. For an application that needs a consistent export, bind the surrounding workflow to its own verified state and mutation policy. ## Two independent page bounds The scan stops before exceeding the entry count. It also checks the complete encoded size when adding each matching entry. If an entry would exceed the page-byte limit, it is removed and the preceding entries return with a cursor. If no entry can fit, the scan refuses with a bounds status rather than returning an ambiguous empty continuation. In a principal-scoped namespace with an empty prefix, three pairs `(a,a)`, `(b,b)`, and `(c,c)` have a 29-byte terminal encoding. With a fourth pair and limits `(64, 101)`, the first page contains two entries plus continuation and occupies 101 bytes. A 100-byte limit yields one entry plus continuation at 93 bytes. The byte ceiling must allow continuation metadata while the page is assembled. ## Refusals and unchanged output | Status | Meaning | Response | | --- | --- | --- | | `-1` denied | Missing matching read authority or access declaration. | Supply the correct admitted grant and scope. | | `-2` invalid | Malformed input, invalid selector or limits, or a mismatched cursor. | Correct the request; restart pagination if identity changes. | | `-3` bounds | Oversized prefix/cursor, invalid memory range, insufficient output capacity, or no entry fitting the page ceiling. | Correct memory bounds or start a new scan with suitable limits. | | `-4` meter | Insufficient admitted storage-read budget for the encoded page. | Increase the activity budget within admitted ceilings. | Refusals before charging leave storage-read usage unchanged. A refused charge produces no partial page. The host writes output only after validation and metering succeed, so output bytes remain unchanged on these refusal paths. Never interpret preexisting buffer contents as a fresh page after a negative return. ## Determinism, writes, and rollback Storage is ordered by program, scope, and key. Within the chosen namespace, entries return in canonical key order independent of insertion order. Equivalent state and scan inputs produce equivalent pages, usage, and evidence. A scan sees writes already staged in the same activity because both use the activity's storage snapshot. A successful activity commits those writes. A later trap discards the staged mutation and returns the runtime-fault outcome without a successful response. Do not treat a page observed inside a failed guest execution as committed state. Read [Programs](https://docs.paxeer.app/programs) for call budgets, response transport, and receipt verification, or [the developer workspace](https://docs.paxeer.app/program-workspace) for conformance and ABI checks. **Technical references:** programs/crates/layerx-programs-runtime/src/host/scan.rs, src/storage/scan.rs, src/abi/storage_ops.rs, src/abi/manifest.rs, and tests/storage_scan.rs within that runtime crate. --- URL: https://docs.paxeer.app/storage # Storage State commitment, historical queries, receipt retention, and backend configuration in Paxeer. ## Overview Paxeer storage separates active state commitment from historical state queries and receipt storage. Each has its own configuration and retention behavior. The implementation is under `storage/` at the repository root. ## State Commitment The state-commit layer under `storage/state_db/sc/` includes MemIAVL, FlatKV, and a composite store that routes state operations. It participates in application commitment, snapshot import/export, and supported proof queries. The default write mode is `memiavl_only`. Other named modes support staged migration to FlatKV. Select routing modes according to the existing data layout and the chain's migration plan. ``` # app.toml [state-commit] sc-enable = true sc-write-mode = "memiavl_only" ``` **Source:** `storage/config/sc_config.go`, `storage/config/write_mode.go`, `storage/state_db/sc/composite/store.go`. ## Historical State Store The state-store layer maintains versioned key/value data for historical queries. Configure imported data and retention for the historical range you need. Commitment proofs also require the corresponding commitment-store history. ``` # app.toml [state-store] ss-enable = true ss-backend = "pebbledb" ss-keep-recent = 100000 ``` The default backend is Pebble and the default retention is 100,000 versions. `ss-keep-recent = 0` retains all available versions. The config also supports a separate EVM historical store through `evm-ss-split`; its data routing and missing-key behavior differ from the unsplit store. **Source:** `storage/config/ss_config.go`, `storage/config/toml.go`, `storage/state_db/ss/`. ## RocksDB Backend The optional RocksDB backend uses user-defined timestamps and column families for versioned state. Build RocksDB and install the node from the repository root: ``` make build-rocksdb make install-rocksdb ``` After installing the compatible binary, set `ss-backend = "rocksdb"` under `[state-store]`. When changing backends, import or restore data in the target backend's format. Compare backends with the same revision, hardware, retained history, and request workload. Measure historical-query latency, iteration time, disk usage, and write throughput for the operations your application uses. **Source:** `chain.mk` — `build-rocksdb`, `install-rocksdb` (the root `Makefile` delegates to `chain.mk` through `PAXEER_MAKE`); `storage/db_engine/rocksdb/mvcc/opts.go`. ## Receipts and Blocks ``` # app.toml: root setting must precede section headers min-retain-blocks = 100000 [receipt-store] rs-backend = "pebbledb" ``` The receipt configuration accepts `pebbledb` or its `pebble` alias. Set receipt retention with the root `min-retain-blocks` setting and historical state retention with `ss-keep-recent`. `--mode archive` configures block and SS retention to zero, preserving imported history and subsequent state. Start with a dataset covering the historical range you plan to serve. **Source:** `storage/config/receipt_config.go`, `node/params/config.go` — `setArchiveTypeAppConfig`. ## Snapshots and Recovery Application snapshots, commitment-store snapshots, and filesystem backups are distinct. Use the mechanism and directory layout matching your build. Stop a node before replacing its data, preserve validator last-sign state, and keep a compatible copy of the configuration and genesis. Changelogs and write-ahead logs support storage replay and recovery. Follow the recovery procedure for the selected store, and preserve consensus signer state alongside the validator key. **Source:** `storage/wal/`, `storage/state_db/sc/composite/`, `consensus/privval/file.go`. ## Inspection Tools The PaxDB command provides storage inspection and benchmark operations. Build or run it from the repository root, using its help to select the correct database path and height: ``` go run ./storage/tools/cmd/paxdb --help go run ./storage/tools/cmd/paxdb dump-iavl --help go run ./storage/tools/cmd/paxdb dump-db --help ``` Beyond inspection, `paxdb` provides `dump-flatkv` and `import-flatkv-from-memiavl` for FlatKV export and migration, `migrate-evm-status` for EVM status migration, `prune` for version pruning, and `replay-changelog` for changelog replay. Run these operations through `paxdb`. Use an offline copy when an operation needs exclusive database access. **Source:** `storage/tools/cmd/paxdb/main.go`, `storage/tools/cmd/paxdb/operations/`. ## Next Steps - [Configure node storage](https://docs.paxeer.app/configuration) - [Operate and recover a node](https://docs.paxeer.app/operators) - [Understand block commitment](https://docs.paxeer.app/consensus) --- URL: https://docs.paxeer.app/streams # Streaming Payments Pay for elapsed time or verified usage with funded, capped streams, deterministic accrual, settlement, and cancellation. ## Continuous Commerce on Paxeer X Streams turn ongoing work into incremental payment obligations. Time streams support service retainers, compute reservations, and recurring agent work. Metered streams pay for signed usage readings such as completed requests or consumed resources. Both use an isolated `agent::stream:` account and settle through `402LXP` transfer legs. Accrual and settlement are separate: accrual calculates how much the recipient has earned, while settlement transfers available funds. A stream has a lifetime cap and can be topped up, paused, resumed, or closed by its payer. ## Choose a Payment Mode | Mode | Accrual input | Typical use | | --- | --- | --- | | Time (`1`) | Elapsed batch time in milliseconds, bounded by the stream end time. | Agent availability, access, subscriptions, reserved compute. | | Metered (`2`) | Increase in a signed cumulative meter reading. | API calls, work units, bandwidth, resource consumption. | ## Opening and Funding a Stream Set the stream ID, dedicated account, recipient, asset, mode, rate, rate unit, start and end timestamps, total cap, and positive initial funding. Amounts and rates use integer asset base units. The payer supplies authorized funds; the stream account must differ from the recipient account. For time mode, `rate_unit` is a time interval in milliseconds. For metered mode, it is a quantity of meter units. A metered stream registers between one and eight authority keys in strictly increasing order. A time stream has no meter authorities. ### Accrual Formula ``` new_amount = floor((rate × delta + remainder_carry) / rate_unit) new_amount = min(new_amount, total_cap - accrued_total) claimable = accrued_total - settled_total payment = min(claimable, stream_account_balance) ``` The remainder carries across accrual calculations so frequent settlement does not repeatedly discard fractional base units. Batch timestamps provide a shared clock; regressing timestamps fail. Reaching the cap stops additional accrual. ## Time Stream Example 1. Fund a stream with 600 base units and set a lifetime cap of 600. 2. Set `rate = 10` and `rate_unit = 60000`, paying 10 base units per minute. 3. After 15 active minutes, 150 units have accrued. Settle to pay those 150 to the named recipient. 4. Pause for five minutes, then resume. The paused interval earns no additional time payment. 5. Close after another 10 active minutes. With sufficient funding, closing pays the remaining 100 accrued units and refunds the unused 350 to the payer. ## Metered Stream Workflow A meter authority signs the stream ID, cumulative reading, and authority key under the `LXP:STREAM:METER:v1` message tag. The stream verifies the Ed25519 signature and checks that the key belongs to its registered authority set. For a rate of 20 base units per 100 usage units, a reading increase from 1,000 to 1,250 accrues 50 base units. Readings cannot move backward. Repeating a reading produces no new accrual; multiple authority keys attest to the same cumulative meter rather than maintaining independent counters. Submit authenticated readings, then settle the accrued amount. Meter readings accepted while paused or underfunded advance the meter baseline without accruing payment, preventing that recorded usage from being charged retroactively when payment resumes. ## Funding, Claims, and Cancellation | Action | Behavior | | --- | --- | | Top up | Add authorized funds to an existing open stream. Funding does not increase its lifetime cap. | | Settle / claim | Pay accrued, unsettled value to the fixed recipient, limited to the funded balance. | | Pause | Payer checkpoints time accrual and stops further earning while paused. | | Resume | Payer restarts from the current batch timestamp without charging paused time. | | Rate change | Payer settles accrued value at the existing rate, then replaces the rate for subsequent accrual under a fresh idempotency key. | | Close / cancel | Payer settles payable accrued value, refunds the excess balance, and permanently closes the stream. | ### Underfunding If settlement cannot cover all accrued value, it pays the available balance, resets accrued value to the settled total, and marks the stream underfunded. This does not preserve an unpaid debt balance. Accrual stops while underfunded. A top-up clears underfunding and starts the next time-accrual interval at the top-up timestamp. **Maintain funding for continuous service.** Monitor the stream balance, earned amount, cap, pause state, and underfunding state together. A payment cap limits earned value; a funded balance determines what settlement can actually pay. ### Closing a Stream Closing a funded active time stream first accounts for eligible elapsed time. It pays the recipient up to the available balance and returns the rest to the payer in the same transfer set. Closing is final: the stream cannot resume or receive further top-ups. ## Protocol Reference Streams are module `4`, with payload version `1`. The version prefix is two bytes, `00 01`. | Activity | Type | Payload bytes | | --- | --- | --- | | `LX_STREAM_OPEN` | `0x00040001` | 204 + 32 per authority | | `LX_STREAM_TOP_UP` | `0x00040002` | 50 | | `LX_STREAM_METER` | `0x00040003` | 138 | | `LX_STREAM_SETTLE` | `0x00040004` | 66 | | `LX_STREAM_PAUSE` | `0x00040005` | 34 | | `LX_STREAM_RESUME` | `0x00040006` | 34 | | `LX_STREAM_CLOSE` | `0x00040007` | 66 | | `LX_STREAM_RATE_CHANGE` | `0x00040008` | 82 | The rate-change payload carries the stream ID, a positive new rate as an unsigned 128-bit integer, and a nonzero idempotency key. The operation settles payable accrued value before storing the new rate. It preserves the stream's cap and rate unit. ### Retries and Validation Settle and close include a nonzero idempotency key. Retry the same economic operation with its original key and retain the result receipt. A key cannot identify a different stream or operation. Reject malformed versions, trailing payload bytes, meter regressions, unauthorized meters, and operations against a closed stream. Funding, draws, and refunds use published transfer assets and follow asset pause and asset-match rules. The stream account only permits its protocol-authorized draw and refund paths. Payloads are defined in `include/layerx/lx_stream.h` and `modules/layerxpay/types/payload_stream.go`; execution is implemented in `src/modules/stream/`. ## Related Guides - [Escrow and milestone payments](https://docs.paxeer.app/escrow) - [Protocol modules](https://docs.paxeer.app/modules) - [SDK integration](https://docs.paxeer.app/sdk) --- URL: https://docs.paxeer.app/subscriptions # Event subscriptions Build durable agent consumers with scoped visibility, acknowledged cursors, explicit gap recovery, and verified receipt references. Paxeer X subscriptions let an agent observe activity without repeatedly rebuilding its view from individual queries. The contract persists the subscription definition, acknowledgement position, continuity state, and lifecycle controls in the agent daemon. An event carries its identity, bytes, deduplication identifier, cursor, and an optional verified receipt reference. The Agent API routes `subscription.create`, `subscription.list` and `subscription.health` to the daemon's durable subscription store. Creation uses an *idempotent mutation*; list and health reads require the authenticated session's operation permit. ## Choose the event interface | Interface | Consumer model | Recovery mechanism | | --- | --- | --- | | Agent subscriptions | Authenticated tenant, agent, and capability; explicit filter and delivery target. | Durable acknowledged cursor, backfill barrier, truncation notice. | | [Hosted webhooks](https://docs.paxeer.app/webhooks) | Developer HTTPS endpoints for journey, payment, approval, and program families. | Signed delivery, retries, dead letters, and signed replay cursors. | Choose the agent subscription interface when an autonomous runtime needs visibility constrained by its session capability. Choose webhooks when an external application receives hosted event families over HTTPS. Their cursor and verification representations belong to their respective interfaces. ## Create a scoped subscription `subscription.create` requires `scope`, `filter`, `start`, and `delivery_target`, inside an idempotent mutation. The scope names tenant, agent, and capability and must equal the authenticated owner coordinates. The same key and request return the original record; a changed request under that key is refused. | Filter field | Restriction | | --- | --- | | agents | Selected agent identities. | | accounts | Selected accounts visible to the owner. | | activity_types | Selected native operation types. | | modules | Selected module activity. | | assets | Selected assets. | | counterparties | Selected interacting principals. | | result_classes | Selected outcome classes. | Evaluation applies tenant restriction first, capability scope second, and filter third. A filter narrows visibility and cannot expand a capability or disclose another tenant's records. Administrative list and health operations also require the authenticated session's operation permit. ## Consume and acknowledge 1. Restore the persisted subscription and last acknowledged cursor. 2. Receive an Event, Gap, or Truncated delivery. 3. For an Event, claim its `deduplication_id` in your durable consumer store. 4. Verify any receipt evidence required for the business decision. 5. Commit the application effect and deduplication record together. 6. Acknowledge the delivered cursor after that commit. ``` EventDelivery event_identity event_bytes deduplication_id cursor receipt_reference: None | Verified { receipt_ref, rung } cursor = { block_height: "125", tx_index: "0", log_index: "0" } subscription.acknowledge(scope, subscription_id, cursor) ``` Delivery is at least once. An acknowledgement records progress; it does not make a business handler transactional. If the process crashes after applying an effect but before acknowledging, the repeated delivery must find the completed deduplication record. Each cursor is an object with block_height, tx_index, and log_index fields encoded as canonical decimal strings. Preserve all three coordinates when saving or acknowledging progress. The daemon refuses acknowledgements for never-delivered cursors and rejects regressing positions. Keep processing and acknowledgement ordered for a subscription instead of advancing past unfinished work. ## Resolve gaps before advancing A Gap contains `missing_first`, `missing_last`, `backfill_cursor`, and `backfill_attempted`. It forms a continuity barrier: later events remain blocked until successful backfill or an explicit truncation notice. Persist that blocked state so a restart cannot accidentally cross the missing interval. If retention no longer contains the requested interval, Truncated reports `requested_first`, `oldest_available`, and `resume_cursor`. Rebuild the application view from authoritative state or retained history, record the discontinuity, and continue from the declared resume point. Treat truncation as an explicit loss of continuity. ## Pause, resume, and inspect health | Operation | Required fields | Use | | --- | --- | --- | | `subscription.list` | scope | Find subscriptions visible to the authenticated owner. | | `subscription.health` | scope, subscription_id | Inspect acknowledged progress and pending backfill. | | `subscription.acknowledge` | scope, subscription_id, cursor | Persist completed delivery progress. | | `subscription.pause` | scope, subscription_id | Stop delivery temporarily while preserving position. | | `subscription.resume` | scope, subscription_id | Continue under current authorization and continuity controls. | | `subscription.delete` | scope, subscription_id | Terminate delivery while retaining its audit record. | Health returns the target, `last_acknowledged`, `last_delivery_at`, and `pending_backfill`. The current daemon returns null for the delivery timestamp. Pending backfill reports the missing sequence range, including truncated continuity over the subscription's own coordinates. ## Revocation and restart safety Session, capability, or tenant revocation stops the corresponding subscription. Durable termination distinguishes Deleted, SessionRevoked, CapabilityRevoked, and TenantRevoked. Session-bound access continues to require an authorized operation rather than relying on possession of a subscription identifier. Restart restores definition, acknowledged position, unacknowledged deliveries, and continuity. Preserve the daemon store together with its tenant and session context. A corrupt or unavailable store refuses progress instead of silently resetting the cursor. ## Separate notification from proof An event may carry no receipt reference. A verified reference names its receipt and rung with Paxeer as the settlement domain. Event arrival alone does not establish an economic outcome. The Agent API reports `submitted`, `receipted` and `committed`; a verified receipt reference requires at least receipted. For settlement-sensitive automation, retrieve the evidence and require committed block evidence. Keep local approval and policy notifications distinguishable from protocol receipts. See [Agents on Paxeer X](https://docs.paxeer.app/agents) for the write lifecycle and [Agent runtime](https://docs.paxeer.app/agent-runtime) for capability, readiness, and recovery controls. **Reference:** `services/agent/crates/layerx-agent-api/src/stream.rs` and `services/agent/crates/layerx-agentd/src/agent_rpc_adapters.rs`; `services/agent/crates/layerx-agentd/src/events/subscription.rs` in the monorepo. --- URL: https://docs.paxeer.app/system-map # System map Explore every Paxeer 7.0.0 system by kind, release change, and name, with build commands, configuration, health checks, dependencies, and documentation. Choose a system to expand its details. Follow a dependency to open that system, including when it is outside the current filters. Build commands run from the repository root unless they include a change of directory. ## node ### Paxeer chain node Identifier: chain-node Change in 7.0.0: changed Directory: daemon/paxd Build command: ```sh make build ``` Build output: build/paxd Configuration: node/params/config.go and docs/release/7.0.0-validator-runbook.md Ports: 26656, 26657, 8545, 8546, 1317 Health check: paxd status Depends on: None Site pages: [/run-node](https://docs.paxeer.app/run-node) Repository references: docs/release/7.0.0-upgrade-plan.md, docs/release/7.0.0-validator-runbook.md, docs/site/paxeer-docs/src/app/run-node/page.tsx ## kernel ### LayerX kernel host Identifier: kernel Change in 7.0.0: changed Directory: modules/lxphost Build command: ```sh make build ``` Build output: build/paxd with the native kernel archive Configuration: modules/lxphost and docs/site/paxeer-docs/src/app/layerx-kernel/page.tsx Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/layerx-kernel](https://docs.paxeer.app/layerx-kernel) Repository references: docs/system/kernel-modules.md, docs/site/paxeer-docs/src/app/layerx-kernel/page.tsx ## module ### Epoch module Identifier: module-epoch Change in 7.0.0: unchanged Directory: modules/epoch Build command: ```sh go build ./modules/epoch/... ``` Build output: linked into build/paxd Configuration: modules/epoch/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### EVM module Identifier: module-evm Change in 7.0.0: unchanged Directory: modules/evm Build command: ```sh go build ./modules/evm/... ``` Build output: linked into build/paxd Configuration: modules/evm/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Launchpad module Identifier: module-launchpad Change in 7.0.0: changed Directory: modules/launchpad Build command: ```sh go build ./modules/launchpad/... ``` Build output: linked into build/paxd Configuration: modules/launchpad/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX agent module Identifier: module-layerx-agent Change in 7.0.0: new Directory: modules/layerxagent Build command: ```sh go build ./modules/layerxagent/... ``` Build output: linked into build/paxd Configuration: modules/layerxagent/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX anchor module Identifier: module-layerx-anchor Change in 7.0.0: retired Directory: modules/layerxanchor Build command: ```sh go build ./modules/layerxanchor/... ``` Build output: linked into build/paxd Configuration: modules/layerxanchor/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX auth module Identifier: module-layerx-auth Change in 7.0.0: new Directory: modules/layerxauth Build command: ```sh go build ./modules/layerxauth/... ``` Build output: linked into build/paxd Configuration: modules/layerxauth/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX bridge module Identifier: module-layerx-bridge Change in 7.0.0: unchanged Directory: modules/layerxbridge Build command: ```sh go build ./modules/layerxbridge/... ``` Build output: linked into build/paxd Configuration: modules/layerxbridge/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX chains module Identifier: module-layerx-chains Change in 7.0.0: new Directory: modules/layerxchains Build command: ```sh go build ./modules/layerxchains/... ``` Build output: linked into build/paxd Configuration: modules/layerxchains/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX custody module Identifier: module-layerx-custody Change in 7.0.0: retired Directory: modules/layerxcustody Build command: ```sh go build ./modules/layerxcustody/... ``` Build output: linked into build/paxd Configuration: modules/layerxcustody/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX exchange module Identifier: module-layerx-exchange Change in 7.0.0: unchanged Directory: modules/layerxexchange Build command: ```sh go build ./modules/layerxexchange/... ``` Build output: linked into build/paxd Configuration: modules/layerxexchange/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX governance module Identifier: module-layerx-gov Change in 7.0.0: unchanged Directory: modules/layerxgov Build command: ```sh go build ./modules/layerxgov/... ``` Build output: linked into build/paxd Configuration: modules/layerxgov/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX ledger module Identifier: module-layerx-ledger Change in 7.0.0: new Directory: modules/layerxledger Build command: ```sh go build ./modules/layerxledger/... ``` Build output: linked into build/paxd Configuration: modules/layerxledger/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### LayerX pay module Identifier: module-layerx-pay Change in 7.0.0: new Directory: modules/layerxpay Build command: ```sh go build ./modules/layerxpay/... ``` Build output: linked into build/paxd Configuration: modules/layerxpay/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Mint module Identifier: module-mint Change in 7.0.0: unchanged Directory: modules/mint Build command: ```sh go build ./modules/mint/... ``` Build output: linked into build/paxd Configuration: modules/mint/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Oracle module Identifier: module-oracle Change in 7.0.0: unchanged Directory: modules/oracle Build command: ```sh go build ./modules/oracle/... ``` Build output: linked into build/paxd Configuration: modules/oracle/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Perpetuals module Identifier: module-perps Change in 7.0.0: unchanged Directory: modules/perps Build command: ```sh go build ./modules/perps/... ``` Build output: linked into build/paxd Configuration: modules/perps/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Price feed module Identifier: module-pricefeed Change in 7.0.0: unchanged Directory: modules/pricefeed Build command: ```sh go build ./modules/pricefeed/... ``` Build output: linked into build/paxd Configuration: modules/pricefeed/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Embedded sequencer module Identifier: module-sequencer Change in 7.0.0: new Directory: modules/sequencer Build command: ```sh go build ./modules/sequencer/... ``` Build output: linked into build/paxd Configuration: modules/sequencer/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Spot module Identifier: module-spot Change in 7.0.0: unchanged Directory: modules/spot Build command: ```sh go build ./modules/spot/... ``` Build output: linked into build/paxd Configuration: modules/spot/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Store module Identifier: module-store Change in 7.0.0: unchanged Directory: modules/store Build command: ```sh go build ./modules/store/... ``` Build output: linked into build/paxd Configuration: modules/store/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### Token factory module Identifier: module-tokenfactory Change in 7.0.0: unchanged Directory: modules/tokenfactory Build command: ```sh go build ./modules/tokenfactory/... ``` Build output: linked into build/paxd Configuration: modules/tokenfactory/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ### XWeb module Identifier: module-xweb Change in 7.0.0: unchanged Directory: modules/xweb Build command: ```sh go build ./modules/xweb/... ``` Build output: linked into build/paxd Configuration: modules/xweb/types and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/modules](https://docs.paxeer.app/modules) Repository references: docs/system/chain-modules.md, docs/site/paxeer-docs/src/app/modules/page.tsx ## precompile ### Address binding precompiles Identifier: precompile-addr Change in 7.0.0: changed Directory: precompiles/addr Build command: ```sh go build ./precompiles/addr/... ``` Build output: registered in build/paxd Configuration: precompiles/addr/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Bank precompile Identifier: precompile-bank Change in 7.0.0: unchanged Directory: precompiles/bank Build command: ```sh go build ./precompiles/bank/... ``` Build output: registered in build/paxd Configuration: precompiles/bank/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Common token precompiles Identifier: precompile-common Change in 7.0.0: unchanged Directory: precompiles/common Build command: ```sh go build ./precompiles/common/... ``` Build output: registered in build/paxd Configuration: precompiles/common/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Distribution precompiles Identifier: precompile-distribution Change in 7.0.0: unchanged Directory: precompiles/distribution Build command: ```sh go build ./precompiles/distribution/... ``` Build output: registered in build/paxd Configuration: precompiles/distribution/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Fee token precompile Identifier: precompile-feetoken Change in 7.0.0: changed Directory: precompiles/feetoken Build command: ```sh go build ./precompiles/feetoken/... ``` Build output: registered in build/paxd Configuration: precompiles/feetoken/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Governance precompile Identifier: precompile-gov Change in 7.0.0: unchanged Directory: precompiles/gov Build command: ```sh go build ./precompiles/gov/... ``` Build output: registered in build/paxd Configuration: precompiles/gov/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### IBC precompiles Identifier: precompile-ibc Change in 7.0.0: unchanged Directory: precompiles/ibc Build command: ```sh go build ./precompiles/ibc/... ``` Build output: registered in build/paxd Configuration: precompiles/ibc/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### JSON precompile Identifier: precompile-json Change in 7.0.0: unchanged Directory: precompiles/json Build command: ```sh go build ./precompiles/json/... ``` Build output: registered in build/paxd Configuration: precompiles/json/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Launchpad precompiles Identifier: precompile-launchpad Change in 7.0.0: changed Directory: precompiles/launchpad Build command: ```sh go build ./precompiles/launchpad/... ``` Build output: registered in build/paxd Configuration: precompiles/launchpad/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX agent precompiles Identifier: precompile-layerx-agent Change in 7.0.0: new Directory: precompiles/layerxagent Build command: ```sh go build ./precompiles/layerxagent/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxagent/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX anchor precompile Identifier: precompile-layerx-anchor Change in 7.0.0: retired Directory: precompiles/layerxanchor Build command: ```sh go build ./precompiles/layerxanchor/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxanchor/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX auth precompile Identifier: precompile-layerx-auth Change in 7.0.0: new Directory: precompiles/layerxauth Build command: ```sh go build ./precompiles/layerxauth/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxauth/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX bridge precompile Identifier: precompile-layerx-bridge Change in 7.0.0: changed Directory: precompiles/layerxbridge Build command: ```sh go build ./precompiles/layerxbridge/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxbridge/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX chains precompile Identifier: precompile-layerx-chains Change in 7.0.0: new Directory: precompiles/layerxchains Build command: ```sh go build ./precompiles/layerxchains/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxchains/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX custody precompile Identifier: precompile-layerx-custody Change in 7.0.0: retired Directory: precompiles/layerxcustody Build command: ```sh go build ./precompiles/layerxcustody/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxcustody/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX exchange precompile Identifier: precompile-layerx-exchange Change in 7.0.0: unchanged Directory: precompiles/layerxexchange Build command: ```sh go build ./precompiles/layerxexchange/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxexchange/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX ledger precompile Identifier: precompile-layerx-ledger Change in 7.0.0: new Directory: precompiles/layerxledger Build command: ```sh go build ./precompiles/layerxledger/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxledger/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX pay precompile Identifier: precompile-layerx-pay Change in 7.0.0: new Directory: precompiles/layerxpay Build command: ```sh go build ./precompiles/layerxpay/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxpay/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX programs precompile Identifier: precompile-layerx-programs Change in 7.0.0: changed Directory: precompiles/layerxprograms Build command: ```sh go build ./precompiles/layerxprograms/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxprograms/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### LayerX verify precompile Identifier: precompile-layerx-verify Change in 7.0.0: retired Directory: precompiles/layerxverify Build command: ```sh go build ./precompiles/layerxverify/... ``` Build output: registered in build/paxd Configuration: precompiles/layerxverify/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Oracle precompile Identifier: precompile-oracle Change in 7.0.0: unchanged Directory: precompiles/oracle Build command: ```sh go build ./precompiles/oracle/... ``` Build output: registered in build/paxd Configuration: precompiles/oracle/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### P-256 precompile Identifier: precompile-p256 Change in 7.0.0: unchanged Directory: precompiles/p256 Build command: ```sh go build ./precompiles/p256/... ``` Build output: registered in build/paxd Configuration: precompiles/p256/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Perpetuals precompile Identifier: precompile-perps Change in 7.0.0: unchanged Directory: precompiles/perps Build command: ```sh go build ./precompiles/perps/... ``` Build output: registered in build/paxd Configuration: precompiles/perps/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Pointer precompile Identifier: precompile-pointer Change in 7.0.0: unchanged Directory: precompiles/pointer Build command: ```sh go build ./precompiles/pointer/... ``` Build output: registered in build/paxd Configuration: precompiles/pointer/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Pointer view precompile Identifier: precompile-pointerview Change in 7.0.0: unchanged Directory: precompiles/pointerview Build command: ```sh go build ./precompiles/pointerview/... ``` Build output: registered in build/paxd Configuration: precompiles/pointerview/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Price feed precompile Identifier: precompile-pricefeed Change in 7.0.0: unchanged Directory: precompiles/pricefeed Build command: ```sh go build ./precompiles/pricefeed/... ``` Build output: registered in build/paxd Configuration: precompiles/pricefeed/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Solo precompile Identifier: precompile-solo Change in 7.0.0: unchanged Directory: precompiles/solo Build command: ```sh go build ./precompiles/solo/... ``` Build output: registered in build/paxd Configuration: precompiles/solo/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Spot precompiles Identifier: precompile-spot Change in 7.0.0: unchanged Directory: precompiles/spot Build command: ```sh go build ./precompiles/spot/... ``` Build output: registered in build/paxd Configuration: precompiles/spot/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Staking precompile Identifier: precompile-staking Change in 7.0.0: unchanged Directory: precompiles/staking Build command: ```sh go build ./precompiles/staking/... ``` Build output: registered in build/paxd Configuration: precompiles/staking/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### Wasm precompile Identifier: precompile-wasmd Change in 7.0.0: unchanged Directory: precompiles/wasmd Build command: ```sh go build ./precompiles/wasmd/... ``` Build output: registered in build/paxd Configuration: precompiles/wasmd/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ### XWeb precompile Identifier: precompile-xweb Change in 7.0.0: unchanged Directory: precompiles/xweb Build command: ```sh go build ./precompiles/xweb/... ``` Build output: registered in build/paxd Configuration: precompiles/xweb/abi.json and node/app.go Ports: None listed Health check: paxd status Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/precompiles](https://docs.paxeer.app/precompiles) Repository references: docs/system/precompiles.md, docs/site/paxeer-docs/src/app/precompiles/page.tsx ## service ### Hosted gateway Identifier: gateway Change in 7.0.0: changed Directory: services/platform/hosted/gateway Build command: ```sh cargo build --locked --release --manifest-path services/platform/Cargo.toml --package layerx-platform-gateway ``` Build output: services/platform/target/release/layerx-gateway Configuration: services/platform/hosted/gateway/deployment.yaml and README.md Ports: 9443 Health check: GET /readyz Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/services](https://docs.paxeer.app/services) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/services/page.tsx ### Explorer backend Identifier: explorer-backend Change in 7.0.0: changed Directory: services/explorer/backend Build command: ```sh mix release ``` Build output: _build/prod/rel/blockscout/bin/blockscout Configuration: services/explorer/backend/config/runtime.exs Ports: 4000 Health check: GET /api/healthz Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: See repository references. Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/explorer/ENVS.md ### Agent daemon Identifier: agent-daemon Change in 7.0.0: changed Directory: services/agent Build command: ```sh cargo build --locked --release --manifest-path services/agent/Cargo.toml --package layerx-agentd-host ``` Build output: services/agent/target/release/layerx-agentd Configuration: services/agent/crates/layerx-agentd README and environment variables Ports: 8790 Health check: GET /healthz Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/agent-runtime](https://docs.paxeer.app/agent-runtime) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/agent-runtime/page.tsx ### Interop workspace Identifier: interop Change in 7.0.0: changed Directory: services/interop Build command: ```sh cargo build --locked --release --manifest-path services/interop/Cargo.toml ``` Build output: services/interop/target/release binaries Configuration: services/interop/deploy and README.md Ports: None listed Health check: cargo run --manifest-path services/interop/Cargo.toml --bin layerx-interop-gateway -- --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/interop](https://docs.paxeer.app/interop) Repository references: services/interop/README.md, docs/site/paxeer-docs/src/app/interop/page.tsx ### Bridge relayer Identifier: bridge-relayer Change in 7.0.0: changed Directory: services/interop/crates/layerx-bridge-relayer Build command: ```sh cargo build --locked --release --manifest-path services/interop/Cargo.toml --bin layerx-bridge-relayer ``` Build output: services/interop/target/release/layerx-bridge-relayer Configuration: services/interop/deploy/bridge-relayer and contracts/bridge/README.md Ports: 8545 Health check: layerx-bridge-relayer --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [LayerX bridge module](https://docs.paxeer.app/system-map#system-module-layerx-bridge) Site pages: See repository references. Repository references: docs/release/7.0.0-service-operator-runbook.md, contracts/bridge/README.md ### Launchpad indexer Identifier: launchpad-indexer Change in 7.0.0: changed Directory: services/launchpad/indexer Build command: ```sh go build ./... ``` Build output: services/launchpad/indexer/indexerd Configuration: services/launchpad/indexer/internal/config/config.go Ports: 8080 Health check: GET /health/ready Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [LayerX chains module](https://docs.paxeer.app/system-map#system-module-layerx-chains) Site pages: [/launchpad](https://docs.paxeer.app/launchpad) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/launchpad/page.tsx ### Wallet gateway Identifier: wallet-gateway Change in 7.0.0: changed Directory: services/wallet/gateway Build command: ```sh pnpm --dir services/wallet --filter ./gateway build ``` Build output: services/wallet/gateway/dist Configuration: services/wallet/deploy/env and gateway/src/env.ts Ports: 8787 Health check: GET /health Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/accounts](https://docs.paxeer.app/accounts) Repository references: docs/wallet/service/cutover.md ### Human service Identifier: human-service Change in 7.0.0: unchanged Directory: services/human Build command: ```sh cargo build --locked --release --manifest-path services/human/Cargo.toml ``` Build output: services/human/target/release binaries Configuration: services/human/crates/layerx-human-service README.md Ports: 8080 Health check: GET /readyz Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/human-interface](https://docs.paxeer.app/human-interface) Repository references: services/human/README.md, docs/site/paxeer-docs/src/app/human-interface/page.tsx ### Bridge deployment service Identifier: service-bridge Change in 7.0.0: changed Directory: services/bridge Build command: ```sh bash services/bridge/deploy/checklist.sh --all ``` Build output: deployment validation output Configuration: services/bridge/deploy and contracts/bridge/README.md Ports: None listed Health check: bash services/bridge/deploy/checklist.sh --all Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [LayerX bridge module](https://docs.paxeer.app/system-map#system-module-layerx-bridge) Site pages: See repository references. Repository references: docs/release/7.0.0-service-operator-runbook.md, contracts/bridge/README.md ### Launchpad service workspace Identifier: service-launchpad Change in 7.0.0: changed Directory: services/launchpad Build command: ```sh make -C services/launchpad build ``` Build output: services/launchpad binaries Configuration: services/launchpad/Makefile and services/launchpad/indexer/internal/config/config.go Ports: PORT Health check: GET /health/ready Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [LayerX chains module](https://docs.paxeer.app/system-map#system-module-layerx-chains) Site pages: [/launchpad](https://docs.paxeer.app/launchpad) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/launchpad/page.tsx ### Platform hosted services Identifier: service-platform Change in 7.0.0: changed Directory: services/platform Build command: ```sh cargo build --locked --release --manifest-path services/platform/Cargo.toml ``` Build output: services/platform/target/release binaries Configuration: services/platform/hosted/gateway/README.md and deployment.yaml Ports: 9443 Health check: GET /readyz (HTTPS) Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/services](https://docs.paxeer.app/services) Repository references: docs/site/paxeer-docs/src/app/services/page.tsx, docs/release/7.0.0-service-operator-runbook.md ## application ### Bridge application Identifier: bridge Change in 7.0.0: changed Directory: apps/bridge Build command: ```sh pnpm --dir apps/bridge build ``` Build output: apps/bridge/.next Configuration: apps/bridge/src/lib/bridge/config.ts Ports: 3000 Health check: GET / Depends on: [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway), [Bridge relayer](https://docs.paxeer.app/system-map#system-bridge-relayer) Site pages: [/bridge](https://docs.paxeer.app/bridge) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/bridge/page.tsx ### Explorer application Identifier: explorer Change in 7.0.0: changed Directory: apps/explorer Build command: ```sh pnpm --dir apps/explorer build ``` Build output: apps/explorer/.next Configuration: apps/explorer/configs and docs/explorer/ENVS.md Ports: 3000 Health check: GET /api/healthz Depends on: [Explorer backend](https://docs.paxeer.app/system-map#system-explorer-backend) Site pages: [/services](https://docs.paxeer.app/services) Repository references: docs/release/7.0.0-service-operator-runbook.md ### Inference peer Identifier: inference-peer Change in 7.0.0: unchanged Directory: apps/inference-peer Build command: ```sh npm --prefix apps/inference-peer test ``` Build output: apps/inference-peer/engine Configuration: apps/inference-peer/package.json Ports: 8787 Health check: npm --prefix apps/inference-peer test Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/agents](https://docs.paxeer.app/agents) Repository references: docs/site/paxeer-docs/src/app/agents/page.tsx ### Launchpad web application Identifier: launchpad Change in 7.0.0: changed Directory: apps/launchpad/web Build command: ```sh pnpm --dir apps/launchpad/web build ``` Build output: apps/launchpad/web/.next Configuration: apps/launchpad/web/src/core/rpc.ts Ports: 3000 Health check: GET / Depends on: [Launchpad indexer](https://docs.paxeer.app/system-map#system-launchpad-indexer), [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/launchpad](https://docs.paxeer.app/launchpad) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/launchpad/page.tsx ### Names application Identifier: names Change in 7.0.0: unchanged Directory: apps/names Build command: ```sh pnpm --dir apps/names build ``` Build output: apps/names/.next Configuration: apps/names/package.json Ports: 3000 Health check: GET / Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md ### Paxeer Xtrades application Identifier: perps Change in 7.0.0: changed Directory: apps/perps Build command: ```sh pnpm --dir apps/perps build ``` Build output: apps/perps/apps/web/.next-production Configuration: apps/perps/apps/web/next.config.js, apps/perps/deploy and package.json Ports: 3000 Health check: GET /api/build-id Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/perpetuals](https://docs.paxeer.app/perpetuals) Repository references: apps/perps/README.md, docs/site/paxeer-docs/src/app/perpetuals/page.tsx, docs/perps/data-api.md ### Wallet application Identifier: wallet Change in 7.0.0: changed Directory: apps/wallet Build command: ```sh pnpm --dir apps/wallet build ``` Build output: apps/wallet/.next Configuration: apps/wallet/src/account/config.ts Ports: 3000 Health check: GET / Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/accounts](https://docs.paxeer.app/accounts) Repository references: docs/release/7.0.0-service-operator-runbook.md ### Human web application Identifier: human-web Change in 7.0.0: unchanged Directory: apps/web Build command: ```sh npm --prefix apps/web run build ``` Build output: apps/web/.next Configuration: apps/web/package.json and docs/platform/site.kvx Ports: 3000 Health check: GET / Depends on: [Human service](https://docs.paxeer.app/system-map#system-human-service) Site pages: [/human-interface](https://docs.paxeer.app/human-interface) Repository references: docs/site/paxeer-docs/src/app/human-interface/page.tsx, docs/platform/content/index.md ### Bridge application Identifier: app-bridge Change in 7.0.0: changed Directory: apps/bridge Build command: ```sh pnpm --dir apps/bridge build ``` Build output: apps/bridge/.next Configuration: apps/bridge/src/lib/bridge/config.ts Ports: 3000 Health check: GET / Depends on: [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/bridge](https://docs.paxeer.app/bridge) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/bridge/page.tsx ### Explorer application Identifier: app-explorer Change in 7.0.0: changed Directory: apps/explorer Build command: ```sh pnpm --dir apps/explorer build ``` Build output: apps/explorer/.next Configuration: apps/explorer/configs and docs/explorer/ENVS.md Ports: 3000 Health check: GET /api/healthz Depends on: [Explorer backend](https://docs.paxeer.app/system-map#system-explorer-backend) Site pages: [/services](https://docs.paxeer.app/services) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/services/page.tsx ### Launchpad web application Identifier: app-launchpad Change in 7.0.0: changed Directory: apps/launchpad/web Build command: ```sh pnpm --dir apps/launchpad/web build ``` Build output: apps/launchpad/web/.next Configuration: apps/launchpad/web/src/core/rpc.ts Ports: 3000 Health check: GET / Depends on: [Launchpad indexer](https://docs.paxeer.app/system-map#system-launchpad-indexer), [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/launchpad](https://docs.paxeer.app/launchpad) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/launchpad/page.tsx ### Wallet application Identifier: app-wallet Change in 7.0.0: changed Directory: apps/wallet Build command: ```sh pnpm --dir apps/wallet build ``` Build output: apps/wallet/.next Configuration: apps/wallet/src/account/config.ts Ports: 3000 Health check: GET / Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node), [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/accounts](https://docs.paxeer.app/accounts) Repository references: docs/release/7.0.0-service-operator-runbook.md, docs/site/paxeer-docs/src/app/accounts/page.tsx ### Human web application Identifier: app-web Change in 7.0.0: unchanged Directory: apps/web Build command: ```sh npm --prefix apps/web run build ``` Build output: apps/web/.next Configuration: apps/web/package.json Ports: 3000 Health check: GET / Depends on: [Human service](https://docs.paxeer.app/system-map#system-human-service) Site pages: [/human-interface](https://docs.paxeer.app/human-interface) Repository references: docs/platform/content/index.md, docs/site/paxeer-docs/src/app/human-interface/page.tsx ### Inference peer Identifier: app-inference-peer Change in 7.0.0: unchanged Directory: apps/inference-peer Build command: ```sh npm --prefix apps/inference-peer test ``` Build output: apps/inference-peer/engine Configuration: apps/inference-peer/scripts/serve.mjs Ports: 8787 Health check: GET /probe Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/agents](https://docs.paxeer.app/agents) Repository references: docs/site/paxeer-docs/src/app/agents/page.tsx ### Names application Identifier: app-names Change in 7.0.0: unchanged Directory: apps/names Build command: ```sh pnpm --dir apps/names build ``` Build output: apps/names/.next Configuration: apps/names/package.json Ports: 3000 Health check: GET / Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: See repository references. Repository references: docs/system/sdk.md Additional inventory reference: /names (no published site page) ## sdk ### Wallet SDK Identifier: wallet-sdk Change in 7.0.0: changed Directory: sdk/wallet Build command: ```sh pnpm --dir sdk/wallet build ``` Build output: sdk/wallet/dist Configuration: sdk/wallet/package.json Ports: None listed Health check: package exports load Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Cosmos TypeScript SDK Identifier: cosmos-sdk Change in 7.0.0: unchanged Directory: sdk/js Build command: ```sh npm --prefix sdk/js test ``` Build output: sdk/js/dist Configuration: sdk/js/package.json Ports: None listed Health check: node --test sdk/js/test/ Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Names SDK Identifier: names-sdk Change in 7.0.0: unchanged Directory: sdk/names Build command: ```sh pnpm --dir sdk/names build ``` Build output: sdk/names/dist Configuration: sdk/names/package.json Ports: None listed Health check: package exports load Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Agent TypeScript SDK Identifier: agent-sdk Change in 7.0.0: changed Directory: services/agent/sdk/typescript Build command: ```sh npm --prefix services/agent/sdk/typescript run build ``` Build output: services/agent/sdk/typescript/dist Configuration: services/agent/sdk/typescript/package.json Ports: None listed Health check: package exports load Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon), [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Chainflow data SDK Identifier: chainflow-sdk Change in 7.0.0: unchanged Directory: sdk/chainflow/typescript Build command: ```sh npm --prefix sdk/chainflow/typescript run build ``` Build output: sdk/chainflow/typescript/dist Configuration: sdk/chainflow/typescript/pyproject.toml and package.json Ports: None listed Health check: package exports load Depends on: None Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Programs Rust SDK Identifier: program-rust-sdk Change in 7.0.0: changed Directory: programs/sdk/rust Build command: ```sh cargo build --locked --manifest-path programs/sdk/rust/Cargo.toml ``` Build output: programs/sdk/rust/target artifacts Configuration: programs/sdk/rust/Cargo.toml Ports: None listed Health check: cargo test --manifest-path programs/sdk/rust/Cargo.toml Depends on: [LayerX kernel host](https://docs.paxeer.app/system-map#system-kernel) Site pages: [/programs](https://docs.paxeer.app/programs) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/programs/page.tsx ### Programs AssemblyScript SDK Identifier: program-assemblyscript-sdk Change in 7.0.0: unchanged Directory: programs/sdk/assemblyscript Build command: ```sh npm --prefix programs/sdk/assemblyscript pack --dry-run ``` Build output: programs/sdk/assemblyscript/package archive Configuration: programs/sdk/assemblyscript/package.json Ports: None listed Health check: package exports load Depends on: [LayerX kernel host](https://docs.paxeer.app/system-map#system-kernel) Site pages: [/programs](https://docs.paxeer.app/programs) Repository references: docs/site/paxeer-docs/src/app/programs/page.tsx ### Agent Python SDK Identifier: agent-python-sdk Change in 7.0.0: changed Directory: services/agent/sdk/python Build command: ```sh python3 -m build services/agent/sdk/python ``` Build output: services/agent/sdk/python/dist Configuration: services/agent/sdk/python/pyproject.toml Ports: None listed Health check: python3 -m build services/agent/sdk/python Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md ### Agent JVM SDK Identifier: agent-jvm-sdk Change in 7.0.0: unchanged Directory: sdk/platform/jvm Build command: ```sh mvn -f sdk/platform/jvm/pom.xml package ``` Build output: sdk/platform/jvm/target/*.jar Configuration: sdk/platform/jvm/pom.xml Ports: None listed Health check: mvn -f sdk/platform/jvm/pom.xml test Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx, sdk/platform/jvm/README.md ### Agent .NET SDK Identifier: agent-dotnet-sdk Change in 7.0.0: unchanged Directory: sdk/platform/dotnet Build command: ```sh dotnet build sdk/platform/dotnet/LayerX.Sdk.csproj ``` Build output: sdk/platform/dotnet/bin and obj Configuration: sdk/platform/dotnet/LayerX.Sdk.csproj Ports: None listed Health check: dotnet build sdk/platform/dotnet/LayerX.Sdk.csproj Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/platform/content/quickstart/csharp.md ### Agent Swift SDK Identifier: agent-swift-sdk Change in 7.0.0: unchanged Directory: sdk/platform/swift Build command: ```sh swift build --package-path sdk/platform/swift ``` Build output: sdk/platform/swift/.build Configuration: sdk/platform/swift/Package.swift Ports: None listed Health check: swift test --package-path sdk/platform/swift Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/platform/content/quickstart/swift.md ### Chainflow Go SDK Identifier: chainflow-go-sdk Change in 7.0.0: unchanged Directory: sdk/chainflow/go Build command: ```sh go build ./... ``` Build output: Go package artifacts Configuration: sdk/chainflow/go/go.mod Ports: None listed Health check: go test ./... Depends on: None Site pages: See repository references. Repository references: sdk/chainflow/go/README.md ### Chainflow Python SDK Identifier: chainflow-python-sdk Change in 7.0.0: unchanged Directory: sdk/chainflow/python Build command: ```sh python3 -m build sdk/chainflow/python ``` Build output: sdk/chainflow/python/dist Configuration: sdk/chainflow/python/pyproject.toml Ports: None listed Health check: python3 -m build sdk/chainflow/python Depends on: None Site pages: See repository references. Repository references: docs/perps/data-api.md, sdk/chainflow/python/README.md ### Chainflow Rust SDK Identifier: chainflow-rust-sdk Change in 7.0.0: unchanged Directory: sdk/chainflow/rust Build command: ```sh cargo build --locked --release --manifest-path sdk/chainflow/rust/Cargo.toml ``` Build output: sdk/chainflow/rust/target artifacts Configuration: sdk/chainflow/rust/Cargo.toml Ports: None listed Health check: cargo test --manifest-path sdk/chainflow/rust/Cargo.toml Depends on: None Site pages: See repository references. Repository references: docs/perps/data-api.md, sdk/chainflow/rust/README.md ### Wallet SDK Identifier: sdk-wallet Change in 7.0.0: changed Directory: sdk/wallet Build command: ```sh pnpm --dir sdk/wallet build ``` Build output: sdk/wallet/dist Configuration: sdk/wallet/package.json Ports: None listed Health check: package exports load Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Cosmos TypeScript SDK Identifier: sdk-cosmos Change in 7.0.0: unchanged Directory: sdk/js Build command: ```sh npm --prefix sdk/js test ``` Build output: sdk/js/dist Configuration: sdk/js/package.json Ports: None listed Health check: package exports load Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Names SDK Identifier: sdk-names Change in 7.0.0: unchanged Directory: sdk/names Build command: ```sh pnpm --dir sdk/names build ``` Build output: sdk/names/dist Configuration: sdk/names/package.json Ports: None listed Health check: package exports load Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Agent TypeScript SDK Identifier: sdk-agent-typescript Change in 7.0.0: changed Directory: services/agent/sdk/typescript Build command: ```sh npm --prefix services/agent/sdk/typescript run build ``` Build output: services/agent/sdk/typescript/dist Configuration: services/agent/sdk/typescript/package.json Ports: None listed Health check: package exports load Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/sdk/page.tsx ### Programs Rust SDK Identifier: sdk-program-rust Change in 7.0.0: changed Directory: programs/sdk/rust Build command: ```sh cargo build --locked --release --manifest-path programs/Cargo.toml -p layerx-program-sdk ``` Build output: programs/target/release/deps Configuration: programs/sdk/rust/Cargo.toml Ports: None listed Health check: cargo test --manifest-path programs/sdk/rust/Cargo.toml Depends on: [LayerX kernel host](https://docs.paxeer.app/system-map#system-kernel) Site pages: [/programs](https://docs.paxeer.app/programs) Repository references: docs/system/sdk.md, docs/site/paxeer-docs/src/app/programs/page.tsx ### Programs AssemblyScript SDK Identifier: sdk-program-assemblyscript Change in 7.0.0: changed Directory: programs/sdk/assemblyscript Build command: ```sh npm --prefix programs/sdk/assemblyscript run test:source ``` Build output: programs/sdk/assemblyscript/build/safety.wasm Configuration: programs/sdk/assemblyscript/package.json Ports: None listed Health check: package exports load Depends on: [LayerX kernel host](https://docs.paxeer.app/system-map#system-kernel) Site pages: [/programs](https://docs.paxeer.app/programs) Repository references: docs/site/paxeer-docs/src/app/programs/page.tsx ### Chainflow TypeScript SDK Identifier: sdk-chainflow-typescript Change in 7.0.0: unchanged Directory: sdk/chainflow/typescript Build command: ```sh npm --prefix sdk/chainflow/typescript run build ``` Build output: sdk/chainflow/typescript/dist Configuration: sdk/chainflow/typescript/package.json Ports: None listed Health check: package exports load Depends on: [Hosted gateway](https://docs.paxeer.app/system-map#system-gateway) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Chainflow Go SDK Identifier: sdk-chainflow-go Change in 7.0.0: unchanged Directory: sdk/chainflow/go Build command: ```sh go build ./... ``` Build output: Go package artifacts Configuration: sdk/chainflow/go/go.mod Ports: None listed Health check: go test ./... Depends on: None Site pages: See repository references. Repository references: sdk/chainflow/go/README.md ### Chainflow Python SDK Identifier: sdk-chainflow-python Change in 7.0.0: unchanged Directory: sdk/chainflow/python Build command: ```sh python3 -m build sdk/chainflow/python ``` Build output: sdk/chainflow/python/dist Configuration: sdk/chainflow/python/pyproject.toml Ports: None listed Health check: python3 -m build sdk/chainflow/python Depends on: None Site pages: See repository references. Repository references: docs/perps/data-api.md, sdk/chainflow/python/README.md ### Chainflow Rust SDK Identifier: sdk-chainflow-rust Change in 7.0.0: unchanged Directory: sdk/chainflow/rust Build command: ```sh cargo build --locked --release --manifest-path sdk/chainflow/rust/Cargo.toml ``` Build output: sdk/chainflow/rust/target artifacts Configuration: sdk/chainflow/rust/Cargo.toml Ports: None listed Health check: cargo test --manifest-path sdk/chainflow/rust/Cargo.toml Depends on: None Site pages: See repository references. Repository references: docs/perps/data-api.md, sdk/chainflow/rust/README.md ### Agent JVM SDK Identifier: sdk-agent-jvm Change in 7.0.0: unchanged Directory: sdk/platform/jvm Build command: ```sh mvn -f sdk/platform/jvm/pom.xml package ``` Build output: sdk/platform/jvm/target/*.jar Configuration: sdk/platform/jvm/pom.xml Ports: None listed Health check: mvn -f sdk/platform/jvm/pom.xml test Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Agent .NET SDK Identifier: sdk-agent-dotnet Change in 7.0.0: unchanged Directory: sdk/platform/dotnet Build command: ```sh dotnet build sdk/platform/dotnet/LayerX.Sdk.csproj ``` Build output: sdk/platform/dotnet/bin and obj Configuration: sdk/platform/dotnet/LayerX.Sdk.csproj Ports: None listed Health check: dotnet build sdk/platform/dotnet/LayerX.Sdk.csproj Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Agent Swift SDK Identifier: sdk-agent-swift Change in 7.0.0: unchanged Directory: sdk/platform/swift Build command: ```sh swift build --package-path sdk/platform/swift ``` Build output: sdk/platform/swift/.build Configuration: sdk/platform/swift/Package.swift Ports: None listed Health check: swift test --package-path sdk/platform/swift Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ### Agent Go SDK Identifier: sdk-agent-go Change in 7.0.0: unchanged Directory: sdk/platform/go Build command: ```sh cd sdk/platform/go && go build ./... ``` Build output: Go package artifacts Configuration: sdk/platform/go/go.mod Ports: None listed Health check: go test ./... Depends on: [Agent daemon](https://docs.paxeer.app/system-map#system-agent-daemon) Site pages: [/sdk](https://docs.paxeer.app/sdk) Repository references: docs/site/paxeer-docs/src/app/sdk/page.tsx ## tool ### Release tools Identifier: release-tools Change in 7.0.0: changed Directory: tools/release Build command: ```sh python3 tools/release/upgrade_info.py --help ``` Build output: command output and validated plan-info Configuration: tools/release/version.json and tools/release/upgrade_info.py Ports: None listed Health check: python3 tools/release/upgrade_info.py --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: See repository references. Repository references: docs/release/7.0.0-upgrade-plan.md, docs/release/7.0.0-validator-runbook.md ### Paxctl operator CLI Identifier: paxctl Change in 7.0.0: changed Directory: tools/paxctl Build command: ```sh make -C tools/paxctl build ``` Build output: tools/paxctl/bin/paxctl Configuration: tools/paxctl/README.md Ports: None listed Health check: paxctl --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/cli](https://docs.paxeer.app/cli) Repository references: docs/site/paxeer-docs/src/app/cli/page.tsx ### LayerX developer CLI Identifier: layerx-cli Change in 7.0.0: changed Directory: tools/platform/cli Build command: ```sh cargo build --locked --release --manifest-path tools/platform/Cargo.toml --package layerx-platform-cli ``` Build output: tools/platform/target/release/layerx Configuration: tools/platform/cli/src/config.rs Ports: None listed Health check: layerx --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/cli](https://docs.paxeer.app/cli) Repository references: docs/system/cli.md, docs/site/paxeer-docs/src/app/cli/page.tsx ### Wasm tools Identifier: wasm-tools Change in 7.0.0: unchanged Directory: tools/wasm-tools Build command: ```sh cargo build --locked --release --manifest-path tools/wasm-tools/Cargo.toml ``` Build output: tools/wasm-tools/target/release binaries Configuration: tools/wasm-tools/Cargo.toml Ports: None listed Health check: cargo run --manifest-path tools/wasm-tools/Cargo.toml -- --help Depends on: [LayerX kernel host](https://docs.paxeer.app/system-map#system-kernel) Site pages: [/wasm](https://docs.paxeer.app/wasm) Repository references: docs/site/paxeer-docs/src/app/wasm/page.tsx ### Load test tool Identifier: loadtest Change in 7.0.0: unchanged Directory: tools/loadtest Build command: ```sh make -C tools/loadtest build ``` Build output: tools/loadtest/bin artifacts Configuration: tools/loadtest/config Ports: None listed Health check: loadtest --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/debugging-transactions](https://docs.paxeer.app/debugging-transactions) Repository references: docs/site/paxeer-docs/src/app/debugging-transactions/page.tsx ### System documentation generator Identifier: docs-generator Change in 7.0.0: unchanged Directory: tools/docs Build command: ```sh bash tools/docs/gen-system-docs.sh ``` Build output: docs/system generated pages Configuration: tools/docs/gen-system-docs.sh Ports: None listed Health check: bash tools/docs/gen-system-docs.sh --check Depends on: None Site pages: See repository references. Repository references: docs/system/INDEX.md ### Node bring-up tool Identifier: bringup Change in 7.0.0: changed Directory: tools/bringup Build command: ```sh go build ./tools/bringup/... ``` Build output: tools/bringup binaries Configuration: tools/bringup/cmd Ports: None listed Health check: bringup --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/installation](https://docs.paxeer.app/installation) Repository references: docs/site/paxeer-docs/src/app/installation/page.tsx ### Release rollback tool Identifier: rollback-tool Change in 7.0.0: changed Directory: tools/release Build command: ```sh bash tools/release/rollback.sh --help ``` Build output: rollback command Configuration: tools/release/rollback.sh Ports: None listed Health check: bash tools/release/rollback.sh --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: See repository references. Repository references: docs/release/7.0.0-upgrade-plan.md ### Backup and monitoring tools Identifier: operations Change in 7.0.0: changed Directory: tools/ops Build command: ```sh bash tools/ops/monitoring/render.sh ``` Build output: tools/ops/monitoring/rendered configurations Configuration: tools/ops/monitoring and tools/ops/backup Ports: 9090, 9093 Health check: python3 tools/ops/monitoring/readiness.py --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/network-operations](https://docs.paxeer.app/network-operations) Repository references: docs/release/7.0.0-validator-runbook.md, docs/site/paxeer-docs/src/app/network-operations/page.tsx ### Backup and restore tools Identifier: backup-tools Change in 7.0.0: unchanged Directory: tools/ops/backup Build command: ```sh bash tools/ops/backup/backup.sh --help ``` Build output: backup archives and checkpoint metadata Configuration: tools/ops/backup/backup.env.example Ports: None listed Health check: systemctl status paxeer-backup.timer Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/network-operations](https://docs.paxeer.app/network-operations) Repository references: docs/release/7.0.0-validator-runbook.md, docs/site/paxeer-docs/src/app/network-operations/page.tsx ### Monitoring stack Identifier: monitoring-tools Change in 7.0.0: changed Directory: tools/ops/monitoring Build command: ```sh bash tools/ops/monitoring/render.sh ``` Build output: rendered monitoring configuration Configuration: tools/ops/monitoring/prometheus.yml, rules.yml and blackbox.yml Ports: 9090, 9093 Health check: GET /-/ready (Prometheus) Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/network-operations](https://docs.paxeer.app/network-operations) Repository references: docs/release/7.0.0-validator-runbook.md, docs/site/paxeer-docs/src/app/network-operations/page.tsx ### Paxeer load generator Identifier: paxload Change in 7.0.0: unchanged Directory: tools/loadtest Build command: ```sh make -C tools/loadtest build ``` Build output: tools/loadtest/build/paxload Configuration: tools/loadtest/config and profiles Ports: None listed Health check: paxload --help Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/operators](https://docs.paxeer.app/operators) Repository references: docs/site/paxeer-docs/src/app/operators/page.tsx ### Cosmovisor supervisor Identifier: cosmovisor Change in 7.0.0: unchanged Directory: sdk/cosmovisor Build command: ```sh make -C sdk/cosmovisor ``` Build output: sdk/cosmovisor/cosmovisor Configuration: sdk/cosmovisor/README.md Ports: None listed Health check: cosmovisor version Depends on: [Paxeer chain node](https://docs.paxeer.app/system-map#system-chain-node) Site pages: [/operators](https://docs.paxeer.app/operators) Repository references: docs/release/7.0.0-validator-runbook.md, docs/site/paxeer-docs/src/app/operators/page.tsx --- URL: https://docs.paxeer.app/unified-network # Unified Network Architecture The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit each block. ## The Network Model Paxeer X uses EVM chain ID `125` (`0x7d`). The node binary `paxd` runs the Cosmos SDK application and native EVM. The LayerX kernel runs in-process inside `paxd` through `modules/lxphost`, executes and orders each transaction, gives it the next position in one global sequence, and returns a signed execution receipt. `node/sequencer` supplies execution ordering within the node. Kernel state changes commit with the rest of the node's transaction state. A receipt is final once its block is committed. Applications establish finality from the committed block and the receipt's inclusion evidence. Sub-chains are tenant domains stored in the database and managed by `modules/layerxchains`. Creating a domain namespaces state within the shared network. It does not require new node infrastructure. ## State and Authority | State | Authoritative owner | How applications use it | | --- | --- | --- | | EVM contracts and Cosmos balances | Paxeer application state committed by chain consensus | Contract calls, transactions, native modules and registered token pointers | | Agent identities and delegated authority | LayerX identity kernel | DIDs, primary keys, sessions, scoped grants, recovery and revocation | | Economic activity and balances | Kernel state committed in `paxd` blocks | Receipts, replay, module queries and state witnesses | | Receipt finality | Committed block | `pax_sequencerReceipt` rungs: `submitted`, `receipted`, `committed` | | Tenant domains | `modules/layerxchains` | Namespaced state within the shared network | | Indexes and user interfaces | Projections of committed evidence | Search, account history and operational views, with receipts retained for verification | An address binding identifies the same participant across the EVM and LayerX identity systems. Grants still determine the actions that participant or its delegates can perform. A verified signature establishes who signed evidence. Authorization and application policy establish whether that evidence is acceptable for a specific operation. ## From Intent to Committed Activity ### Canonical Signed Activities A LayerX state change uses a canonical binary envelope containing protocol and network identifiers, activity type, actor DID, authority, account sequence, timestamp bounds, idempotency key, fee limit, payload binding, and signature. Fixed-width integers and canonical decoding keep independent executors in agreement. Time checks use the batch timestamp. The kernel resolves authority, checks sequence and payload integrity, computes the fee, and executes the module inside a state journal. Successful execution commits its effects. An admitted operation that fails rolls back module effects while still recording its fee, sequence, and receipt. An admission refusal consumes neither fee nor sequence. An idempotent retry returns the original receipt without repeating the economic effect. ### Receipts, Replay and State Roots Every admitted activity receives a global sequence and a signed receipt linked to the previous and resulting state roots. The node executes transactions before proposing them in receipt order. The signed receipt records execution. The committed block establishes finality. `pax_sequencerReceipt` distinguishes a known transaction without a receipt (`submitted`), a signed receipt awaiting commitment (`receipted`), and a receipt covered by the committed block's sequence batch (`committed`). The hosted gateway's `px_getReceiptKeys` method returns pinned node receipt keys. For independent verification, authenticate the block header and CometBFT commit, then verify transaction or state inclusion against the corresponding authenticated root. A successful submission or signed receipt alone must not be treated as a committed result. ## Native Precompiles Contracts reach native modules through `precompiles/`. The merge plan is `v7.0`. The thirteen merge entries are the five construct precompiles and eight agent-function precompiles in precompiles/setup.go. The table below also includes other native interfaces. Select the interface for the upgrade active at the queried height. | Precompile | Address suffix | Role | | --- | --- | --- | | Addr | `0x1004` | Resolve Paxeer and EVM identities; bind and resolve LayerX DIDs and unified accounts. | | Perps | `0x1015` | Perpetuals interface selected by the v6.12.0 precompile set in `node/precompiles_v6120.go`. | | LayerXBridge | `0x1016` | Mint and burn bridged assets under registered-chain, attestor, threshold and cap rules. | | Launchpad | `0x1017` | Token launch interface selected by the v6.12.0 precompile set. | | FeeToken / XWeb | `0x1018` / `0x1019` | Fee-token preferences and attested web requests, respectively. | | layerxledger, layerxpay, layerxauth, layerxprograms, layerxchains | `0x101A`–`0x101E` | Merge precompiles for ledger, payment, authorization, programs, and tenant domains. | | orob, clearing, oracle aggregator, pofq, scheduler, streams, tee attestor, eip712 | `0x0901`–`0x0908` | Remaining merge precompiles. | | Pricefeed and spot | `0x1020`–`0x1025` | `pricefeed` at `0x1020`; `spot_pecor`, `spot_orders`, `spot_stoporders`, `spot_quoter` and `spot_vault` at `0x1021`–`0x1025` in the v6.12.0 set. | Each suffix identifies a 20-byte address padded with leading zeros. See [Precompiles](https://docs.paxeer.app/precompiles) for contract interfaces. The served precompile set depends on the queried block height and module activation. Use the ABI in the matching `precompiles/` directory and check the target module's state before submitting a transaction. The node selects versioned implementations through `node/precompiles_v6120.go` and its merge activation gates. ## Unified Identity A LayerX identity is rendered as `did:layerx:` followed by its 32-byte Ed25519 public key in lowercase hexadecimal. The canonical main account name is `agent:did:layerx::main`. The address precompile resolves the EVM address, Paxeer address, DID key, and derived LayerX main account together. Binding requires both keys: the DID signs the binding domain, EVM chain ID, EVM address, and nonce; the EVM account submits the transaction. Bindings are one-to-one. Unbinding consumes a nonce, and previously signed binding messages cannot be replayed as a fresh association. ## Finality 1. **Submit:** A signed activity or transaction is known to the sequencer (`submitted`). 2. **Execute:** The kernel executes it and issues a signed receipt (`receipted`). 3. **Commit:** The block containing its sequence batch commits (`committed`). The receipt is final at this point. Finality depends on BFT block commitment. Keep the receipt, authenticated block header, commit, and inclusion evidence needed to verify the result. See [Checkpoints](https://docs.paxeer.app/checkpoints) and [Finality](https://docs.paxeer.app/finality) for the evidence boundaries. ## Developer and Service Boundaries EVM applications use Ethereum-compatible tooling and JSON-RPC. Public node namespaces are `debug`, `echo`, `eth`, `net`, `pax`, `test` and `txpool`. Method availability depends on node configuration. The hosted gateway exposes a separate `px_` API. Its deployment URL and credentials come from the operator. Gateway method availability does not follow from public node URLs. Workflows carry the actor identity, intended action, and resulting evidence through routing, execution, and indexing. A unified experience can present one account and one history while retaining the receipt and EVM transaction identifiers needed to audit each step. ## Build Across the Whole System - Compose agent commerce from identity, budgets, escrow, delivery attestations and receipt-backed payment. - Build programmable businesses with WASM programs, program-owned accounts and bounded spending grants. - Connect Solidity applications to verified agent execution and committed LayerX state. - Combine token launches, spot and perps activity, and external-chain assets under their own verification rules. Continue with [Paxeer X and LayerX](https://docs.paxeer.app/paxeer-vs-layerx), [Modules](https://docs.paxeer.app/modules), [Contracts](https://docs.paxeer.app/contracts), and [Consensus](https://docs.paxeer.app/consensus). --- URL: https://docs.paxeer.app/wasm-runtime # WASM Runtime Understand Paxeer’s in-tree CosmWasm virtual machine, Go and Rust boundary, native library builds, and gas accounting. **Source:** `wasm-runtime/` at the repository root, especially `lib.go`, `internal/api/`, and `libwasmvm/`. ## Runtime responsibilities The in-tree CosmWasm runtime connects the Go node to a Rust virtual machine through a C interface. It stores and compiles WebAssembly modules, caches them, and executes contract entry points with host callbacks for storage, addresses, queries, and gas. A contract developer compiles Rust into a `.wasm` artifact separately. The runtime's `StoreCode` compiles that WebAssembly into its execution representation; it does not accept Rust source. ## Package layout | Path | Responsibility | | --- | --- | | `lib.go` | CGO-enabled `VM`, cache lifetime, code storage, and contract entry points. | | `lib_no_cgo.go` | Shared types, Wasm checksum creation, and version API available without a VM execution build. | | `internal/api/` | C bindings, callbacks, memory ownership, iterators, and platform linker settings. | | `libwasmvm/` | Rust library and generated C header. | | `types/` | Environment, messages, query results, gas, storage, and IBC types shared across the boundary. | | `builders/` | Containerized native-library build definitions. | | `testdata/` | Compiled contracts used by runtime tests. | The node imports the local `wasm-runtime/` Go package as part of the root Go module. Use it with its matching native library and generated bindings. ## CGO and native libraries `lib.go` is guarded by the `cgo` build tag. Without CGO, checksum and shared-type utilities remain available, but the VM execution API is not compiled. `LibwasmvmVersion` explicitly returns an unavailable error when CGO is disabled. Linker files cover Linux glibc, Linux musl, macOS, Windows, and a system-library mode. Install the native library matching the node's operating system and architecture. | Build path | Relevant files or targets | | --- | --- | | Linux glibc | `link_glibclinux_x86_64.go`, `link_glibclinux_aarch64.go`, `release-build-linux` | | Linux musl | `link_muslc.go`, `release-build-alpine` | | macOS | `link_mac.go`, `link_mac_static.go`, macOS release targets | | Windows | `link_windows.go`, `release-build-windows` | | System library | `link_system.go` and its `sys_wasmvm` build selection | ## Building the runtime Use the node's [installation guide](https://docs.paxeer.app/installation) to build Paxeer. When changing the runtime itself, its local Makefile has separate Rust and Go targets. Run these from the repository root: ``` # Build the native release library and refresh the generated C bindings. make -C wasm-runtime build-rust-release # Build the Go packages and demo against the native library. make -C wasm-runtime build-go # Run the runtime's Go test suite with the actual native library. make -C wasm-runtime test ``` The Rust target copies the compiled library into `internal/api/` and updates `bindings.h`. It requires a working Rust and C toolchain. Containerized release targets build specific distribution artifacts; choose the target matching the node you will run. ## VM lifecycle and caching `NewVM` creates a cache using a data directory, supported capabilities, a per-execution memory limit, a debug-output setting, and a cache size. Call `Cleanup` when releasing a VM. `StoreCode` returns the checksum used for later instantiation and execution; `StoreCodeUnchecked` does the same while skipping static validation checks, so prefer `StoreCode` for untrusted bytecode. `Pin` and `Unpin` control retention in the memory cache. Code upload, contract instantiation, storage updates, and message dispatch are coordinated by the [CosmWasm module](https://docs.paxeer.app/wasm). Upload or instantiation permissions are module parameters, not a statement that the VM implementation is absent. ## Execution and gas The VM receives an environment, contract message bytes, storage and query callbacks, and gas limits. Its result carries contract data, emitted messages, and execution gas information back to the module. Host work also consumes gas through the supplied meter. When an EVM contract calls the wasmd precompile, the adapter maps the supplied EVM gas into the native execution meter and reports remaining gas. A read-only call made from another on-chain contract still consumes execution gas. Measure the complete call with its real payload and state instead of assuming a fixed gas cost for all CosmWasm operations. ## Runtime integration [WASM bindings](https://docs.paxeer.app/wasmbinding) add Paxeer-specific query and message handlers. [EVM precompiles](https://docs.paxeer.app/precompiles) expose selected runtime and native-module operations to Solidity. Their ABI and execution-context checks are part of the integration contract. --- URL: https://docs.paxeer.app/wasm # WASM CosmWasm contract lifecycle, deployment permissions, and calls between Paxeer’s EVM and WebAssembly runtimes. **Source:** `wasm/x/wasm/`, `precompiles/wasmd/`, and `node/wasmbinding/` at the repository root. ## Runtime and module Paxeer includes the CosmWasm module for storing WebAssembly code, instantiating contracts, executing messages, querying state, and performing authorized migrations. The [WASM runtime](https://docs.paxeer.app/wasm-runtime) executes compiled contract bytecode; the module supplies storage, account, bank, and message integration. Contract authors compile Rust to WebAssembly before upload. Contract messages and queries use the individual contract's JSON schema. Native coin amounts use base-denomination integers, such as `uhpx`. ## Check deployment permissions Upload access and default instantiation access are separate parameters. Query the network's current settings before deployment. Restricting new code upload does not by itself disable execution of existing contracts. ``` # Use the Cosmos RPC endpoint configured for your target node. paxd query params subspace wasm uploadAccess paxd query params subspace wasm instantiateAccess ``` These are the parameter keys in `wasm/x/wasm/types/params.go`. A particular code ID also carries its instantiation permissions. Check those permissions and the contract's administrator before an instantiate or migrate transaction. ## Contract lifecycle Set your node endpoint, Cosmos chain ID, and signer in the CLI configuration first. In these command templates, `INIT_JSON`, `EXECUTE_JSON`, and `QUERY_JSON` are shell variables containing JSON matching your contract; `CODE_ID` and `CONTRACT` come from confirmed transaction results. ADMIN is the chosen administrator address, NEW_CODE_ID identifies uploaded replacement code, and MIGRATE_JSON contains its migration message. ``` # Upload a compiled contract and record its confirmed code_id. paxd tx wasm store contract.wasm --from deployer --gas auto # Choose the administrator explicitly, or use --no-admin for no administrator. paxd tx wasm instantiate "$CODE_ID" "$INIT_JSON" \ --label "My contract" --admin "$ADMIN" --from deployer --gas auto # Execute an application message, then read the contract state. paxd tx wasm execute "$CONTRACT" "$EXECUTE_JSON" --from caller --gas auto paxd query wasm contract-state smart "$CONTRACT" "$QUERY_JSON" # An authorized administrator can migrate to an uploaded replacement code ID. paxd tx wasm migrate "$CONTRACT" "$NEW_CODE_ID" "$MIGRATE_JSON" \ --from admin --gas auto ``` `--amount` attaches native coins when a transaction requires them. Use denomination amounts such as `1000000uhpx`, not a decimal display amount or an EVM wei amount. ## Call CosmWasm from the EVM The precompile at `0x0000000000000000000000000000000000001002` exposes `instantiate`, `execute`, `execute_batch`, and `query`. Load `precompiles/wasmd/abi.json` from the node revision you target. Message and coin-list arguments are UTF-8 JSON encoded as bytes. An empty coin list is the JSON text `[]`, not empty bytes. CosmWasm targets use their `pax1...` contract addresses. ``` import { Contract, parseEther, toUtf8Bytes, toUtf8String } from 'ethers' // signer is your connected signer; wasmdAbi is the matching abi.json. const wasm = new Contract( '0x0000000000000000000000000000000000001002', wasmdAbi, signer, ) // Application-specific JSON comes from the target contract's schema. const queryResult = await wasm.query(contractAddress, toUtf8Bytes(JSON.stringify(queryMessage))) const decodedJson = JSON.parse(toUtf8String(queryResult)) // 1,000,000 uhpx corresponds to 10^18 wei of EVM value. const coins = toUtf8Bytes(JSON.stringify([{ denom: 'uhpx', amount: '1000000' }])) const tx = await wasm.execute( contractAddress, toUtf8Bytes(JSON.stringify(executeMessage)), coins, { value: parseEther('1') }, ) await tx.wait() ``` This execution example is a template for a contract message that accepts that payment. The JSON coin list must include the `uhpx` funded through EVM value: `value = uhpx amount × 10^12`. Omitting it or attaching a mismatched value reverts with `coin amount must equal value specified`. For `execute_batch`, the sum of the coin amounts across all calls must equal the value, and no value may remain after execution. Query returns raw contract response bytes; decode their hex representation before JSON parsing when the contract returns JSON. Execution may return arbitrary bytes. Transaction receipt log data is not automatically the function's return data; inspect documented events or query the resulting contract state. ## Call the EVM from CosmWasm Paxeer implements custom `call_evm` and `delegate_call_evm` messages, EVM static queries, token interfaces, and address lookups through [WASM bindings](https://docs.paxeer.app/wasmbinding). The implementation places additional limits on nested execution. Delegatecalling `instantiate` is refused outright. On the execution paths, a delegatecall is admitted only from the registered ERC-20, ERC-721, or ERC-1155 pointer of the target CosmWasm contract; any other calling contract is refused as not a pointer of that contract. Ordinary wrappers should use normal calls. ## Messages, storage, and gas Standard CosmWasm messages handle bank transfers, staking, distribution, and other contract calls; custom bindings add Paxeer-specific module operations. Each contract has isolated byte-keyed storage accessed through host callbacks. Runtime computation and host work consume gas, including when an EVM contract makes a CosmWasm query on-chain. Custom bindings provide a native Oracle query route for exchange rates and time-weighted prices. Read the [Oracle module guide](https://docs.paxeer.app/modules/oracle) for its query fields and available data. ## Implementation references - `wasm/x/wasm/client/cli/tx.go` and `query.go`: exact transaction and query commands. - `wasm/x/wasm/types/params.go`: upload and instantiation permission types. - `precompiles/wasmd/wasmd.go`: payment equality, context checks, batch execution, and return data. - `node/wasmbinding/encoder.go`: custom messages routed from CosmWasm. --- URL: https://docs.paxeer.app/wasmbinding # WASM Bindings Use Paxeer custom messages and queries from CosmWasm, including token creation, EVM calls, address association, and native module reads. **Source:** `node/wasmbinding/` at the repository root and each module's `client/wasm/` package. ## How bindings are registered `RegisterCustomPlugins` installs a custom message encoder and query router in the CosmWasm keeper. These bindings extend standard bank, staking, distribution, and Wasm messages. The package is Go node code; it is not a Rust crate to add to `Cargo.toml`. Contract-side types must serialize to the JSON forms below and implement the appropriate CosmWasm custom message or query traits. Use the schemas in this source revision when generating types or evaluating a client library. ## Custom messages `node/wasmbinding/encoder.go` dispatches these top-level message variants. Supply one operation per message. | Variant | Payload and behavior | | --- | --- | | `create_denom` | `subdenom`; creates a tokenfactory denomination under the calling contract. | | `mint_tokens` | `amount` coin object; subject to the denomination's mint authority. | | `burn_tokens` | `amount` coin object; executes the native tokenfactory burn path. | | `change_admin` | `denom` and `new_admin_address`; requires the current denomination administrator. | | `set_metadata` | Bank `metadata` object for the denomination. | | `set_denom_paused` | `denom` and an explicit `paused` boolean; a missing or null boolean is refused. | | `call_evm` | `to`, decimal-string integer `value`, and base64 `data`; dispatches an internal EVM call. | | `delegate_call_evm` | `to` and base64 `data`; carries calling-contract and code-hash context into the EVM delegate-call path. | ``` // JSON payload of a custom message, emitted by a CosmWasm contract: { "create_denom": { "subdenom": "credits" } } ``` The tokenfactory encoder and ordinary EVM-call encoder supply the contract as sender. The delegate-call encoder uses the incoming message sender when it is a valid Paxeer address and carries the emitting contract and code hash separately. ABI calldata bytes use base64 in the custom-message JSON; Ethereum `0x` hex strings must be decoded and re-encoded before use. ## Custom queries `PaxQueryWrapper` selects a route and embeds the route-specific JSON query in `query_data`. Unknown routes and unknown variants return errors. | Route | Implemented query families | | --- | --- | | `evm` | Static calls; ERC-20, ERC-721, and ERC-1155 reads; transfer and approval payload generation; interface support; EVM/Paxeer address lookups. | | `tokenfactory` | `denom_authority_metadata`, `denoms_from_creator`, and `denom_paused` (which reports the pause state and issuer DID for a denomination). | | `epoch` | `epoch` state. | | `stakingext` | `unbonding_delegations` for a supplied delegator. | | `oracle` | `exchange_rates` and `oracle_twaps` through the retained native Oracle handler. | ``` // Query the current epoch from inside a CosmWasm contract: { "route": "epoch", "query_data": { "epoch": {} } } ``` This is a custom querier payload, not an HTTP JSON-RPC request. It must be issued through the contract's CosmWasm query interface. ## Address lookup and token queries The EVM route exposes `get_pax_address` with `evm_address`, and `get_evm_address` with `pax_address`. Responses contain the resolved address and an `associated` flag. Check that flag before using the result as a linked account. ERC query fields are defined in `modules/evm/client/wasm/bindings/queries.go`. A transfer-payload query only produces encoded calldata; it does not transfer assets. Send the resulting calldata through a supported execution path when a transaction is intended. Keep native coin integers, ERC token decimals, and EVM wei values separate. Do not format a bank base-denomination amount using an unrelated ERC token's display precision. ## Execution boundaries CosmWasm-to-EVM calls are implemented. The corresponding [wasmd precompile](https://docs.paxeer.app/wasm) supports EVM-to-CosmWasm calls, with context and pointer checks. A non-query CosmWasm → EVM → CosmWasm loop is rejected; delegate-call messages should not be treated as unrestricted arbitrary execution. The native Oracle querier exposes exchange rates and time-weighted prices through this route. Check available denominations and observation freshness before using price data. See the [Oracle module guide](https://docs.paxeer.app/modules/oracle). ## Implementation references - `node/wasmbinding/wasm.go`: plugin registration. - `node/wasmbinding/encoder.go` and `message_plugin.go`: custom variants and module dispatch. - `node/wasmbinding/query_plugin.go` and `queries.go`: query wrapper, route selection, and handlers. - `modules/evm/client/wasm/encoder.go`: base64 decoding and internal EVM message construction. --- URL: https://docs.paxeer.app/webhooks # Webhooks Receive signed Paxeer X events with durable delivery, per-subject ordering, bounded retries, and cursor-based replay. Hosted webhooks deliver journey, payment, approval, and program events to your HTTPS receiver. Events and pending deliveries are persisted before transmission. Each endpoint has its own Ed25519 signing key, and retries preserve the event identifier and exact body bytes so your application can safely recognize repeats. ## Register an endpoint Use an active developer session with `Authorization: Bearer`, or the `__Host-layerx-session` cookie. Cookie-authenticated POST and DELETE requests also carry `x-layerx-csrf` matching the session CSRF token. Registration requires an `Idempotency-Key`. ``` POST /v1/webhooks/endpoints Authorization: Bearer Idempotency-Key: Content-Type: application/json { "url": "", "kinds": ["payment", "approval"], "minimum_verification": "unverified" } ``` The URL uses a canonical DNS name and resolves exclusively to public addresses. Literal IP destinations are refused. Each developer principal can register up to 32 endpoints. Registration returns the endpoint identifier, signing key identifier, public key, and receiver obligation. Preserve the returned key in your receiver's trusted key configuration. ## Event families and evidence | Kind | Resource and facts | Evidence | | --- | --- | --- | | `journey` | Journey identity, kind, state, updated time. | Source facts with optional activity receipt binding. | | `payment` | Activity identity, amount, asset, settled state. | Successful verified receipt for settlement; source amount and asset retain their own evidence labels. | | `approval` | Approval identity, agent, state, creation time. | Source facts with optional activity receipt binding. | | `program` | Program identity, lifecycle, version, code hash, receipt digest. | Source facts with optional activity receipt binding. | Webhook verification levels are `unverified`, `receipt-verified` and `block-committed`. Registering an endpoint with any other `minimum_verification` value is rejected as an invalid request. Each fact retains its own level; the event's aggregate verification uses the weakest fact. A payment event can therefore be unverified in aggregate while its settled-state fact carries receipt evidence. A minimum-verification filter applies to that aggregate level. Inspect and verify the facts your decision uses. ## Verify the raw delivery ``` layerx-webhook-id: layerx-webhook-timestamp: layerx-webhook-key-id: layerx-webhook-signature: v1= signed_message = UTF8(event_id + "." + timestamp + ".") || raw_body ``` 1. Validate bounded identifiers and canonical integer timestamp syntax. 2. Reject signatures older than the accepted age or too far in the future. Defaults are 300 seconds of age and 30 seconds of future skew. 3. Verify Ed25519 against the trusted public key named by the key identifier, over the exact incoming body bytes. 4. Claim the event identifier and payload digest in a durable replay store before applying business effects. 5. For economic effects, resolve and verify the referenced receipt and compare its digest to the event evidence. Read the body as raw bytes before JSON parsing. Re-serializing parsed JSON changes the signed message. Operational headers for delivery, attempt, kind, subject, sequence, and endpoint are outside the signature; use authenticated body fields for business decisions. `GET /v1/webhooks/scheme` publishes the receiver contract. ## Commit once, accept repeats Delivery is at least once. Store the event identifier with its payload digest and business outcome in the same transactional database as your application effects. A completed repeat returns success without repeating fulfilment; an in-progress claim waits or retries; the same identifier with a different digest is a conflict. Release an unsuccessful processing lease so a legitimate retry can proceed. The framework integrations provide verified webhook consumers and replay-store interfaces. An in-memory single-process store is useful for local execution; a durable shared store preserves deduplication across workers and restarts. ## Ordering, retries, and dead letters Events are ordered per subject, rather than globally across every resource. Publish rejects a non-advancing subject sequence. Delivery progresses through pending, in-flight, retrying, delivered, and dead-lettered. Only an accepting 2xx status from your endpoint marks a delivery delivered. | Default control | Value | | --- | --- | | Maximum attempts | 8 | | Initial retry delay | 10 seconds | | Maximum retry delay | 3,600 seconds | | Deterministic backoff spread | 20% | | In-flight lease | 120 seconds | | Automatic suspension | 20 consecutive dead letters | Backoff doubles up to its bound. Redirects are refused; HTTP 410 is a permanent failure. A permanent failure or exhausted attempts creates a dead letter. A suspended endpoint receives no dispatch until resumed. A lost worker's in-flight lease permits recovery without losing the persisted event. ## Manage delivery and replay | Method and path | Purpose | | --- | --- | | `GET /v1/webhooks/endpoints` | List endpoint registrations. | | `GET /v1/webhooks/endpoints/{id}/events` | Read endpoint event history and continuation cursor. | | `GET /v1/webhooks/endpoints/{id}/keys` | Read current and overlapping verification keys. | | `POST /v1/webhooks/endpoints/{id}/keys` | Rotate the signing key with an idempotency key. | | `POST /v1/webhooks/endpoints/{id}/redeliveries` | Enqueue replay from a signed cursor with an idempotency key. | | `POST /v1/webhooks/endpoints/{id}/suspensions` | Suspend an endpoint with a reason. | | `POST /v1/webhooks/endpoints/{id}/resumptions` | Resume delivery and clear consecutive dead-letter accounting. | | `GET /v1/webhooks/events`, `GET /v1/webhooks/deliveries`, `GET /v1/webhooks/dead-letters` | Inspect events and operational outcomes. | | `POST /v1/webhooks/dead-letters/{id}/replay` | Retry a dead letter with an idempotency key. | Pagination defaults to 50 items with a maximum of 200. Preserve cursors as opaque signed values. Expired retention returns `410 cursor_expired`; repair continuity using retained event and receipt history rather than silently assuming all events were delivered. Replay keeps the original event identifier and body digest. ## Rotate keys and monitor receivers Key rotation announces a pending public key before activation; the default overlap is 86,400 seconds. Configure the new public key during the overlap while retaining the old key for eligible deliveries. Signing private keys stay with the signing service. Monitor delivery latency, retry age, dead letters, suspension, and receiver signature failures. Return 2xx after durable acceptance. For long processing jobs, commit an inbox record and process it asynchronously. Use [agent subscriptions](https://docs.paxeer.app/subscriptions) for tenant-scoped streams with explicit acknowledgement and gap recovery. **Reference:** `services/platform/hosted/webhooks/src/main.rs` and its sibling files `hosted.rs`, `scheme.rs`, `events.rs`, `endpoints.rs`; endpoint management routes are in routes.rs in the same directory. --- URL: https://docs.paxeer.app/xdk # XDK developer toolkit Build Paxeer X applications in seven languages with native activities, human journeys, agent tools, exchange integrations, and local proof verification. ## Choose your integration plane XDK is the Paxeer X developer toolkit across native activities, payments, Programs, exchange operations, identity, and verifiable settlement. Package and import names use `layerx`; use the exact language identifiers below in your application. | Plane | Use it for | Entry points | | --- | --- | --- | | Node JSON-RPC | Signed EVM transaction submission, balances and receipt reads at the node root path. The `eth_*` namespace provides Ethereum methods; the EVM chain ID is `125`. | `eth_sendRawTransaction`, `eth_getBalance`, `pax_sequencerReceipt` | | Human API | User journeys with a quote, explicit approval, and an idempotent commit. | `move.quote` / `move.commit` | | Agent API | Daemon registration, policy-bound preparation, external signing, submission, and Programs. | `agent.register`, `prepare`, `submit`, `program.*` | | MCP | Tool calls from assistants through the same agent daemon gates. | [22 catalogue tools, plus 11 session tools in Full mode (33 total)](https://docs.paxeer.app/mcp) | | Offline verification | Independent signed-receipt and block-commitment evidence checks. | Language-specific local verifiers | The hosted gateway in `services/platform/hosted/gateway` serves `px_register` and `px_requestFunds`. Platform SDK receipt verifiers bind signed receipt bytes to the raw transaction and independently trusted receipt keys. That signature check reaches `receipted`; `committed` verification also requires authenticated block and inclusion evidence. The LayerX kernel inside paxd executes and orders each transaction and builds each block; validators check and commit it. A receipt is final when its block is committed. Rust `layerx-sdk` also exposes `production::verify_receipt` with an independently supplied `AuthorizedBatch`. ## Seven language SDKs | Language | Package | Payment entry point | Receipt verifier | | --- | --- | --- | --- | | Rust | `layerx-sdk` in services/agent/crates/layerx-sdk | `RpcClient::send_raw_transaction` | `production::verify_receipt` | | TypeScript | `@sidiora/layerx-sdk` in services/agent/sdk/typescript | `JsonRpcClient.sendRawTransaction`; `ProductionClient.human` | `verifySequencerReceipt` | | Python | `layerx-sdk` in services/agent/sdk/python | `PaymentRpc.send`; `ProductionClient.human` | `verify_sequencer_receipt` | | Go | `sdk/platform/go` | `Client.Human` | `VerifySequencerReceipt` | | JVM | `com.sidiora.layerx:layerx-sdk` in sdk/platform/jvm | `ProductionClient.human` | `LocalVerifier.verifySequencerReceipt` | | Swift | `LayerXSDK` in sdk/platform/swift | `humanMoveQuote` / `humanMoveCommit` | `LocalVerifier.verifySequencerReceipt` | | .NET | `LayerX.Sdk` in sdk/platform/dotnet | `HumanMoveQuoteAsync` / `HumanMoveCommitAsync` | `LocalVerifier.VerifySequencerReceipt` | ## Native and application API families | Family | Developer surface | | --- | --- | | Native activities | Canonical payload encoders, account derivation, fee estimation and signed EVM transaction submission. | | Programs | Program lifecycle, native program calls, transfer authority, call graphs, runtime terminals, and occupancy settlement. | | Spot and perpetuals | `encodeSpotActivity`, `decodeSpotActivity`, `encodePerpsActivity`, and `decodePerpsActivity` construct and inspect TypeScript native trading payloads. | | Exchange | ABI helpers and event decoders for exchange operations. Confirm the exact helper names in the SDK source for your language before use. | | Bridge | `bridgeInCall`, `bridgeOutCall`, and `decodeBridgeEvent` construct TypeScript bridge calls and decode bridge events. | | Launchpad | Launchpad market operations. Confirm the exact operations exposed by your language SDK in its source before use. | | Streams and mirrors | Streaming and mirror surfaces; see [streams](https://docs.paxeer.app/streams) and [mirrors](https://docs.paxeer.app/mirrors) for the documented behavior. | | XWeb and agent services | XWeb API, web search, native capabilities, gas-station support, and policy-aware transport interfaces. | ## Credentials, amounts, and retries Use Bearer identity sessions for authenticated human journeys. Hosted gateway activity submission uses a `LayerX-Key` credential with `activity:write`. Node JSON-RPC submits signed EVM transactions. Choose authentication for the service handling the operation. Keep secret material in `SecretBytes` or the language credential wrapper, and keep signing outside application logs. Use protocol integer amounts or decimal strings rather than floating point values. Attach a stable idempotency key to a business action and preserve it across retries. A submission result can be pending; poll or subscribe until the requested commitment is reached, then verify the receipt. ## Transport selection The generated operation catalog defines names and schemas; the transport determines the reachable plane. Human operations use their HTTP routes, and agent transports use the daemon envelope. Programs clients submit mutations as signed EVM transactions and read program state through node JSON-RPC. Go provides human and agent envelope HTTP transports; JVM transport accepts separate human and agent origins. Use the hosted gateway for principal registration and funding requests. Start with [SDK quickstarts](https://docs.paxeer.app/sdk-quickstarts), then continue to [MCP tools](https://docs.paxeer.app/mcp), [Programs](https://docs.paxeer.app/programs), and [public JSON-RPC](https://docs.paxeer.app/public-rpc). --- URL: https://docs.paxeer.app/xweb # Web Search and xweb Search the web, fetch content, and consume attested API results from agents and Solidity contracts. ## One Content Layer, Three Entry Points The `x-websearch` sidecar in services/interop/crates/x-websearch crawls an operator-defined seed list into its own Tantivy index and serves search, page extraction, and content-addressed retrieval. Agents pay for requests through 402LXP. Solidity contracts request attested results through the xweb precompile and read committed program results through the same interface. Each path identifies content with a canonical digest. | Consumer | Entry point | Result | | --- | --- | --- | | Agent | Paid sidecar HTTP routes, SDKs or MCP | Search results or extracted text, verified payment settlement and content digest | | Contract | `0x0000000000000000000000000000000000001019` | Attested response, digest, full length and bounded callback | | Program result reader | `IXWeb.getProgramResult` / xweb keeper `GetProgramResult` | A committed program observation. Use the committed-result views; the kernel host disables in-program `web_read`. | ## Search and Fetch for Agents | Route | Payment | Response | | --- | --- | --- | | `GET /health` | None | Sidecar health | | `GET /search?q=` | 402LXP | At most ten results with URL, title and snippet, plus the content digest | | `GET /fetch?url=` | 402LXP | Requested and final URL, media type, extracted text, full length and digest | | `GET /content/` | None | Canonical bytes identified by a 64-character hexadecimal digest | Search results sort by descending score and then ascending URL. Fetch accepts HTTP and HTTPS, honors robots.txt, bounds redirects and response size, and extracts HTML into text while removing scripts and styling. Plain text and JSON pass through. The crawler respects page, host, depth and politeness budgets. ### The Payment Workflow 1. An unpaid request receives HTTP `402` and a `PAYMENT-REQUIRED` offer. 2. The agent chooses an exact-payment offer in SID, PAX, USDC or USDL and repeats the request with `PAYMENT-SIGNATURE`. 3. The sidecar submits settlement and verifies the sequencer-signed receipt against configured trust inputs. 4. Content is released with `PAYMENT-RESPONSE` and a transaction hash beginning `0x`. Pending settlement returns a retry response without releasing content. Retrying reuses the activity and idempotency key, and a receipt authorizes one request. Operators configure a positive per-request price in each asset's base units. The configured integer amount is the offered price. ## Content You Can Verify and Retrieve Canonicalization normalizes text encoding, line endings, whitespace and Unicode. The digest commits the domain `PAXEERX_WEB_CONTENT_V1`, request kind, URL or query, media type and canonical text. Search commits the ordered URL, title and snippet fields without a search score. Identical canonical inputs produce the same digest. Sidecars persist the canonical bytes before answering. Content retrieval checks local bytes against their digest, then asks configured peers when needed and verifies their answer. A peer request reads local storage without recursively forwarding. Contracts retain at most `4096` response bytes alongside the digest and full length; the digest path retrieves the complete canonical record. ## Request Web Data from Solidity The `IXWeb` interface in contracts/src/precompiles/IXWeb.sol exposes `request`, `fulfil`, `fulfilProgram`, `refund`, and views including `getProgramResult`, `getKernelNetworkId`, and views for requests, results, attestors, threshold, fee and parameters. Request kinds are `1` fetch, `2` search, and `3` API. A requester pays exactly the current `fee()` and declares its callback gas bound. ``` function onXWebResponse( uint64 requestId, bytes32 contentDigest, uint32 fullLength, bytes calldata response ) external; ``` Implement this callback and authenticate the xweb precompile as the caller. Associate the request ID with the operation that requested it. Inspect full length before treating a bounded response as complete. ### Attestation and Callback Outcomes Registered attestors fetch independently and sign evidence bound to the execution origin, network, requester, request ID, request kind, payload hash, content digest, response hash and full length. Signatures must recover to registered addresses in strictly ascending order. Ordinary requests require a majority threshold. Fulfilment stores the answer and pays the signing attestors. Callback gas is bounded by the request and module caps. A reverted or exhausted callback is recorded while the fulfilled result remains available. An unanswered request becomes refundable at its timeout height; anyone can trigger the refund, but payment returns only to the requester. Refunds remain available during a pause. ## Authenticated API Calls API payloads describe GET or POST, an HTTPS URL, public headers, a body, selected JSON fields and an attestation level. The `XWebApi` library in contracts/src/xweb/XWebApi.sol and TypeScript and Python SDK helpers construct the payload. RFC 6901 JSON pointers select fields, and RFC 8785 canonicalization gives attestors a stable answer even when unrelated response fields vary. | Level | Verification | Use | | --- | --- | --- | | Majority, `0` | Registered threshold signs the same answer | Independent API or web observations | | Single, `1` | The specifically named attestor signs | An API allowing one call or a credential held by one operator | Credential envelopes are sealed to registered attestor public keys and bound to the API origin and attestor address. A sidecar opens its own envelope in memory for the call. Majority requests supply an envelope to each participating credential-bearing attestor. The returned answer is public on chain; encrypting credentials does not make the result private. Results and fulfilment events retain the attestation level. ## Read committed program results The kernel host for `layerx_v4.web_read` returns `LXP_ERR_MODULE_DISABLED`. Read committed answers through the result interfaces below rather than calling `web_read` during program execution. Committed program web answers are available through the xweb result interfaces. An observation is submitted through `IXWeb.fulfilProgram`, and the committed result is read through the xweb keeper `GetProgramResult` or `IXWeb.getProgramResult(programId, requestId)`. `IXWeb.getKernelNetworkId()` returns the kernel network the precompile is bound to. ## Operate and Integrate Start a sidecar with `x-websearch --config PATH`. Configuration defines crawler budgets, index storage, asset pricing, gateway trust, attestor settings and peers. Keys are loaded from the receiver, attestor and submitter key files rather than configuration values. Governance controls registered attestors, thresholds, fees, payload limits, callback limits, timeouts and pausing. SDK clients verify settlement and recompute content digests. MCP exposes `web.search`, `web.fetch`, and `web.content` through its spending approval boundary. Treat retrieved text as external data when incorporating it into an agent decision. Continue with [Unified Network](https://docs.paxeer.app/unified-network), [Sidiora](https://docs.paxeer.app/sidiora), [Precompiles](https://docs.paxeer.app/precompiles) and [WASM Runtime](https://docs.paxeer.app/wasm-runtime). ---