/**
 * AsentumChain smart contract VM.
 *
 * A Hardened JavaScript (SES) sandbox that loads contract source, provides
 * chain-native host APIs (storage, msg, chain, emit, assert), and meters
 * gas per operation.
 *
 * Contract convention:
 *   The contract source is a JS program whose final expression evaluates
 *   to an object. That object's methods are the contract's public
 *   interface. A special `init` method, if present, runs once at deploy
 *   time with constructor arguments.
 *
 *   Example:
 *     const BALANCE = 'b:';
 *     ({
 *       init(args) { storage.set(BALANCE + args.owner, String(args.amount)); },
 *       balanceOf(a) { return storage.get(BALANCE + a) || '0'; },
 *     });
 *
 * No ambient authority: no Date.now, Math.random, fetch, setTimeout, etc.
 * All data flows through the host API endowments.
 */

/**
 * Initialize the SES runtime. Must be called before any VM operations.
 * Safe to call multiple times — only the first call actually runs
 * `lockdown()`. In tests, call from `beforeAll`; in the node binary,
 * call at startup.
 */
declare function initializeVm(): void;
/** Execution context passed to a contract. */
interface VmContext {
    /** Hex-encoded sender address (`0x...`). */
    sender: string;
    /** Hex-encoded contract address (`0x...`). */
    contractAddress: string;
    /** Value (in wei-equivalent units) attached to the call. */
    value: bigint;
    /** Current block number. */
    blockNumber: bigint;
    /** Current block timestamp (seconds since epoch). */
    blockTimestamp: bigint;
    /** Chain ID. */
    chainId: bigint;
}
/**
 * Key/value storage interface exposed to contracts. Keys and values are
 * strings (contracts are responsible for encoding BigInts and structured
 * data as strings). Implementations persist these values in the chain
 * state under the contract's storage slot.
 */
interface StorageAdapter {
    get(key: string): string | undefined;
    set(key: string, value: string): void;
    delete(key: string): boolean;
    has(key: string): boolean;
    keys?(prefix?: string): Iterable<string>;
}
/** An event emitted by a contract during execution. */
interface VmEvent {
    name: string;
    data: unknown;
}
/**
 * An outbound value transfer queued by a contract via the `transfer`
 * global. Not applied during VM execution — the chain-integration layer
 * applies them after the contract returns successfully, debiting the
 * contract's balance and crediting the recipient. If the contract's
 * balance is insufficient, the whole tx reverts.
 */
interface OutboundTransfer {
    to: string;
    amount: bigint;
}
/** An approved library to inject as a frozen global in the contract Compartment. */
interface ApprovedLibrary {
    /** The global variable name (e.g., 'math', 'utils'). Must be a valid JS identifier. */
    name: string;
    /** The library's JavaScript source code. Evaluated in its own sub-Compartment with no host APIs. */
    source: string;
}
/**
 * Callback for cross-contract calls via the `E()` global. The chain
 * integration layer provides this — it knows how to load a contract's
 * source and storage by address, enforce the reentrancy guard, and
 * charge gas from the shared budget.
 *
 * Returns the callee's return value. Throws on revert (which the
 * chain layer uses to trigger atomic rollback of all storage writes).
 */
type CrossCallFn = (callerAddress: string, targetAddress: string, method: string, args: unknown[]) => unknown;
/** Common options accepted by both deploy and call operations. */
interface ExecuteOptions {
    source: string;
    context: VmContext;
    storage: StorageAdapter;
    gasLimit: bigint;
    /**
     * Cross-contract call handler. When a contract calls `E(addr).method(args)`,
     * the VM invokes this callback. The chain-integration layer implements it
     * by recursively calling vm.call() with the target contract's source and
     * storage. If omitted, E() throws "cross-contract calls not available".
     */
    crossCall?: CrossCallFn;
    /**
     * contract's Compartment. Each library is evaluated in its own
     * sub-Compartment with no host APIs (no storage, no emit, no msg)
     * — pure functions only. The result is frozen and made available as
     * a global under the library's name.
     */
    approvedLibraries?: ApprovedLibrary[];
}
interface DeployResult {
    events: VmEvent[];
    gasUsed: bigint;
    initReturnValue: unknown;
    outboundTransfers: OutboundTransfer[];
}
interface CallResult {
    returnValue: unknown;
    events: VmEvent[];
    gasUsed: bigint;
    outboundTransfers: OutboundTransfer[];
}
/**
 * The VM. Instantiate once per node process (or per test file). Holds no
 * per-contract state — that lives entirely in the `StorageAdapter` that
 * callers pass in.
 */
