@xchainjs/xchain-monero 0.2.0

package/lib/lws.d.ts

@@ -0,0 +1,88 @@
+/**
+ * MyMonero-compatible Light Wallet Server (LWS) REST API client.
+ * LWS accepts private view keys and returns pre-decoded balances/transactions,
+ * avoiding the need for client-side blockchain scanning.
+ */
+export interface LWSLoginResponse {
+    new_address: boolean;
+    generated_locally: boolean;
+    start_height: number;
+}
+export interface LWSSpentOutput {
+    amount: string;
+    key_image: string;
+    tx_pub_key: string;
+    out_index: number;
+    mixin: number;
+}
+export interface LWSAddressInfoResponse {
+    locked_funds: string;
+    total_received: string;
+    total_sent: string;
+    scanned_height: number;
+    scanned_block_height: number;
+    start_height: number;
+    transaction_height: number;
+    blockchain_height: number;
+    spent_outputs: LWSSpentOutput[];
+}
+export interface LWSTxInfo {
+    id: number;
+    hash: string;
+    timestamp: string;
+    total_received: string;
+    total_sent: string;
+    height: number;
+    spent_outputs: LWSSpentOutput[];
+    payment_id: string;
+    coinbase: boolean;
+    mempool: boolean;
+    mixin: number;
+}
+export interface LWSAddressTxsResponse {
+    total_received: string;
+    scanned_height: number;
+    scanned_block_height: number;
+    start_height: number;
+    blockchain_height: number;
+    transactions: LWSTxInfo[];
+}
+export interface LWSUnspentOutput {
+    amount: string;
+    public_key: string;
+    index: number;
+    global_index: number;
+    tx_id: number;
+    tx_hash: string;
+    tx_prefix_hash: string;
+    tx_pub_key: string;
+    timestamp: string;
+    height: number;
+    rct: string;
+}
+export interface LWSUnspentOutsResponse {
+    amount: string;
+    outputs: LWSUnspentOutput[];
+    per_byte_fee: number;
+    fee_mask: number;
+    fork_version: number;
+}
+/**
+ * Register wallet address with LWS for scanning.
+ * Must be called before other endpoints will return data.
+ */
+export declare const login: (url: string, address: string, viewKeyHex: string) => Promise<LWSLoginResponse>;
+/**
+ * Get balance summary for an address.
+ * Returns total received/sent in piconero strings.
+ */
+export declare const getAddressInfo: (url: string, address: string, viewKeyHex: string) => Promise<LWSAddressInfoResponse>;
+/**
+ * Get transaction history for an address.
+ * Returns transactions with per-tx received/sent amounts.
+ */
+export declare const getAddressTxs: (url: string, address: string, viewKeyHex: string) => Promise<LWSAddressTxsResponse>;
+/**
+ * Get unspent outputs for transaction building.
+ */
+export declare const getUnspentOuts: (url: string, address: string, viewKeyHex: string, amount?: string) => Promise<LWSUnspentOutsResponse>;

package/lib/scanner.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Daemon-based blockchain scanner for Monero.
+ * Scans blocks using the view key to find owned outputs and detect spent outputs.
+ * Used as fallback when no LWS (Light Wallet Server) is available.
+ *
+ * This is intentionally slow — scanning the full chain from genesis is impractical.
+ * Use a restore height close to when the wallet was created.
+ */
+export interface OwnedOutput {
+    txHash: string;
+    outputIndex: number;
+    amount: bigint;
+    globalIndex: number;
+    publicKey: Uint8Array;
+    txPubKey: Uint8Array;
+    keyImage: string;
+    height: number;
+    timestamp: number;
+}
+export interface ScanState {
+    /** Last fully scanned block height */
+    lastHeight: number;
+    /** Owned unspent outputs */
+    ownedOutputs: OwnedOutput[];
+    /** Set of spent key images */
+    spentKeyImages: Set<string>;
+}
+interface ScanProgress {
+    currentHeight: number;
+    totalHeight: number;
+    outputsFound: number;
+}
+/**
+ * Scan a range of blocks for owned outputs.
+ * Uses batched RPC calls: fetches block tx hashes in parallel, then
+ * fetches all transactions in a single get_transactions call per batch.
+ */
+export declare function scanBlocks(daemonUrl: string, privViewKey: Uint8Array, pubSpendKey: Uint8Array, privSpendKey: Uint8Array, fromHeight: number, toHeight: number, onProgress?: (progress: ScanProgress) => void): Promise<{
+    ownedOutputs: OwnedOutput[];
+    spentKeyImages: Set<string>;
+}>;
+/**
+ * Compute balance from scan results.
+ * Balance = sum of owned outputs whose key images are NOT in the spent set.
+ */
+export declare function computeBalance(ownedOutputs: OwnedOutput[], spentKeyImages: Set<string>): bigint;
+/**
+ * Get unspent outputs from scan results.
+ */
+export declare function getUnspentOutputs(ownedOutputs: OwnedOutput[], spentKeyImages: Set<string>): OwnedOutput[];
+export {};

