@orbinum/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1674 @@
+import * as polkadot_api from 'polkadot-api';
+import { PolkadotClient, TxFinalizedPayload, PolkadotSigner } from 'polkadot-api';
+export { PolkadotSigner } from 'polkadot-api';
+export { getPolkadotSigner } from 'polkadot-api/signer';
+export { getPolkadotSignerFromPjs } from 'polkadot-api/pjs-signer';
+
+/**
+ * Thin wrapper over polkadot-api (PAPI) that provides:
+ * - Raw JSON-RPC calls (custom Orbinum RPCs)
+ * - Unsafe transaction building from call data
+ * - Transaction submission with or without watching
+ */
+declare class SubstrateClient {
+    private readonly _papi;
+    private constructor();
+    /**
+     * Connects to the Orbinum node via WebSocket.
+     * Throws if the node does not respond within `timeoutMs`.
+     */
+    static connect(wsUrl: string, timeoutMs?: number): Promise<SubstrateClient>;
+    /**
+     * Performs a raw JSON-RPC request. Use this for custom Orbinum RPCs
+     * (shieldedPool_*, accountMapping_*, privacy_*, etc.).
+     */
+    request<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Returns the underlying PolkadotClient instance.
+     * Use for block subscriptions (`blocks$`), raw metadata access, and advanced SCALE operations.
+     */
+    get polkadotClient(): PolkadotClient;
+    /**
+     * Returns the PAPI UnsafeApi for dynamic, metadata-driven transaction building.
+     * The first access triggers a metadata fetch from the node.
+     *
+     * Usage:
+     * ```ts
+     * const tx = client.unsafe.tx.shieldedPool.shield(...);
+     * const result = await tx.signAndSubmit(signer);
+     * ```
+     */
+    get unsafe(): polkadot_api.UnsafeApi<unknown>;
+    /**
+     * Wraps pre-built SCALE call bytes (from protocol-core TransactionBuilder)
+     * into a PAPI UnsafeTransaction that can be signed and submitted.
+     */
+    txFromCallData(callData: Uint8Array): Promise<polkadot_api.UnsafeTransaction<any, string, string, any, Record<string, {
+        value: any;
+        additionalSigned: any;
+    } | {
+        value: any;
+    } | {
+        additionalSigned: any;
+    }>>>;
+    /**
+     * Submits a pre-signed extrinsic (hex string) and waits for finalization.
+     */
+    submit(signedHex: string): Promise<TxFinalizedPayload>;
+    /**
+     * Submits a pre-signed extrinsic and returns an Observable of tx lifecycle events.
+     * Events: TxSigned → TxBroadcasted → TxBestBlocksState → TxFinalized
+     */
+    submitAndWatch(signedHex: string): ReturnType<PolkadotClient['submitAndWatch']>;
+    /**
+     * Convenience: wrap raw call bytes and sign+submit in one step.
+     */
+    signAndSubmit(callData: Uint8Array, signer: PolkadotSigner): Promise<TxFinalizedPayload>;
+    /** Closes the WebSocket connection. */
+    destroy(): void;
+}
+
+/**
+ * Stateless HTTP JSON-RPC client for the Orbinum EVM endpoint.
+ * Follows the standard Ethereum JSON-RPC specification.
+ */
+declare class EvmClient {
+    private readonly rpcUrl;
+    constructor(rpcUrl: string);
+    /**
+     * Performs a single JSON-RPC call.
+     */
+    request<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Performs multiple JSON-RPC calls in a single HTTP request (batch).
+     */
+    batchRequest<T extends unknown[]>(calls: Array<{
+        method: string;
+        params?: unknown[];
+    }>): Promise<T>;
+    /** Returns the native token balance (in wei) for an EVM address. */
+    getBalance(address: string): Promise<bigint>;
+    /** Returns the latest block number. */
+    getBlockNumber(): Promise<number>;
+    /** Returns the current chain ID. */
+    getChainId(): Promise<number>;
+    /** Returns the transaction count (nonce) for an EVM address. */
+    getTransactionCount(address: string): Promise<number>;
+    /** Returns the current gas price in wei. */
+    getGasPrice(): Promise<bigint>;
+    /**
+     * Submits a signed raw transaction. Returns the transaction hash.
+     */
+    sendRawTransaction(signedHex: string): Promise<string>;
+    /**
+     * Executes a read-only call without creating a transaction.
+     */
+    call(to: string, data: string, from?: string): Promise<string>;
+    /**
+     * Estimates the gas for a transaction.
+     */
+    estimateGas(params: {
+        from?: string;
+        to: string;
+        data?: string;
+        value?: string;
+    }): Promise<bigint>;
+    /**
+     * Returns a transaction receipt by hash, or null if not yet mined.
+     */
+    getTransactionReceipt(txHash: string): Promise<Record<string, unknown> | null>;
+}
+
+type OrbinumClientConfig = {
+    /** WebSocket URL of the Orbinum node (e.g. "ws://localhost:9944") */
+    substrateWs: string;
+    /** HTTP URL of the EVM JSON-RPC endpoint (e.g. "http://localhost:9933") */
+    evmRpc?: string;
+    /** Connection timeout in ms. Default: 15_000 */
+    connectTimeoutMs?: number;
+};
+type TxResult = {
+    txHash: string;
+    blockHash: string;
+    blockNumber: number;
+    /** Whether the extrinsic succeeded (no ExtrinsicFailed event). */
+    ok: boolean;
+    /** Dispatch error type string when ok = false. */
+    error?: string;
+};
+type MerkleTreeInfo = {
+    root: string;
+    treeSize: number;
+    depth: number;
+};
+/** Aggregate shielded pool statistics (merkle tree + total locked balance). */
+type PoolStats = {
+    merkleRoot: string;
+    commitmentCount: number;
+    /** Total native balance locked in the pool (u128 as decimal string). */
+    totalBalance: string;
+    treeDepth: number;
+};
+type MerkleProof = {
+    root: string;
+    leafIndex: number;
+    siblings: string[];
+};
+type CommitmentMerkleProof = MerkleProof;
+type NullifierStatus = {
+    nullifier: string;
+    isSpent: boolean;
+};
+type PoolBalance = {
+    assetId: number;
+    balance: bigint;
+};
+type ShieldParams = {
+    assetId: number;
+    amount: bigint;
+    /** 0x-prefixed 32-byte commitment hex */
+    commitment: string;
+    /** Optional encrypted memo bytes. Auto-generates a dummy memo if absent. */
+    encryptedMemo?: Uint8Array;
+};
+type UnshieldParams = {
+    /** ZK proof bytes */
+    proof: Uint8Array;
+    /** 0x-prefixed merkle root hex */
+    merkleRoot: string;
+    /** 0x-prefixed nullifier hex */
+    nullifier: string;
+    assetId: number;
+    amount: bigint;
+    /** SS58 or 0x-prefixed 32-byte address */
+    recipientAddress: string;
+};
+type TransferInput = {
+    /** 0x-prefixed nullifier hex */
+    nullifier: string;
+    /** 0x-prefixed commitment hex */
+    commitment: string;
+};
+type TransferOutput = {
+    /** 0x-prefixed commitment hex */
+    commitment: string;
+    encryptedMemo?: Uint8Array;
+};
+type PrivateTransferParams = {
+    inputs: TransferInput[];
+    outputs: TransferOutput[];
+    /** ZK proof bytes */
+    proof: Uint8Array;
+    /** 0x-prefixed merkle root hex */
+    merkleRoot: string;
+};
+/** Input params for NoteBuilder.build(). All fields except value have defaults. */
+type NoteInput = {
+    /** Amount in planck (required). */
+    value: bigint;
+    /** Asset ID — default 0 (native ORB-Privacy). */
+    assetId?: bigint;
+    /** BabyJubJub Ax coordinate (owner public key x). Default 0n. */
+    ownerPk?: bigint;
+    /** Random blinding scalar. Defaults to BigInt(Date.now()). */
+    blinding?: bigint;
+    /** Secret spending key used to derive the nullifier. Default 0n. */
+    spendingKey?: bigint;
+    /**
+     * 32-byte recipient viewing key used to encrypt the memo (ChaCha20-Poly1305).
+     * When provided, NoteBuilder.build() will auto-generate the 104-byte encrypted memo.
+     * Omit to skip memo generation (use buildMemo() separately if needed).
+     */
+    viewingKey?: Uint8Array;
+};
+/**
+ * Computed ZK note (commitment + nullifier). Built entirely off-chain.
+ *
+ * commitment = Poseidon(value, assetId, ownerPk, blinding)
+ * nullifier  = Poseidon(commitment, spendingKey)
+ */
+type ZkNote = {
+    value: bigint;
+    assetId: bigint;
+    ownerPk: bigint;
+    blinding: bigint;
+    spendingKey: bigint;
+    /** Whether the note has been spent/nullified on-chain. */
+    spent: boolean;
+    /** Local timestamp when this note was marked spent, or null if still active/unknown. */
+    spentAt: number | null;
+    /** Poseidon commitment scalar. */
+    commitment: bigint;
+    /** Poseidon nullifier scalar. */
+    nullifier: bigint;
+    /** 0x-prefixed 32-byte little-endian hex commitment. */
+    commitmentHex: string;
+    /** 0x-prefixed 32-byte little-endian hex nullifier. */
+    nullifierHex: string;
+    /**
+     * 104-byte encrypted memo (ChaCha20-Poly1305) as number[] for SCALE encoding.
+     * Always populated: uses a dummy memo when no viewingKey is provided.
+     */
+    memo: number[];
+};
+/** Result of buildAndShield: the submitted tx and the note to keep safe. */
+type ShieldResult = {
+    txResult: TxResult;
+    note: ZkNote;
+};
+type ChainInfo = {
+    name: string;
+    version: string;
+    ss58Prefix: number;
+};
+type FullIdentityInfo = {
+    substrateAddress: string | null;
+    evmAddress: string | null;
+    alias: string | null;
+};
+/**
+ * Signature verification scheme for cross-chain links.
+ * Mirrors `SignatureScheme` in pallet-account-mapping.
+ */
+type SignatureScheme = 'Eip191' | 'Ed25519';
+/** A verified public link to an external chain wallet. */
+type ChainLink = {
+    chainId: number;
+    address: string;
+};
+/** A private link: only the Poseidon commitment is stored on-chain. */
+type PrivateLink = {
+    chainId: number;
+    commitment: string;
+};
+/** Public profile metadata set by the account owner. */
+type AccountMetadata = {
+    displayName: string | null;
+    bio: string | null;
+    avatar: string | null;
+};
+/** Identity info by alias: owner, optional EVM address, link count. */
+type AliasInfo = {
+    /** 0x-prefixed 32-byte AccountId32 hex. */
+    owner: string;
+    /** Normalized EVM address (0x + 40 hex chars), or null. */
+    evmAddress: string | null;
+    chainLinksCount: number;
+};
+/**
+ * Full identity for an alias: owner, EVM address, all public chain links, metadata.
+ * Returned by `accountMapping_getFullIdentity` (alias-based lookup).
+ */
+type AliasFullIdentity = {
+    owner: string;
+    evmAddress: string | null;
+    chainLinks: ChainLink[];
+    metadata: AccountMetadata | null;
+};
+/** Sale listing info for an alias on the marketplace. */
+type ListingInfo = {
+    price: bigint;
+    /** True if sale is private (whitelist-only). */
+    private: boolean;
+    whitelistCount: number;
+};
+/** An alias actively listed for sale with its full info. */
+type AccountListing = {
+    alias: string;
+    listing: ListingInfo;
+};
+/** A supported chain and its signature verification scheme. */
+type SupportedChain = {
+    chainId: number;
+    scheme: SignatureScheme;
+};
+/**
+ * Bitmask to convert a SLIP-0044 coin type into an Orbinum ChainId.
+ * Example: `SLIP0044_NAMESPACE | 501` = Solana.
+ */
+declare const SLIP0044_NAMESPACE = 2147483648;
+
+/**
+ * Queries the Orbinum shielded-pool Merkle tree via custom RPC methods.
+ */
+declare class MerkleModule {
+    private readonly substrate;
+    constructor(substrate: SubstrateClient);
+    /**
+     * Returns the current Merkle tree state: root, number of leaves, and depth.
+     */
+    getTreeInfo(): Promise<MerkleTreeInfo>;
+    /**
+     * Returns the Merkle inclusion proof for a leaf at `leafIndex`.
+     */
+    getProof(leafIndex: number): Promise<MerkleProof>;
+    /**
+     * Returns the Merkle inclusion proof for a given commitment (0x-prefixed hex).
+     * Searches the tree for the commitment and returns its proof.
+     */
+    getProofByCommitment(commitmentHex: string): Promise<MerkleProof>;
+    /**
+     * Returns the current Merkle root without fetching the full tree info.
+     */
+    getRoot(): Promise<string>;
+    /**
+     * Returns an array of commitment leaves from index `from` to `to` (inclusive).
+     * Defaults to returning all leaves.
+     */
+    getLeaves(from?: number, to?: number): Promise<string[]>;
+}
+
+/**
+ * High-level module for Orbinum shielded-pool operations.
+ *
+ * Transactions are built via polkadot-api's UnsafeApi (metadata-driven),
+ * which means the Orbinum node must be reachable on first use.
+ * Signing is delegated to a PolkadotSigner (see polkadot-api/signer).
+ *
+ * Parameter order matches the Orbinum runtime extrinsics exactly.
+ */
+declare class ShieldedPoolModule {
+    private readonly substrate;
+    readonly merkle: MerkleModule;
+    constructor(substrate: SubstrateClient, merkle: MerkleModule);
+    /**
+     * Deposits tokens into the shielded pool.
+     * Extrinsic: shieldedPool.shield(assetId, amount, commitment, encryptedMemo)
+     */
+    shield(params: ShieldParams, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Build a ZkNote locally and submit shieldedPool.shield in one call.
+     *
+     * Returns both the on-chain result and the note — **save the note locally**,
+     * it cannot be recovered after the fact.
+     *
+     * @param params.value       Amount in planck (required).
+     * @param params.assetId     Asset ID — default 0 (native ORB-Privacy).
+     * @param params.ownerPk     BabyJubJub Ax (default 0n).
+     * @param params.blinding    Random blinding scalar (default BigInt(Date.now())).
+     * @param params.spendingKey Secret spending key (default 0n).
+     */
+    buildAndShield(params: {
+        value: bigint;
+        assetId?: number;
+        ownerPk?: bigint;
+        blinding?: bigint;
+        spendingKey?: bigint;
+    }, signer: PolkadotSigner): Promise<ShieldResult>;
+    /**
+     * Withdraws tokens from the shielded pool to a public address.
+     * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)
+     */
+    unshield(params: UnshieldParams, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Performs a private (shielded) transfer between two notes.
+     * Extrinsic: shieldedPool.privateTransfer(inputs, outputs, proof, merkleRoot)
+     */
+    privateTransfer(params: PrivateTransferParams, signer: PolkadotSigner): Promise<TxResult>;
+    /** Returns whether a nullifier has already been spent. */
+    isNullifierSpent(nullifierHex: string): Promise<boolean>;
+    /** Returns the full nullifier status object. */
+    getNullifierStatus(nullifierHex: string): Promise<NullifierStatus>;
+    /** Returns the total locked balance in the pool for a given asset. */
+    getPoolBalance(assetId: number): Promise<PoolBalance>;
+    /**
+     * Returns Merkle tree info and pool balance for a given asset in a single call.
+     * Convenience wrapper used by both `app` and `privacy-explorer`.
+     */
+    getPoolStats(assetId?: number): Promise<{
+        merkle: MerkleTreeInfo;
+        balance: PoolBalance;
+    }>;
+}
+
+type RawSystemHealth = {
+    peers: number;
+    isSyncing: boolean;
+    shouldHavePeers: boolean;
+};
+/**
+ * Provides general chain queries: node info, account mapping, address resolution.
+ */
+declare class ChainModule {
+    private readonly substrate;
+    private readonly evm;
+    constructor(substrate: SubstrateClient, evm: EvmClient | null);
+    /**
+     * Returns basic chain information from the node.
+     */
+    getChainInfo(): Promise<ChainInfo>;
+    /**
+     * Returns the node's peer count and sync status.
+     */
+    getHealth(): Promise<RawSystemHealth>;
+    /**
+     * Returns the node's software version string.
+     */
+    getNodeVersion(): Promise<string>;
+    /**
+     * Returns the genesis hash hex.
+     */
+    getGenesisHash(): Promise<string>;
+    /**
+     * Resolves the full identity (Substrate + EVM addresses, alias) for an account.
+     * Accepts an EVM address (0x...) or a Substrate account hex (0x...32bytes).
+     */
+    getFullIdentity(address: string): Promise<FullIdentityInfo | null>;
+    /**
+     * Returns the mapped Substrate account hex for a given EVM address, or null.
+     */
+    getMappedAccountByEvm(evmAddress: string): Promise<string | null>;
+    /**
+     * Returns the alias registered for a Substrate account, or null.
+     */
+    getAliasOf(accountHex: string): Promise<string | null>;
+    /**
+     * Returns estimated EVM chain ID from the EVM RPC endpoint. Requires evmRpc
+     * to have been provided in `OrbinumClientConfig`.
+     */
+    getEvmChainId(): Promise<number>;
+    /**
+     * Returns the current EVM block number.
+     */
+    getEvmBlockNumber(): Promise<number>;
+}
+
+type AddChainLinkParams = {
+    /** External chain ID. Use SLIP0044_NAMESPACE | coinType for SLIP-0044 chains. */
+    chainId: number;
+    /** The external address bytes (e.g. 20 bytes for EVM, 32 for Solana). */
+    address: Uint8Array;
+    /** Signature over the caller's AccountId32 (64 bytes for Ed25519, 65 for EIP-191). */
+    signature: Uint8Array;
+};
+type SetMetadataParams = {
+    displayName?: string | null;
+    bio?: string | null;
+    avatar?: string | null;
+};
+type PutOnSaleParams = {
+    price: bigint;
+    /** If true the sale becomes OTC (whitelist required). */
+    isPrivate: boolean;
+};
+type DispatchAsLinkedParams = {
+    /** Owner AccountId32 hex (0x-prefixed 64 chars). */
+    owner: string;
+    chainId: number;
+    address: Uint8Array;
+    /** Signature over the encoded call payload. */
+    signature: Uint8Array;
+    /** Encoded call bytes (SCALE). */
+    callData: Uint8Array;
+};
+/**
+ * Module for Orbinum pallet-account-mapping:
+ * - Query on-chain identity data (aliases, chain links, metadata, marketplace)
+ * - Submit identity management extrinsics
+ *
+ * All query methods return null/false on not-found or network errors.
+ */
+declare class AccountMappingModule {
+    private readonly substrate;
+    constructor(substrate: SubstrateClient);
+    /**
+     * Returns the explicitly mapped (or fallback) Substrate AccountId32 hex for
+     * an EVM address. `mapped` is set only when `map_account` was called.
+     * `fallback` is always the EeSuffix rule: `H160 ++ [0x00; 12]`.
+     */
+    getAccountAddresses(accountId: string): Promise<{
+        mapped: string | null;
+        fallback: string | null;
+    }>;
+    /**
+     * Returns the explicitly mapped Substrate AccountId32 hex for a given EVM
+     * address, or null if no explicit mapping exists.
+     */
+    getMappedAccount(evmAddress: string): Promise<string | null>;
+    /**
+     * Resolves "@alias" to basic info (owner, optional EVM address, link count).
+     * Accepts the alias with or without the leading "@".
+     */
+    resolveAlias(alias: string): Promise<AliasInfo | null>;
+    /**
+     * Returns the alias registered for the given Substrate AccountId32 hex, or null.
+     */
+    getAliasOf(accountId: string): Promise<string | null>;
+    /**
+     * Resolves "@alias" to its full identity: owner, EVM address, all public
+     * chain links, and profile metadata.
+     */
+    resolveFullIdentity(alias: string): Promise<AliasFullIdentity | null>;
+    /**
+     * Returns the profile metadata for a given Substrate AccountId32 hex, or null.
+     */
+    getAccountMetadata(accountId: string): Promise<AccountMetadata | null>;
+    /**
+     * Returns the owner AccountId32 hex of a verified multichain link, or null.
+     */
+    getLinkOwner(chainId: number, address: string): Promise<string | null>;
+    /**
+     * Returns all blockchain networks supported for verified cross-chain links.
+     */
+    getSupportedChains(): Promise<SupportedChain[]>;
+    /**
+     * Returns the private link commitments registered for an alias.
+     * Real addresses are never exposed. Returns null if the alias does not exist.
+     */
+    getPrivateLinks(alias: string): Promise<PrivateLink[] | null>;
+    /**
+     * Returns true if the given commitment is registered as a private link for the alias.
+     */
+    hasPrivateLink(alias: string, commitment: string): Promise<boolean>;
+    /**
+     * Returns listing info if the alias is currently for sale, or null.
+     */
+    getListingInfo(alias: string): Promise<ListingInfo | null>;
+    /**
+     * Returns the alias and its listing if the given account currently has an
+     * alias listed for sale. Returns null otherwise.
+     */
+    getAccountListing(accountId: string): Promise<AccountListing | null>;
+    /**
+     * Returns whether a specific buyer can purchase the given alias right now.
+     */
+    canBuy(alias: string, buyerAccountId: string): Promise<boolean>;
+    /**
+     * Creates an explicit EVM → Substrate account mapping.
+     * Stores an explicit `MappedAccounts` entry for the caller's H160.
+     * Extrinsic: accountMapping.mapAccount()
+     */
+    mapAccount(signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Removes the EVM → Substrate mapping for the caller.
+     * Extrinsic: accountMapping.unmapAccount()
+     */
+    unmapAccount(signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Registers a unique @alias for the caller.
+     * Requires a deposit. The alias must be 3–32 ASCII lowercase alphanumeric chars + hyphens.
+     * Extrinsic: accountMapping.registerAlias(alias)
+     */
+    registerAlias(alias: string, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Releases the caller's alias and recovers the deposit.
+     * Extrinsic: accountMapping.releaseAlias()
+     */
+    releaseAlias(signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Transfers the caller's alias to another account.
+     * Extrinsic: accountMapping.transferAlias(newOwner)
+     */
+    transferAlias(newOwnerHex: string, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Adds a verified public link to an external-chain wallet.
+     *
+     * `params.signature` must be produced by the external wallet over the caller's
+     * AccountId32 bytes:
+     *  - EIP-191 (EVM): sign(keccak256("\x19Ethereum Signed Message:\n32" + accountId32))
+     *  - Ed25519 (Solana): sign(accountId32 bytes)
+     *
+     * Extrinsic: accountMapping.addChainLink(chainId, address, signature)
+     */
+    addChainLink(params: AddChainLinkParams, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Removes the external-chain link for the given chain ID.
+     * Extrinsic: accountMapping.removeChainLink(chainId)
+     */
+    removeChainLink(chainId: number, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Updates the caller's public profile metadata.
+     * Extrinsic: accountMapping.setAccountMetadata(displayName, bio, avatar)
+     */
+    setAccountMetadata(params: SetMetadataParams, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Lists the caller's alias for sale on the alias marketplace.
+     * Extrinsic: accountMapping.putAliasOnSale(price, isPrivate)
+     */
+    putAliasOnSale(params: PutOnSaleParams, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Cancels an active alias sale listing.
+     * Extrinsic: accountMapping.cancelSale()
+     */
+    cancelSale(signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Purchases an alias listed for sale.
+     * Extrinsic: accountMapping.buyAlias(alias)
+     */
+    buyAlias(alias: string, signer: PolkadotSigner): Promise<TxResult>;
+    /**
+     * Dispatches an arbitrary call on behalf of a linked external-chain wallet.
+     *
+     * This is the "Universal Proxy" feature that allows EVM/Solana wallets to
+     * authorize on-chain actions without holding a Substrate private key.
+     *
+     * The relayer (who pays gas) calls this with the external wallet's signature
+     * over the encoded call payload and the owner's AccountId32.
+     *
+     * Extrinsic: accountMapping.dispatchAsLinkedAccount(owner, chainId, address, signature, call)
+     */
+    dispatchAsLinkedAccount(params: DispatchAsLinkedParams, signer: PolkadotSigner): Promise<TxResult>;
+}
+
+/**
+ * Converts a Uint8Array or number[] to a 0x-prefixed lowercase hex string.
+ */
+declare function toHex(bytes: Uint8Array | number[]): string;
+/**
+ * Decodes a hex string (with or without 0x prefix) to Uint8Array.
+ */
+declare function fromHex(hex: string): Uint8Array;
+/**
+ * Ensures a hex string has the 0x prefix.
+ */
+declare function ensureHexPrefix(hex: string): string;
+
+/** EVM transaction request passed to an `EvmSigner` callback. */
+type EvmTxRequest = {
+    to: string;
+    data: string;
+    value?: bigint;
+};
+/**
+ * Callback that signs and submits an EVM transaction, returning the tx hash.
+ *
+ * MetaMask: `(tx) => window.ethereum.request({ method: 'eth_sendTransaction', params: [{ ...tx, from: account }] })`
+ * ethers:   `(tx) => (await signer.sendTransaction({ to: tx.to, data: tx.data })).hash`
+ * viem:     `(tx) => walletClient.sendTransaction({ to: tx.to, data: tx.data })`
+ */
+type EvmSigner = (tx: EvmTxRequest) => Promise<string>;
+/**
+ * Bindings for the `ShieldedPoolPrecompile` at address `0x...0801`.
+ *
+ * This precompile wraps `pallet-shielded-pool` extrinsics and dispatches them
+ * on behalf of the EVM caller (resolved to an AccountId32 via
+ * `EeSuffixAddressMapping`). No Substrate signer is required — an EVM wallet
+ * is sufficient.
+ *
+ * ### Key benefit for apps
+ * EVM-only users (MetaMask, Phantom bridge via chain links, etc.) can shield,
+ * transfer, and unshield without ever needing a Polkadot extension.
+ *
+ * All write methods accept an `EvmSigner` callback so the module stays
+ * transport-agnostic. See `buildShieldCalldata` etc. if you only need the
+ * raw calldata for custom signing flows.
+ */
+declare class ShieldedPoolPrecompile {
+    private readonly evm;
+    private readonly addr;
+    constructor(evm: EvmClient);
+    /**
+     * Returns the ABI-encoded calldata for `shield(uint32, uint256, bytes32, bytes)`.
+     * Useful when you need to inspect or batch the calldata before sending.
+     */
+    buildShieldCalldata(params: ShieldParams): string;
+    /**
+     * Deposits tokens into the shielded pool from an EVM transaction.
+     *
+     * The EVM caller's address is deterministically mapped to a Substrate
+     * AccountId32 (`H160 ++ [0x00; 12]`). The pool deducts from that account.
+     *
+     * Extrinsic: `shieldedPool.shield(assetId, amount, commitment, encryptedMemo)`
+     */
+    shield(params: ShieldParams, signer: EvmSigner): Promise<string>;
+    /**
+     * Returns the ABI-encoded calldata for
+     * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[])`.
+     */
+    buildPrivateTransferCalldata(params: PrivateTransferParams): string;
+    /**
+     * Submits a private transfer within the shielded pool from an EVM transaction.
+     *
+     * The EVM caller identity is **irrelevant to the ZK proof** — the sender is
+     * hidden by design. Any EVM address (including a relayer) can submit a valid proof.
+     *
+     * Extrinsic: `shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos)`
+     */
+    privateTransfer(params: PrivateTransferParams, signer: EvmSigner): Promise<string>;
+    /**
+     * Params for an `unshield` call via the EVM precompile.
+     * The `recipient` is a full 32-byte AccountId32 (Substrate account or
+     * EeSuffix-derived: `H160 ++ [0x00; 12]`).
+     */
+    buildUnshieldCalldata(params: UnshieldParams): string;
+    /**
+     * Withdraws tokens from the shielded pool to a recipient account.
+     *
+     * `params.recipientAddress` must be a 0x-prefixed 64-hex-char AccountId32.
+     * To send to an EVM address, use `evmToImplicitSubstrate(evmAddr)` from
+     * `@orbinum/sdk` to derive the AccountId32 first.
+     *
+     * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)`
+     */
+    unshield(params: UnshieldParams, signer: EvmSigner): Promise<string>;
+    /**
+     * Estimates the EVM gas for a `shield` call without submitting.
+     * Requires `from` to be set to the actual sender address.
+     */
+    estimateShieldGas(params: ShieldParams, from: string): Promise<bigint>;
+    /**
+     * Estimates the EVM gas for a `privateTransfer` call.
+     */
+    estimatePrivateTransferGas(params: PrivateTransferParams, from: string): Promise<bigint>;
+    /**
+     * Estimates the EVM gas for an `unshield` call.
+     */
+    estimateUnshieldGas(params: UnshieldParams, from: string): Promise<bigint>;
+}
+
+type ResolvedAlias = {
+    /** AccountId32 hex of the alias owner (as 0x-prefixed 20-byte EVM address). */
+    owner: string;
+    /** EVM address of the owner, or null if unset. */
+    evmAddress: string | null;
+};
+/**
+ * EVM bindings for `AccountMappingPrecompile` at address `0x...0800`.
+ *
+ * This precompile wraps `pallet-account-mapping` extrinsics and queries,
+ * allowing **EVM wallets** to manage their on-chain identity (aliases, chain
+ * links, metadata, marketplace) without a Substrate signer.
+ *
+ * ### Read-only calls
+ * Use `resolveAlias`, `getAliasOf`, `hasPrivateLink` to query state via
+ * `eth_call` — no signer required.
+ *
+ * ### Write calls
+ * Provide an `EvmSigner` callback. The EVM caller's address is mapped to its
+ * Substrate AccountId32 via `AddressMapping`.
+ */
+declare class AccountMappingPrecompile {
+    private readonly evm;
+    private readonly addr;
+    constructor(evm: EvmClient);
+    /**
+     * Resolves `@alias` to its owner EVM address (and optionally a secondary EVM address).
+     *
+     * Returns `(address owner, address evmAddress)` — two 32-byte ABI-encoded slots.
+     * `evmAddress` is zero-address (`0x000...0`) if the owner has no explicit EVM address.
+     */
+    resolveAlias(alias: string): Promise<ResolvedAlias | null>;
+    /**
+     * Returns the alias registered for the given EVM address, or null.
+     * The precompile ABI encodes the alias as `bytes` (UTF-8).
+     */
+    getAliasOf(evmAddress: string): Promise<string | null>;
+    /**
+     * Returns true if the given Poseidon commitment is registered as a private
+     * link for the given alias.
+     */
+    hasPrivateLink(alias: string, commitment: string): Promise<boolean>;
+    /**
+     * Creates an explicit EVM → Substrate account mapping for the signer's address.
+     * Extrinsic: `accountMapping.mapAccount()`
+     */
+    mapAccount(signer: EvmSigner): Promise<string>;
+    /**
+     * Removes the EVM → Substrate mapping for the signer's address.
+     * Extrinsic: `accountMapping.unmapAccount()`
+     */
+    unmapAccount(signer: EvmSigner): Promise<string>;
+    /**
+     * Releases the signer's registered alias, recovering the deposit.
+     * Extrinsic: `accountMapping.releaseAlias()`
+     */
+    releaseAlias(signer: EvmSigner): Promise<string>;
+    /**
+     * Cancels an active alias sale listing.
+     * Extrinsic: `accountMapping.cancelSale()`
+     */
+    cancelSale(signer: EvmSigner): Promise<string>;
+    /**
+     * Registers a unique @alias for the signer's account.
+     * Requires a deposit. The alias must be 3–32 ASCII lowercase alphanumeric chars + hyphens.
+     * Extrinsic: `accountMapping.registerAlias(alias)`
+     */
+    registerAlias(alias: string, signer: EvmSigner): Promise<string>;
+    /**
+     * Transfers the signer's alias to a new EVM `owner` address.
+     * Extrinsic: `accountMapping.transferAlias(newOwner)`
+     */
+    transferAlias(newOwnerEvmAddress: string, signer: EvmSigner): Promise<string>;
+    /**
+     * Purchases an alias currently listed for sale.
+     * Extrinsic: `accountMapping.buyAlias(alias)`
+     */
+    buyAlias(alias: string, signer: EvmSigner): Promise<string>;
+    /**
+     * Lists the signer's alias for sale on the alias marketplace.
+     *
+     * @param price          Asking price in planck (ORB).
+     * @param allowedBuyers  Whitelist of EVM addresses allowed to buy.
+     *                       Pass an empty array for a public (open) listing.
+     * Extrinsic: `accountMapping.putAliasOnSale(price, allowedBuyers)`
+     */
+    putAliasOnSale(price: bigint, allowedBuyers: string[], signer: EvmSigner): Promise<string>;
+    /**
+     * Removes the external-chain link for the given chain ID.
+     * Extrinsic: `accountMapping.removeChainLink(chainId)`
+     */
+    removeChainLink(chainId: number, signer: EvmSigner): Promise<string>;
+    /**
+     * Adds a verified public link to an external-chain wallet.
+     *
+     * @param chainId       Orbinum chain ID (use `SLIP0044_NAMESPACE | coinType` for SLIP-0044).
+     * @param externalAddr  External wallet address bytes (20 bytes for EVM, 32 for Solana).
+     * @param signature     Signature over the caller's AccountId32:
+     *                        - EIP-191 (EVM): 65 bytes over keccak256("\x19Ethereum Signed Message:\n32" + accountId32)
+     *                        - Ed25519 (Solana): 64 bytes over the raw accountId32 bytes
+     *
+     * Extrinsic: `accountMapping.addChainLink(chainId, address, signature)`
+     */
+    addChainLink(chainId: number, externalAddr: Uint8Array, signature: Uint8Array, signer: EvmSigner): Promise<string>;
+    /**
+     * Registers a private chain link — only the Poseidon commitment is stored.
+     * The real external address is never revealed on-chain.
+     *
+     * @param chainId     External chain ID.
+     * @param commitment  0x-prefixed 32-byte Poseidon commitment hex.
+     *
+     * Extrinsic: `accountMapping.registerPrivateLink(chainId, commitment)`
+     */
+    registerPrivateLink(chainId: number, commitment: string, signer: EvmSigner): Promise<string>;
+    /**
+     * Removes a private link by its commitment.
+     * Extrinsic: `accountMapping.removePrivateLink(commitment)`
+     */
+    removePrivateLink(commitment: string, signer: EvmSigner): Promise<string>;
+    /**
+     * Reveals a private link publicly by providing the real address and blinding.
+     * After this call the link becomes a public chain link.
+     *
+     * @param commitment  32-byte commitment hex.
+     * @param address     External address bytes (the actual wallet address).
+     * @param blinding    32-byte blinding factor used when computing the commitment.
+     * @param signature   Signature over the AccountId32 bytes (same rules as `addChainLink`).
+     *
+     * Extrinsic: `accountMapping.revealPrivateLink(commitment, address, blinding, signature)`
+     */
+    revealPrivateLink(commitment: string, address: Uint8Array, blinding: string, signature: Uint8Array, signer: EvmSigner): Promise<string>;
+    /**
+     * Updates the signer's public profile metadata.
+     * Pass `null` for any field to leave it unchanged.
+     *
+     * Extrinsic: `accountMapping.setAccountMetadata(displayName, bio, avatar)`
+     */
+    setAccountMetadata(displayName: string | null, bio: string | null, avatar: string | null, signer: EvmSigner): Promise<string>;
+    /** Returns the raw ABI-encoded calldata for `registerAlias`. */
+    buildRegisterAliasCalldata(alias: string): string;
+    /** Returns the raw ABI-encoded calldata for `mapAccount`. */
+    buildMapAccountCalldata(): string;
+}
+
+/**
+ * Low-level bindings for cryptographic EVM precompiles.
+ *
+ * These precompiles use **raw input** (no ABI selector) and are called via
+ * `eth_call`. They are useful for on-chain-verified cryptographic operations,
+ * particularly `curve25519Add` and `curve25519ScalarMul` for Ristretto ZK math.
+ *
+ * Gas costs are deterministic but metered by the EVM; for off-chain operations
+ * prefer the `@noble/*` libraries directly.
+ */
+declare class CryptoPrecompiles {
+    private readonly evm;
+    constructor(evm: EvmClient);
+    /**
+     * Recovers the Ethereum address from an ECDSA signature.
+     *
+     * Classic Ethereum ECRecover (EIP-spec): input is always 128 bytes:
+     *   hash(32) + v_padded(32, v=27 or 28) + r(32) + s(32)
+     *
+     * Returns a 0x-prefixed lowercase 20-byte EVM address.
+     */
+    ecRecover(hash: Uint8Array, v: 27 | 28, r: Uint8Array, s: Uint8Array): Promise<string>;
+    /**
+     * Recovers the **full uncompressed public key** (64 bytes, no 0x04 prefix)
+     * from an ECDSA signature.
+     *
+     * Same input format as `ecRecover`. Output is 64 bytes (32-byte X + 32-byte Y).
+     */
+    ecRecoverPublicKey(hash: Uint8Array, v: 27 | 28, r: Uint8Array, s: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Computes SHA-256 of arbitrary bytes via EVM precompile.
+     * Returns a 32-byte digest.
+     */
+    sha256(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Computes RIPEMD-160 of arbitrary bytes via EVM precompile.
+     * Returns the 20-byte digest right-padded to 32 bytes (standard ABI output).
+     */
+    ripemd160(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Data copy via EVM precompile (identity). Returns the input unchanged.
+     * Mainly useful for gas benchmarking.
+     */
+    identity(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Computes Keccak-256 (= SHA3-FIPS-256 as used by Ethereum) of arbitrary bytes.
+     * Returns a 32-byte digest.
+     */
+    keccak256(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Adds up to 10 Ristretto (Curve25519) compressed points via EVM precompile.
+     *
+     * Input: N × 32-byte CompressedRistretto points concatenated (N ≤ 10).
+     * Output: 32-byte CompressedRistretto sum.
+     *
+     * Useful for ZK protocols that require verifiable Pedersen commitments.
+     */
+    curve25519Add(points: Uint8Array[]): Promise<Uint8Array>;
+    /**
+     * Multiplies a Ristretto compressed point by a scalar via EVM precompile.
+     *
+     * Input: 32-byte scalar (little-endian) + 32-byte CompressedRistretto point.
+     * Output: 32-byte CompressedRistretto result.
+     *
+     * Useful for computing key images and Pedersen commitments in ZK protocols.
+     */
+    curve25519ScalarMul(scalar: Uint8Array, point: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * Main entry point for the Orbinum TypeScript SDK.
+ *
+ * Connects to an Orbinum node and exposes all protocol modules.
+ *
+ * @example
+ * ```ts
+ * import { OrbinumClient } from '@orbinum/sdk';
+ *
+ * const client = await OrbinumClient.connect({
+ *   substrateWs: 'ws://localhost:9944',
+ *   evmRpc: 'http://localhost:9933',
+ * });
+ *
+ * // Query Merkle tree
+ * const info = await client.shieldedPool.merkle.getTreeInfo();
+ * console.log('root:', info.root, 'nodes:', info.treeSize);
+ *
+ * // Shield tokens (with a PolkadotSigner)
+ * const result = await client.shieldedPool.shield(
+ *   { assetId: 1, amount: 1000n, commitment: '0xabc...' },
+ *   signer,
+ * );
+ * console.log('tx ok:', result.ok, 'block:', result.blockHash);
+ *
+ * client.destroy();
+ * ```
+ */
+declare class OrbinumClient {
+    /** Raw access to the Substrate WebSocket connection and RPC. */
+    readonly substrate: SubstrateClient;
+    /** Raw access to the EVM HTTP JSON-RPC endpoint (if configured). */
+    readonly evm: EvmClient | null;
+    /** Shielded-pool operations: shield, unshield, privateTransfer, and merkle queries. */
+    readonly shieldedPool: ShieldedPoolModule;
+    /** General chain queries: node info, identity resolution. */
+    readonly chain: ChainModule;
+    /** Account mapping: aliases, chain links, metadata, marketplace, and identity extrinsics. */
+    readonly accountMapping: AccountMappingModule;
+    /**
+     * EVM precompiles: shielded pool + account mapping callable from an EVM wallet.
+     * Only available when `evmRpc` is configured. Methods throw if `evm` is null.
+     */
+    readonly precompiles: {
+        /** `ShieldedPoolPrecompile` (0x0801): shield/unshield/transfer via EVM wallet. */
+        shieldedPool: ShieldedPoolPrecompile;
+        /** `AccountMappingPrecompile` (0x0800): identity management via EVM wallet. */
+        accountMapping: AccountMappingPrecompile;
+        /** Cryptographic precompiles: ECRecover, Keccak-256, Curve25519. */
+        crypto: CryptoPrecompiles;
+    } | null;
+    private constructor();
+    /**
+     * Connects to an Orbinum node and returns a ready-to-use `OrbinumClient`.
+     * Throws if the Substrate node is unreachable within `connectTimeoutMs`.
+     */
+    static connect(config: OrbinumClientConfig): Promise<OrbinumClient>;
+    /**
+     * Convenience getter for the Merkle module (shortcut for `shieldedPool.merkle`).
+     */
+    get merkle(): MerkleModule;
+    /** Closes the WebSocket connection to the Substrate node. */
+    destroy(): void;
+}
+
+/**
+ * Builds ZK notes (commitment + nullifier) and encrypted memos locally.
+ *
+ * All computation is off-chain — no network calls are made.
+ *
+ * Hash scheme (Poseidon, circomlibjs):
+ *   commitment = Poseidon(value, assetId, ownerPk, blinding)
+ *   nullifier  = Poseidon(commitment, spendingKey)
+ *
+ * Memo scheme (EncryptedMemo — native TypeScript, no WASM):
+ *   ChaCha20-Poly1305 with key = SHA256(recipientVk || commitment || domain)
+ *   Result: nonce(12) || ciphertext(76 + 16 MAC) = 104 bytes
+ */
+declare class NoteBuilder {
+    /**
+     * Build a ZkNote from the given inputs.
+     *
+     * @param input.value       Amount in planck (required).
+     * @param input.assetId     Asset ID — default 0n (native ORB-Privacy).
+     * @param input.ownerPk     BabyJubJub Ax — default 0n.
+     * @param input.blinding    Random scalar — defaults to BigInt(Date.now()).
+     * @param input.spendingKey Secret key for nullifier — default 0n.
+     */
+    static build(input: NoteInput): Promise<ZkNote>;
+    /**
+     * Build the 104-byte encrypted memo for a note.
+     *
+     * Pure TypeScript implementation — no WASM dependency.
+     * Uses ChaCha20-Poly1305 with SHA-256 key derivation.
+     *
+     * @param note         The ZkNote whose fields populate the plaintext.
+     * @param recipientVk  32-byte recipient viewing key.
+     *                     Pass `new Uint8Array(32)` (default) for a public/dummy memo.
+     */
+    static buildMemo(note: ZkNote, recipientVk?: Uint8Array): Uint8Array;
+}
+
+/**
+ * EncryptedMemo — TypeScript implementation of Orbinum's encrypted note memo.
+ *
+ * Mirrors primitives/encrypted-memo in the node repository; no WASM required.
+ *
+ * Layout (104 bytes):
+ *   nonce(12) || ciphertext(76 + 16 MAC) = 104
+ *
+ * Plaintext layout (76 bytes):
+ *   value(8 LE) || owner_pk(32) || blinding(32) || asset_id(4 LE)
+ *
+ * Key derivation:
+ *   key = SHA256(viewing_key || commitment || "orbinum-note-encryption-v1")
+ *
+ * Cipher: ChaCha20-Poly1305 (IETF, 96-bit nonce)
+ */
+/** Fields recovered from a successfully decrypted EncryptedMemo. */
+type DecryptedMemo = {
+    value: bigint;
+    ownerPk: bigint;
+    blinding: bigint;
+    assetId: bigint;
+};
+declare const EncryptedMemo: {
+    /**
+     * Build and encrypt a memo for a note.
+     *
+     * @param value       Note value in planck.
+     * @param ownerPk     32-byte owner public key (little-endian).
+     * @param blinding    32-byte blinding scalar (little-endian).
+     * @param assetId     Asset identifier.
+     * @param commitment  32-byte commitment bytes (little-endian).
+     * @param recipientVk 32-byte recipient viewing key — pass `new Uint8Array(32)`
+     *                    for a publicly-readable (dummy) memo.
+     * @returns 104-byte encrypted memo (nonce || ciphertext).
+     */
+    encrypt(value: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array, recipientVk: Uint8Array): Uint8Array;
+    /**
+     * Returns a 104-byte public memo with a zero recipient viewing key.
+     * The memo is still readable by anyone who holds the viewing key (zeros).
+     */
+    encryptPublic(value: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array): Uint8Array;
+    /**
+     * Returns a 104-byte zeroed dummy memo (no information, always valid on-chain).
+     */
+    dummy(): Uint8Array;
+    /**
+     * Decrypt an on-chain EncryptedMemo.
+     *
+     * Returns `null` if decryption fails — wrong key, bad MAC, or malformed memo.
+     * Never throws; safe for scan loops.
+     *
+     * @param memoBytes   104-byte encrypted memo.
+     * @param commitment  32-byte note commitment (little-endian).
+     * @param recipientVk 32-byte recipient viewing key.
+     */
+    decrypt(memoBytes: Uint8Array, commitment: Uint8Array, recipientVk: Uint8Array): DecryptedMemo | null;
+};
+
+/**
+ * NoteDecryptor
+ *
+ * Core logic for decrypting on-chain commitments during a shielded pool scan.
+ * For each commitment, attempts to decrypt the encryptedMemo with the viewer's
+ * viewing key, then verifies the recomputed commitment matches the on-chain value.
+ *
+ * This is protocol-level logic — independent of indexer, storage, or UI.
+ * Consume via scan loops in application code.
+ *
+ * Hash scheme (Poseidon BN254, poseidon-lite):
+ *   commitment = Poseidon4(value, assetId, ownerPk, blinding)
+ *   nullifier  = Poseidon2(commitment, spendingKey)
+ */
+
+/** A single commitment record as returned by the indexer. */
+interface ScanCommitment {
+    commitmentHex: string;
+    leafIndex: number;
+    encryptedMemo: string | null;
+}
+/**
+ * Attempt to decrypt an on-chain commitment using a viewing key.
+ *
+ * Returns a fully populated ZkNote if the memo decrypts correctly and the
+ * recomputed commitment matches the on-chain value.
+ * Returns null when the note does not belong to this viewer (wrong key, no memo,
+ * or commitment mismatch).
+ *
+ * @param commitment  On-chain commitment record from the indexer.
+ * @param viewingKey  32-byte viewing key (from deriveViewingKey).
+ * @param spendingKey Spending key bigint (for nullifier computation).
+ */
+declare function tryDecryptNote(commitment: ScanCommitment, viewingKey: Uint8Array, spendingKey: bigint): ZkNote | null;
+
+/**
+ * PrivacyKeys
+ *
+ * Pure cryptographic derivation functions for the Orbinum shielded pool identity.
+ * These are protocol-level operations — independent of storage, UI, or session.
+ *
+ * Derivation scheme:
+ *   viewingKey = HKDF-SHA256(ikm=spendingKey_bytes, info="orbinum-ivk-v1") → 32 bytes
+ *   ownerPk    = BabyJubJub Ax from (spendingKey * Base8)                  → bigint
+ *
+ * Spending key derivation (from wallet signature):
+ *   message    = "orbinum-spending-key-v1\n${chainId}\n${address.toLowerCase()}"
+ *   skBytes    = HKDF-SHA256(ikm=sig_bytes, salt=empty, info="orbinum-sk-v1:${chainId}:${address}")
+ *   spendingKey = BigInt(skBytes_as_big_endian) % BN254_R  (if 0 → 1)
+ *
+ * The viewingKey is the symmetric key used by EncryptedMemo (ChaCha20-Poly1305).
+ * The ownerPk (x-coordinate) is included in note commitments.
+ */
+/**
+ * Returns the message string the user must sign with their wallet to derive
+ * a deterministic Orbinum spending key.
+ */
+declare function deriveSpendingKeyMessage(chainId: number, address: string): string;
+/**
+ * Derives an Orbinum spending key from a wallet signature.
+ *
+ * Uses HKDF-SHA256(ikm=sigBytes, salt=empty, info="orbinum-sk-v1:{chainId}:{address}")
+ * and reduces the resulting 32-byte value modulo BN254_R.
+ *
+ * @param signatureHex  0x-prefixed or bare hex of the wallet signature.
+ * @param chainId       Chain ID used when building the signing message.
+ * @param address       Signer address (EVM or SS58) used in the signing message.
+ * @returns bigint in [1, BN254_R)
+ */
+declare function deriveSpendingKeyFromSignature(signatureHex: string, chainId: number, address: string): Promise<bigint>;
+/**
+ * Derive a 32-byte viewing key from a spending key.
+ *   viewingKey = HKDF-SHA256(ikm=spendingKey_bytes, info="orbinum-ivk-v1")
+ */
+declare function deriveViewingKey(spendingKey: bigint): Uint8Array;
+/**
+ * Derive the BabyJubJub Ax (x-coordinate of the public key) from a spending key.
+ *   ownerPk = (spendingKey * BabyJubJub.Base8)[0]
+ *
+ * Returns 0n if BabyJubJub computation fails (e.g. invalid scalar).
+ */
+declare function deriveOwnerPk(spendingKey: bigint): bigint;
+
+/**
+ * PrivacyKeyManager
+ *
+ * In-memory manager for the user's Orbinum shielded-pool identity.
+ * Protocol-level module — no UI, no localStorage, no sessionStorage dependencies.
+ *
+ * Call `PrivacyKeyManager.load(spendingKey)` after deriving the key from a wallet
+ * signature (see `deriveSpendingKeyFromSignature`).  The caller (application layer)
+ * is responsible for key persistence and session caching.
+ *
+ * Derivation scheme:
+ *   spendingKey (bigint, BN254 scalar)
+ *     └── viewingKey   = HKDF-SHA256(spendingKey_bytes, info="orbinum-ivk-v1")  → 32 bytes
+ *     └── ownerPk      = BabyJubJub Ax from (spendingKey * Base8)               → bigint
+ */
+declare const PrivacyKeyManager: {
+    /**
+     * Load a spending key into the in-memory session.
+     * Derives viewingKey and ownerPk immediately.
+     * Replaces any previously loaded key.
+     */
+    load(spendingKey: bigint): Promise<void>;
+    /** Clear all key material from memory. Call on vault lock / sign-out. */
+    clear(): void;
+    /** Returns true if a spending key has been loaded. */
+    isLoaded(): boolean;
+    /** Returns the spending key. Throws if not loaded. */
+    getSpendingKey(): bigint;
+    /** Returns the 32-byte viewing key. Throws if not loaded. */
+    getViewingKey(): Uint8Array;
+    /** Returns the BabyJubJub owner public key (x-coordinate). Throws if not loaded. */
+    getOwnerPk(): bigint;
+    /** Returns the spending key as a 32-byte little-endian Uint8Array. Throws if not loaded. */
+    getSpendingKeyBytes(): Uint8Array;
+    /** Exports the spending key as a 0x-prefixed 64-char hex string. Throws if not loaded. */
+    exportHex(): string;
+    /**
+     * Load a spending key from a 0x-prefixed or bare hex string.
+     * Validates the key is in the valid range [1, BN254_R).
+     */
+    importFromHex(hex: string): Promise<void>;
+};
+
+/**
+ * VaultCrypto
+ *
+ * WebCrypto-based encryption utilities for protecting Orbinum vault data.
+ * Works in browser and Node.js 18+ (both expose the WebCrypto API as `crypto`).
+ * Pure functions — no state, no side effects.
+ *
+ * Key derivation: HKDF-SHA-256(ikm=spendingKeyBytes, salt=empty, info="orbinum-vault-key-v1")
+ * Cipher: AES-GCM 256
+ *
+ * BigInt serialisation uses `{ __bigint: "<decimal string>" }` so plain
+ * `JSON.stringify` never receives a bigint. Use `vaultReplacer` / `vaultReviver`
+ * for all vault payloads.
+ */
+/**
+ * `JSON.stringify` replacer that serialises bigint values as
+ * `{ __bigint: "<decimal string>" }` (JSON-safe).
+ */
+declare function vaultReplacer(_key: string, value: unknown): unknown;
+/**
+ * `JSON.parse` reviver that deserialises `{ __bigint: "<decimal string>" }`
+ * back into native bigint values.
+ */
+declare function vaultReviver(_key: string, value: unknown): unknown;
+/**
+ * Derives an AES-GCM-256 CryptoKey from spending key bytes using HKDF-SHA-256.
+ * The spending key carries ≥256 bits of entropy so no salt / iteration
+ * stretching is required.
+ *
+ * @param spendingKeyBytes 32-byte spending key (little-endian bigint representation).
+ */
+declare function deriveVaultKey(spendingKeyBytes: Uint8Array): Promise<CryptoKey>;
+/**
+ * Serialises `payload` to JSON (bigint-safe) and encrypts it with AES-GCM.
+ * Returns base64-encoded `iv` and `ciphertext`.
+ */
+declare function encryptJson(key: CryptoKey, payload: unknown): Promise<{
+    iv: string;
+    ciphertext: string;
+}>;
+/**
+ * Decrypts AES-GCM ciphertext and parses the JSON payload (bigint-safe).
+ * Throws `DOMException` on authentication failure (wrong key or corrupted data).
+ */
+declare function decryptJson(key: CryptoKey, iv: string, ciphertext: string): Promise<unknown>;
+
+/**
+ * Contract addresses and function selectors for all Orbinum EVM precompiles.
+ *
+ * Selectors are verified against the Rust source in frame/evm/precompile and
+ * computed as `bytes4(keccak256("<functionName>(<argTypes>)"))`.
+ */
+/** All precompile contract addresses. */
+declare const PRECOMPILE_ADDR: {
+    readonly EC_RECOVER: "0x0000000000000000000000000000000000000001";
+    readonly SHA256: "0x0000000000000000000000000000000000000002";
+    readonly RIPEMD160: "0x0000000000000000000000000000000000000003";
+    readonly IDENTITY: "0x0000000000000000000000000000000000000004";
+    readonly MODEXP: "0x0000000000000000000000000000000000000005";
+    readonly SHA3_FIPS256: "0x0000000000000000000000000000000000000400";
+    readonly EC_RECOVER_PUBKEY: "0x0000000000000000000000000000000000000401";
+    readonly CURVE25519_ADD: "0x0000000000000000000000000000000000000402";
+    readonly CURVE25519_SCALAR_MUL: "0x0000000000000000000000000000000000000403";
+    readonly ACCOUNT_MAPPING: "0x0000000000000000000000000000000000000800";
+    readonly SHIELDED_POOL: "0x0000000000000000000000000000000000000801";
+};
+
+/**
+ * Serialises a bigint as a 32-byte little-endian Uint8Array.
+ */
+declare function bigintTo32Le(n: bigint): Uint8Array;
+/**
+ * Deserialises a Uint8Array as a little-endian unsigned bigint.
+ */
+declare function bytesToBigintLE(bytes: Uint8Array): bigint;
+/**
+ * Serialises a bigint as a 32-byte big-endian Uint8Array.
+ */
+declare function bigintTo32Be(n: bigint): Uint8Array;
+/**
+ * Serialises a bigint as a 32-element little-endian number[].
+ * Useful when building SCALE-encoded arguments via polkadot-api.
+ */
+declare function bigintTo32LeArr(n: bigint): number[];
+/**
+ * Computes the Merkle path direction bits for a leaf at `leafIndex`
+ * in a binary Merkle tree of `depth` levels.
+ * bit 0 = bottom level (leaf), bit depth-1 = top level (root sibling).
+ */
+declare function computePathIndices(leafIndex: number, depth: number): number[];
+/**
+ * Decodes a little-endian hex string (0x-prefixed or bare) to a bigint.
+ * Equivalent to `bytesToBigintLE(fromHex(hex))`.
+ */
+declare function leHexToBigint(hex: string): bigint;
+
+/**
+ * Normalises an EVM address to lowercase with 0x prefix.
+ */
+declare function normalizeEvmAddress(addr: string): string;
+/**
+ * Returns true if the string looks like an SS58 encoded address
+ * (not a 0x-prefixed hex).
+ */
+declare function isSs58(addr: string): boolean;
+/**
+ * Returns true if the string looks like a 20-byte EVM address.
+ */
+declare function isEvmAddress(addr: string): boolean;
+/**
+ * Pads a 20-byte EVM address to a 32-byte account ID (H256)
+ * by prepending 12 zero bytes (Ethereum-compatible mapping).
+ */
+declare function evmAddressToAccountId(evmAddr: string): Uint8Array;
+/**
+ * Derives the implicit Substrate AccountId32 for an EVM address using the
+ * EeSuffixAddressMapping rule: AccountId32 = H160 ++ [0x00; 12].
+ *
+ * This is the same rule applied by pallet-account-mapping's fallback when
+ * there is no explicit `map_account` entry. Returns 0x-prefixed 64-char hex.
+ *
+ * @param evmAddr  0x-prefixed 20-byte EVM address.
+ */
+declare function evmToImplicitSubstrate(evmAddr: string): string;
+/**
+ * Returns true if the given AccountId32 hex was derived from an EVM address
+ * via the EeSuffixAddressMapping (last 12 bytes are zero).
+ *
+ * @param accountHex  0x-prefixed 64-char AccountId32 hex.
+ */
+declare function isImplicitEvmAccount(accountHex: string): boolean;
+/**
+ * Extracts the EVM address (H160) from an implicit Substrate AccountId32
+ * created by EeSuffixAddressMapping.  Throws if the account is not EVM-derived.
+ *
+ * @param accountHex  0x-prefixed 64-char AccountId32 hex.
+ */
+declare function implicitSubstrateToEvm(accountHex: string): string;
+/**
+ * Returns true if `addr` is a valid SS58 substrate address (not EVM).
+ */
+declare function isSubstrateAddress(addr: string): boolean;
+/**
+ * Returns true if `addr` is a Substrate SS58 address derived from an EVM H160
+ * via the EeSuffixAddressMapping rule (last 12 bytes of AccountId are zero).
+ */
+declare function isUnifiedAddress(addr: string): boolean;
+/**
+ * Converts a unified (EVM-derived) Substrate SS58 address to its EVM H160.
+ * Returns null for native Substrate accounts or invalid input.
+ */
+declare function substrateToEvm(addr: string): string | null;
+/**
+ * Converts an EVM H160 address to its Substrate SS58 equivalent
+ * using the EeSuffixAddressMapping rule: AccountId32 = H160 ++ [0x00; 12].
+ * Returns null on invalid input.
+ */
+declare function evmToSubstrate(addr: string): string | null;
+/**
+ * Converts a 32-byte AccountId hex (0x-prefixed or bare) to its SS58 string.
+ * Returns null on invalid input.
+ */
+declare function accountIdHexToSs58(hex: string): string | null;
+/**
+ * Converts a Substrate SS58 address to its AccountId32 as a 0x-prefixed 64-char hex.
+ * Returns null on invalid input.
+ */
+declare function substrateSs58ToAccountIdHex(addr: string): string | null;
+/**
+ * Universal converter: given any raw address string (SS58, 0x-prefixed 64-char
+ * AccountId hex, or EVM H160), returns the AccountId32 hex (0x-prefixed).
+ * Returns null on unrecognised input.
+ */
+declare function addressToAccountIdHex(addr: string): string | null;
+
+/**
+ * Types for the arguments passed to pallet-shielded-pool extrinsics.
+ * Byte arrays are represented as `number[]` to match SCALE encoding.
+ */
+/** Arguments for the `shield` extrinsic. */
+type ShieldArgs = {
+    assetId: number;
+    amount: bigint;
+    /** 32-byte Poseidon commitment (LE). */
+    commitment: number[];
+    /** 104-byte encrypted memo. */
+    encryptedMemo: number[];
+};
+/** Arguments for the `unshield` extrinsic. */
+type UnshieldArgs = {
+    /** Groth16 proof bytes. */
+    proof: number[];
+    /** 32-byte Merkle root (LE). */
+    merkleRoot: number[];
+    /** 32-byte Poseidon nullifier (LE). */
+    nullifier: number[];
+    assetId: number;
+    amount: bigint;
+    /** 32-byte recipient AccountId. */
+    recipient: number[];
+};
+/** Single input note for a private transfer. */
+type PrivateTransferInput = {
+    /** 32-byte Poseidon nullifier (LE). */
+    nullifier: number[];
+    /** 32-byte Poseidon commitment (LE). */
+    commitment: number[];
+};
+/** Single output note for a private transfer. */
+type PrivateTransferOutput = {
+    /** 32-byte Poseidon commitment (LE). */
+    commitment: number[];
+    /** 104-byte encrypted memo. */
+    memo: number[];
+};
+/** Arguments for the `private_transfer` extrinsic. */
+type PrivateTransferArgs = {
+    inputs: PrivateTransferInput[];
+    outputs: PrivateTransferOutput[];
+    /** Groth16 proof bytes. */
+    proof: number[];
+    /** 32-byte Merkle root (LE). */
+    merkleRoot: number[];
+};
+
+/**
+ * Types for events emitted by pallet-shielded-pool.
+ * Hex strings are 0x-prefixed 32-byte LE Poseidon values.
+ */
+/** Emitted by `shield()` when a note is deposited. */
+type ShieldedEvent = {
+    /** SS58 or 0x-prefixed AccountId of the depositor. */
+    depositor: string;
+    amount: bigint;
+    /** 0x-prefixed 32-byte commitment hex (LE). */
+    commitment: string;
+    /** 0x-prefixed encrypted memo hex. */
+    encryptedMemo: string;
+    /** Leaf index assigned in the Merkle tree. */
+    leafIndex: number;
+};
+/** Emitted by `private_transfer()`. */
+type PrivateTransferEvent = {
+    /** Input nullifiers (0x-prefixed 32-byte hex each). */
+    nullifiers: string[];
+    /** Output commitments (0x-prefixed 32-byte hex each). */
+    commitments: string[];
+    /** Encrypted memos for each output. */
+    encryptedMemos: string[];
+    /** Leaf indices assigned to output commitments. */
+    leafIndices: number[];
+};
+/** Emitted by `unshield()` when a note is withdrawn. */
+type UnshieldedEvent = {
+    /** 0x-prefixed 32-byte nullifier hex (LE). */
+    nullifier: string;
+    amount: bigint;
+    /** SS58 or 0x-prefixed AccountId of the recipient. */
+    recipient: string;
+};
+/** Emitted after every Merkle tree update. */
+type MerkleRootUpdatedEvent = {
+    /** 0x-prefixed previous root hex. */
+    oldRoot: string;
+    /** 0x-prefixed new root hex. */
+    newRoot: string;
+    /** New total number of leaves. */
+    treeSize: number;
+};
+/** Discriminated union of all shielded-pool events. */
+type ShieldedPoolEvent = {
+    type: 'Shielded';
+    data: ShieldedEvent;
+} | {
+    type: 'PrivateTransfer';
+    data: PrivateTransferEvent;
+} | {
+    type: 'Unshielded';
+    data: UnshieldedEvent;
+} | {
+    type: 'MerkleRootUpdated';
+    data: MerkleRootUpdatedEvent;
+};
+
+/** Configuration for IndexerClient. */
+interface IndexerClientConfig {
+    /** Base URL of the indexer REST API (no trailing slash). */
+    baseUrl: string;
+    /** Request timeout in ms. Default: 10_000. */
+    timeoutMs?: number;
+}
+/** Generic paginated result returned by list endpoints. */
+interface PaginatedResult<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+/** A shielded commitment (shield event) stored by the indexer. */
+interface ShieldedCommitment {
+    commitmentHex: string;
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    leafIndex: number;
+    /** Asset ID as decimal string (e.g. "0"). */
+    assetId: string;
+    /** SS58 or 0x-prefixed depositor address, null if not tracked. */
+    sender: string | null;
+    /** 0x-prefixed encrypted memo hex, null if not present. */
+    encryptedMemo: string | null;
+    timestampMs: number | null;
+}
+/** A spent nullifier stored by the indexer. */
+interface SpentNullifier {
+    nullifierHex: string;
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    txType: 'unshield' | 'private_transfer';
+    timestampMs: number | null;
+}
+/** A private transfer event stored by the indexer. */
+interface PrivateTransfer {
+    /** "{blockNumber}-{extrinsicIndex}" */
+    id: string;
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    /** JSON-encoded array of nullifier hex strings. */
+    inputNullifiersJson: string;
+    /** JSON-encoded array of commitment hex strings. */
+    outputCommitmentsJson: string;
+    /** JSON-encoded array of leaf index numbers. */
+    leafIndicesJson: string;
+    timestampMs: number | null;
+}
+/** An unshield event stored by the indexer. */
+interface Unshield {
+    /** "{blockNumber}-{extrinsicIndex}" */
+    id: string;
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    nullifierHex: string;
+    /** Asset ID as decimal string. */
+    assetId: string;
+    /** Amount as decimal string (bigint-safe). */
+    amount: string;
+    recipient: string;
+    timestampMs: number | null;
+}
+/** A Merkle root checkpoint stored by the indexer. */
+interface MerkleRoot {
+    id: number;
+    rootHex: string;
+    blockNumber: number;
+    oldRootHex: string | null;
+    treeSize: number;
+    timestampMs: number | null;
+}
+/** Response from the nullifier status endpoint. */
+interface NullifierStatusResult {
+    nullifier: string;
+    spent: boolean;
+    txType?: 'unshield' | 'private_transfer';
+    blockNumber?: number;
+}
+/**
+ * HTTP client for the Orbinum indexer REST API.
+ *
+ * All methods throw on network errors.
+ * Methods returning a single entity return `null` when the server responds 404.
+ */
+declare class IndexerClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: IndexerClientConfig);
+    private get;
+    private getOrNull;
+    private buildQuery;
+    /** Returns the total count of shielded commitments. */
+    getCommitmentsCount(): Promise<number>;
+    /** Returns a paginated list of shielded commitments. */
+    getCommitments(params?: {
+        page?: number;
+        limit?: number;
+        sinceLeafIndex?: number;
+    }): Promise<PaginatedResult<ShieldedCommitment>>;
+    /** Returns a single commitment by its hex string, or null if not found. */
+    getCommitmentByHex(hex: string): Promise<ShieldedCommitment | null>;
+    /** Returns a paginated list of spent nullifiers. */
+    getNullifiers(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResult<SpentNullifier>>;
+    /** Returns the spent/unspent status of a nullifier. */
+    getNullifierStatus(hex: string): Promise<NullifierStatusResult>;
+    /** Returns a paginated list of private transfer events. */
+    getTransfers(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResult<PrivateTransfer>>;
+    /** Returns a paginated list of unshield events. */
+    getUnshields(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResult<Unshield>>;
+    /** Returns a paginated list of Merkle root checkpoints. */
+    getMerkleRoots(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResult<MerkleRoot>>;
+    /** Returns the latest Merkle root, or null if none exists. */
+    getLatestMerkleRoot(): Promise<MerkleRoot | null>;
+}
+
+export { type AccountListing, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AddChainLinkParams, type AliasFullIdentity, type AliasInfo, type ChainInfo, type ChainLink, ChainModule, type CommitmentMerkleProof, CryptoPrecompiles, type DecryptedMemo, type DispatchAsLinkedParams, EncryptedMemo, EvmClient, type EvmSigner, type EvmTxRequest, type FullIdentityInfo, IndexerClient, type IndexerClientConfig, type ListingInfo, MerkleModule, type MerkleProof, type MerkleRoot, type MerkleRootUpdatedEvent, type MerkleTreeInfo, NoteBuilder, type NoteInput, type NullifierStatus, type NullifierStatusResult, OrbinumClient, type OrbinumClientConfig, PRECOMPILE_ADDR, type PaginatedResult, type PoolBalance, type PoolStats, PrivacyKeyManager, type PrivateLink, type PrivateTransfer, type PrivateTransferArgs, type PrivateTransferEvent, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PutOnSaleParams, type ResolvedAlias, SLIP0044_NAMESPACE, type ScanCommitment, type SetMetadataParams, type ShieldArgs, type ShieldParams, type ShieldResult, type ShieldedCommitment, type ShieldedEvent, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, type SignatureScheme, type SpentNullifier, SubstrateClient, type SupportedChain, type TransferInput, type TransferOutput, type TxResult, type Unshield, type UnshieldArgs, type UnshieldParams, type UnshieldedEvent, type ZkNote, accountIdHexToSs58, addressToAccountIdHex, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, bytesToBigintLE, computePathIndices, decryptJson, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveVaultKey, deriveViewingKey, encryptJson, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToSubstrate, fromHex, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, normalizeEvmAddress, substrateSs58ToAccountIdHex, substrateToEvm, toHex, tryDecryptNote, vaultReplacer, vaultReviver };