declare class Vm {
    constructor();
    /**
     * Deploy a contract: evaluate its source and register the exported
     * interface. If `initArgs` is undefined, `init` is NOT auto-invoked —
     * the caller should invoke it via a separate `call()` if they want
     * explicit initialization. If `initArgs` is an array (even empty), the
     * contract's `init` method (if present) is called with those args.
     *
     * This lets higher-level code choose between two deploy styles:
     *   - "bare deploy, init later" — pass `undefined`
     *   - "deploy with constructor" — pass `[constructorArgs]`
     */
    deploy(options: ExecuteOptions, initArgs?: unknown[]): DeployResult;
    /**
     * Call a method on an already-deployed contract. Re-evaluates the
     * source in a fresh Compartment, finds the exported method, invokes it
     * with the given arguments, and returns the result.
     */
    call(options: ExecuteOptions, method: string, args: unknown[]): CallResult;
    /**
     * Shared compartment setup: builds a metered storage wrapper, an event
     * sink, a safe `chain` / `msg` view, and the `assert` function, then
     * evaluates the contract source and returns whatever the last
     * expression evaluated to.
     */
    private evaluateContract;
}

/**
 * Gas metering for the AsentumChain VM.
 *
 * Uses a flat base gas per call plus per-operation surcharges for storage
 * reads, writes, deletes, and emitted events. This model charges contracts
 * for the work they cause without requiring per-opcode instrumentation
 * inside the SES sandbox.
 */
/** Base cost charged to every contract CALL. */
declare const BASE_CALL_GAS = 21000n;
/** Base cost charged to every contract DEPLOY. */
declare const BASE_DEPLOY_GAS = 32000n;
/** Cost per storage read (including `has`). */
declare const GAS_STORAGE_READ = 800n;
/** Cost per storage write that creates a new key. */
declare const GAS_STORAGE_WRITE_NEW = 20000n;
/** Cost per storage write that updates an existing key. */
declare const GAS_STORAGE_WRITE_UPDATE = 2900n;
/** Cost per storage delete. */
declare const GAS_STORAGE_DELETE = 5000n;
/** Base cost per emitted event, before per-byte payload cost. */
declare const GAS_EVENT_BASE = 375n;
/** Extra cost per byte of event name + serialized data. */
declare const GAS_EVENT_PER_BYTE = 8n;
/** Extra cost per byte of contract source code at deploy time. */
declare const GAS_DEPLOY_PER_BYTE = 200n;
/**
 * Thrown when a contract attempts to consume more gas than its limit.
 * State mutations performed before the throw are not rolled back by the
 * VM itself — the caller (chain apply layer) is responsible for reverting
 * any side effects on failure.
 */
declare class GasLimitExceededError extends Error {
    readonly used: bigint;
    readonly limit: bigint;
    constructor(used: bigint, limit: bigint);
}
/** A running count of gas consumed by a single VM execution. */
declare class GasMeter {
    private readonly limit;
    private used_;
    constructor(limit: bigint);
    /** Charge a fixed amount of gas. Throws if the limit is exceeded. */
    charge(amount: bigint): void;
    /** Current gas used. */
    used(): bigint;
    /** Gas remaining before the limit is hit. */
    remaining(): bigint;
}
declare const GAS_TRANSFER = 9000n;
declare const GAS_CROSS_CALL = 15000n;

/** Thrown when a contract's source fails to parse or evaluate. */
declare class ContractLoadError extends Error {
    constructor(message: string, options?: ErrorOptions);
}
/** Thrown when a contract does not export the expected interface. */
declare class ContractInterfaceError extends Error {
    constructor(message: string);
}
/** Thrown when a contract method throws during execution. */
declare class ContractExecutionError extends Error {
    constructor(message: string, options?: ErrorOptions);
}

export { BASE_CALL_GAS, BASE_DEPLOY_GAS, type CallResult, ContractExecutionError, ContractInterfaceError, ContractLoadError, type CrossCallFn, type DeployResult, type ExecuteOptions, GAS_CROSS_CALL, GAS_DEPLOY_PER_BYTE, GAS_EVENT_BASE, GAS_EVENT_PER_BYTE, GAS_STORAGE_DELETE, GAS_STORAGE_READ, GAS_STORAGE_WRITE_NEW, GAS_STORAGE_WRITE_UPDATE, GAS_TRANSFER, GasLimitExceededError, GasMeter, type OutboundTransfer, type StorageAdapter, Vm, type VmContext, type VmEvent, initializeVm };