package/lib/tx/builder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Monero transaction builder.
+ * Orchestrates: stealth addresses, Pedersen commitments, ECDH encryption,
+ * CLSAG signatures, Bulletproofs+ range proofs, and serialization.
+ *
+ * Reference: monero/src/wallet/wallet2.cpp (create_transactions_2)
+ */
+import type { MoneroTransaction } from './types';
+/** Input to spend */
+export interface SpendableOutput {
+    globalIndex: number;
+    amount: bigint;
+    mask: Uint8Array;
+    txPubKey: Uint8Array;
+    outputIndex: number;
+    publicKey: Uint8Array;
+}
+/** Destination output */
+export interface Destination {
+    pubViewKey: Uint8Array;
+    pubSpendKey: Uint8Array;
+    amount: bigint;
+}
+/** Result of building a transaction */
+export interface BuiltTransaction {
+    tx: MoneroTransaction;
+    txHex: string;
+    txHash: string;
+}
+/**
+ * Build a complete Monero RingCT transaction.
+ *
+ * @param inputs - Spendable outputs to use as inputs
+ * @param destinations - Recipients + amounts
+ * @param changeDestination - Change address keys (pubView, pubSpend)
+ * @param fee - Transaction fee in piconero
+ * @param privViewKey - Sender's private view key
+ * @param privSpendKey - Sender's private spend key
+ * @param daemonUrl - Daemon RPC URL for decoy selection
+ * @returns Built transaction ready for broadcast
+ */
+export declare function buildTransaction(inputs: SpendableOutput[], destinations: Destination[], changeDestination: {
+    pubViewKey: Uint8Array;
+    pubSpendKey: Uint8Array;
+}, fee: bigint, privViewKey: Uint8Array, privSpendKey: Uint8Array, daemonUrl: string): Promise<BuiltTransaction>;

package/lib/tx/decoySelection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Decoy output selection for Monero ring signatures.
+ * Uses gamma distribution (shape=19.28, scale=1/1.61) matching Monero's wallet2.
+ *
+ * Reference: monero/src/wallet/wallet2.cpp (get_outs)
+ */
+/**
+ * Select decoy global output indices for ring signature construction.
+ *
+ * @param realGlobalIndex - Global output index of the real input
+ * @param numOutputs - Total number of outputs on chain
+ * @param newestHeight - Current blockchain height
+ * @param outputDistribution - Cumulative output distribution per block
+ * @param distStartHeight - Start height of distribution data
+ * @returns Array of RING_SIZE - 1 decoy global indices (excluding the real one)
+ */
+export declare function selectDecoys(realGlobalIndex: number, numOutputs: number, newestHeight: number, outputDistribution: number[], distStartHeight: number): number[];
+/**
+ * Build sorted ring with real index.
+ * Returns the ring indices (sorted) and the position of the real input.
+ */
+export declare function buildRingIndices(realGlobalIndex: number, decoys: number[]): {
+    indices: number[];
+    realIndex: number;
+};
+/**
+ * Convert absolute global indices to relative offsets (as stored in tx).
+ */
+export declare function toRelativeOffsets(sortedIndices: number[]): bigint[];

