XChain VM Component

The xchain-vm module is a standalone JavaScript library that executes smart contracts in deterministic, sandboxed V8 isolates. It is the runtime engine for the XChain smart contract layer — everything else (the DEPLOY/EXECUTE action handlers, database tables, gas fee logic) lives in the indexer.

What is xchain-vm

A pure function library. Takes contract code + state + inputs + block context. Returns new state + emitted actions + gas used. It has no awareness of the indexer, database, blockchain, or network. The indexer’s execute.js handler is the bridge between the VM and the platform.

Features

• Deterministic execution — identical results on every indexer node replaying the same block
• V8 sandbox isolation — contracts run in isolated-vm with a separate heap, no access to host process, filesystem, or network
• AST-based gas metering — acorn parses the source, injects __gas() at control flow points, astring regenerates — fully deterministic, not wall-clock
• JSON bridge protocol — host-side gateway functions communicate with the isolate via JSON-serialized arguments and type-prefixed return values
• 16 emittable action types — SEND, DESTROY, ISSUE, MINT, ORDER, DISPENSER, DIVIDEND, AIRDROP, CALLBACK, FILE, LIST, COINPAY, SWEEP, LINK, BROADCAST, MESSAGE
• External attestation gateway — xchain.attestation.request(...) and getResponse(...). Contracts ask an HTTPS endpoint or an approved LLM, and the validator network writes a signed answer back on-chain that re-enters the contract through a callback. See Smart Contracts — Attestation Framework.
• Contract-targeted staking gateway — xchain.contract.getStake, getTotalStaked, getStakers, slash. Any contract can declare itself stakeable at deploy time and slash its own stakers per its own rules. See Smart Contracts — Stakeable Contracts.
• Deterministic math — xchain.math.* wraps mathjs bignumber with string I/O, no floating-point at the gateway boundary
• Contract state management — key-value store with dirty tracking, key count, key size, and value size limits
• Deploy-time validation — V8 syntax check, acorn metering pass, reserved identifier detection, float warnings
• Per-block compilation cache — V8 cached compilation data reused for hot contracts within a block

Documentation

Installation

cd xchain-vm
npm install

isolated-vm requires native C++ compilation. On Debian/Ubuntu: build-essential, python3, libnghttp2-dev, libicu-dev, libbrotli-dev, libc-ares-dev.

Quick Start

const XChainVM = require('xchain-vm');

const vm = new XChainVM({
    gasSchedule: config['GAS_SCHEDULE'],
    gasCeiling:  1000000,
    limits: {
        maxCpuTimeMs:      30000,
        maxMemory:         8,
        maxEmissions:      50,
        maxStateKeys:      10000,
        maxStateValueSize: 65536,
        maxCodeSize:       65536,
        maxStateKeySize:   1024,
        maxBlockCacheSize: 1000
    }
});

const result = await vm.execute({
    code:               contractCode,
    state:              contractState,
    method:             methodName,
    params:             ['arg1', 'arg2'],
    caller:             sourceAddress,
    contractAddress:    'C:BTC:500',
    contractIndex:      500,                   // backs request-id derivation + slash auth
    txHash:             'txhash...',           // backs request-id derivation
    blockContext:       { height: 100, timestamp: 1700000000, hash: 'blockhash' },
    balances:           addressBalances,
    tokenInfo:          tokenInfoMap,
    oracleData:         oracleAccessor,
    crossChainData:     crossChainAccessor,
    attestationData:    attestationAccessor,    // backs xchain.attestation.getResponse
    contractStakeData:  contractStakeAccessor   // backs xchain.contract.* — scoped to THIS contract
});

// result = {
//     success:        boolean,
//     error:          string|null,
//     gasUsed:        number,
//     returnValue:    string|null,
//     stateChanges:   [{ key, value }],
//     stateDeletes:   [key],
//     emittedActions: [{ action, params }],
//     logs:           [string]
// }

Scripts

Total: 974 tests across unit, E2E, security, fuzz, chaos, boundary, regression, and smoke.

Dependencies

Runtime

Development

Related

• Smart Contracts Concept — gateway API reference, contract format, deterministic execution model, attestation framework, stakeable contracts
• Contract Development Guide — writing, deploying, and debugging contracts
• Gas and Fees — gas economics, fee schedule, XCHAIN token
• Indexer Architecture — how the indexer integrates the VM
• DEPLOY Action — deploying a contract (including stakeable-contract metadata)
• EXECUTE Action — calling a contract method
• ATTEST Action — request/response/expire lifecycle behind xchain.attestation.*
• LLM Provider — prompt envelope, approved models, judge-model consensus
• Contract-Targeted Staking — wire spec for xchain.contract.*

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.