package/lib/tx/serialize.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Monero transaction binary serialization.
+ * Reference: monero/src/cryptonote_basic/cryptonote_format_utils.cpp
+ */
+import type { MoneroTransaction, RctSignatures, ClsagSig, BPPlusProof } from './types';
+/**
+ * Encode a number as a Monero varint (7 bits per byte, MSB = continuation flag).
+ */
+export declare function writeVarint(n: bigint | number): Uint8Array;
+/**
+ * Serialize the transaction prefix (everything except RingCT signatures).
+ */
+export declare function serializeTxPrefix(tx: MoneroTransaction): Uint8Array;
+/**
+ * Compute the transaction prefix hash (keccak256 of serialized prefix).
+ * This is the message signed by CLSAG.
+ */
+export declare function txPrefixHash(tx: MoneroTransaction): Uint8Array;
+/**
+ * Serialize the RCT signature base (type, fee, encrypted amounts, output commitments).
+ */
+export declare function serializeRctBase(rct: RctSignatures): Uint8Array;
+/**
+ * Serialize a CLSAG signature.
+ */
+export declare function serializeClsag(sig: ClsagSig): Uint8Array;
+/**
+ * Serialize a Bulletproofs+ proof.
+ */
+export declare function serializeBPPlus(proof: BPPlusProof): Uint8Array;
+/**
+ * Serialize the prunable RCT data (pseudo-outputs, CLSAGs, BP+ proofs).
+ */
+export declare function serializeRctPrunable(rct: RctSignatures): Uint8Array;
+/**
+ * Compute the RCT signature hash (message for CLSAG signing).
+ * hash = keccak256(prefixHash || keccak256(rctBase) || keccak256(rctPrunable))
+ */
+export declare function rctSigHash(prefixHash: Uint8Array, rctBase: Uint8Array, rctPrunable: Uint8Array): Uint8Array;
+/**
+ * Serialize a complete transaction.
+ */
+export declare function serializeTransaction(tx: MoneroTransaction): Uint8Array;

package/lib/tx/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Monero transaction types for RCTTypeCLSAG transactions.
+ */
+/** A transaction input (key input) */
+export interface TxInput {
+    amount: bigint;
+    keyOffsets: bigint[];
+    keyImage: Uint8Array;
+}
+/** A transaction output */
+export interface TxOutput {
+    amount: bigint;
+    key: Uint8Array;
+    viewTag: number;
+}
+/** CLSAG signature for one input */
+export interface ClsagSig {
+    s: Uint8Array[];
+    c1: Uint8Array;
+    D: Uint8Array;
+}
+/** Bulletproofs+ range proof */
+export interface BPPlusProof {
+    A: Uint8Array;
+    A1: Uint8Array;
+    B: Uint8Array;
+    r1: Uint8Array;
+    s1: Uint8Array;
+    d1: Uint8Array;
+    L: Uint8Array[];
+    R: Uint8Array[];
+}
+/** RingCT signatures (type 6 = RCTTypeBulletproofPlus) */
+export interface RctSignatures {
+    type: number;
+    txnFee: bigint;
+    ecdhInfo: Uint8Array[];
+    outPk: Uint8Array[];
+    pseudoOuts: Uint8Array[];
+    clsags: ClsagSig[];
+    bppProofs: BPPlusProof[];
+}
+/** Complete Monero transaction */
+export interface MoneroTransaction {
+    version: number;
+    unlockTime: bigint;
+    inputs: TxInput[];
+    outputs: TxOutput[];
+    extra: Uint8Array;
+    rctSignatures: RctSignatures;
+}
+/** Ring member (decoy or real) with public key and commitment */
+export interface RingMember {
+    dest: Uint8Array;
+    mask: Uint8Array;
+}

package/lib/types.d.ts

@@ -0,0 +1,24 @@
+import { Balance as BaseBalance, ExplorerProviders, Network, Tx as BaseTx, TxParams as BaseTxParams, TxsPage as BaseTxsPage, XChainClientParams } from '@xchainjs/xchain-client';
+import { Asset } from '@xchainjs/xchain-util';
+/**
+ * Monero client params
+ */
+export type XMRClientParams = XChainClientParams & {
+    explorerProviders: ExplorerProviders;
+    daemonUrls?: Record<Network, string[]>;
+    lwsUrls?: Record<Network, string[]>;
+    /** Block height to start scanning from when using daemon fallback (no LWS). Set to wallet creation height to avoid full chain scan. */
+    restoreHeight?: number;
+};
+export type Balance = BaseBalance & {
+    asset: Asset;
+};
+export type TxParams = BaseTxParams & {
+    asset?: Asset;
+};
+export type Tx = BaseTx & {
+    asset: Asset;
+};
+export type TxsPage = BaseTxsPage & {
+    txs: Tx[];
+};

package/lib/utils.d.ts

@@ -0,0 +1,52 @@
+import { Network } from '@xchainjs/xchain-client';
+/**
+ * Monero network type values matching monero-ts MoneroNetworkType enum
+ */
+export declare const MoneroNetworkType: {
+    readonly MAINNET: 0;
+    readonly TESTNET: 1;
+    readonly STAGENET: 2;
+};
+/**
+ * Maps XChainJS Network to Monero network type
+ */
+export declare const getMoneroNetworkType: (network: Network) => number;
+/**
+ * Validates a Monero address format.
+ * Standard addresses are 95 chars, integrated addresses are 106 chars.
+ * Uses base58 character set and prefix validation.
+ */
+export declare const validateMoneroAddress: (address: string) => boolean;
+/**
+ * Reduces a 32-byte value modulo the ed25519 group order.
+ * Required to produce valid Monero private keys from arbitrary 32-byte seeds.
+ */
+export declare const scReduce32: (bytes: Uint8Array) => Uint8Array;
+/**
+ * Converts a Uint8Array to hex string
+ */
+export declare const bytesToHex: (bytes: Uint8Array) => string;
+/**
+ * Converts a hex string to Uint8Array
+ */
+export declare const hexToBytes: (hex: string) => Uint8Array;
+/**
+ * Scalar multiplication: (a * b) mod l
+ */
+export declare function scMul(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Scalar multiply-add: (a * b + c) mod l
+ */
+export declare function scMulAdd(a: Uint8Array, b: Uint8Array, c: Uint8Array): Uint8Array;
+/**
+ * Scalar multiply-subtract: (c - a * b) mod l
+ */
+export declare function scMulSub(a: Uint8Array, b: Uint8Array, c: Uint8Array): Uint8Array;
+/**
+ * Hash to scalar: keccak256(data) reduced mod l
+ */
+export declare function hashToScalar(data: Uint8Array): Uint8Array;
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@xchainjs/xchain-monero",
+  "version": "0.2.0",
+  "description": "Monero (XMR) client for XChainJS",
+  "keywords": [
+    "Monero",
+    "XMR",
+    "XChain"
+  ],
+  "author": "THORChain",
+  "homepage": "https://github.com/xchainjs/xchainjs-lib",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "module": "lib/index.esm.js",
+  "typings": "lib/index.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:xchainjs/xchainjs-lib.git"
+  },
+  "scripts": {
+    "clean": "rm -rf .turbo && rm -rf lib",
+    "build": "yarn clean && rollup -c --bundleConfigAsCjs",
+    "build:release": "yarn exec rm -rf release && yarn pack && yarn exec \"mkdir release && tar zxvf package.tgz --directory release && rm package.tgz\"",
+    "test": "jest",
+    "e2e": "jest --config jest.config.e2e.mjs",
+    "lint": "eslint --config ../../eslint.config.mjs \"{src,__tests__}/**/*.ts\" --fix --max-warnings 0"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1",
+    "@xchainjs/xchain-client": "2.0.11",
+    "@xchainjs/xchain-crypto": "1.0.6",
+    "@xchainjs/xchain-util": "2.0.6",
+    "micro-key-producer": "^0.7.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "release/package"
+  }
+}