@xchainjs/xchain-monero 0.2.0

package/README.md

@@ -0,0 +1,66 @@
+# `@xchainjs/xchain-monero`
+
+Monero (XMR) client for XChainJS — a pure JavaScript implementation with no WASM dependencies.
+
+## Overview
+
+This package provides a Monero client that implements the standard XChainJS `XChainClient` interface. It supports address derivation, balance queries, transaction history, fee estimation, and transaction building/broadcasting.
+
+Key design decisions:
+
+- **Pure JS** — Uses `@noble/curves`, `@noble/hashes`, and `micro-key-producer` for all cryptographic operations. No native modules or WASM, so it works in both Node.js and browser environments.
+- **MyMonero LWS** — Balance and UTXO queries go through a Light Wallet Server (LWS) API, defaulting to `api.mymonero.com`.
+- **Monero Daemon RPC** — Fee estimation and transaction broadcasting use a standard Monero daemon node.
+- **SLIP-10 key derivation** — Derives Monero spend/view keys from a BIP-39 mnemonic via SLIP-10 (`m/44'/128'/account'`).
+
+## Installation
+
+```bash
+yarn add @xchainjs/xchain-monero
+```
+
+## Usage
+
+```typescript
+import { Client, defaultXMRParams } from '@xchainjs/xchain-monero'
+import { Network } from '@xchainjs/xchain-client'
+
+const client = new Client({
+  ...defaultXMRParams,
+  network: Network.Mainnet,
+  phrase: 'your mnemonic phrase here',
+})
+
+// Get address
+const address = await client.getAddressAsync()
+
+// Get balance
+const balances = await client.getBalance(address)
+
+// Transfer
+const txHash = await client.transfer({
+  recipient: '4...',
+  amount: baseAmount(1000000000000, 12), // 1 XMR
+})
+```
+
+## Architecture
+
+```
+src/
+├── client.ts          # XChainClient implementation
+├── const.ts           # Chain constants, default params
+├── types.ts           # Client parameter types
+├── utils.ts           # Address derivation, key helpers
+├── lws.ts             # MyMonero Light Wallet Server API
+├── daemon.ts          # Monero daemon RPC client
+└── tx/
+    ├── builder.ts     # Transaction construction
+    ├── serialize.ts   # Binary serialization
+    ├── decoySelection.ts  # Ring member (decoy) selection
+    └── types.ts       # Transaction types
+```
+
+## License
+
+MIT

package/lib/client.d.ts

@@ -0,0 +1,76 @@
+import { AssetInfo, BaseXChainClient, Fees, PreparedTx, TxHash, TxHistoryParams } from '@xchainjs/xchain-client';
+import { Address } from '@xchainjs/xchain-util';
+import { Balance, Tx, TxParams, TxsPage, XMRClientParams } from './types';
+export declare class Client extends BaseXChainClient {
+    private explorerProviders;
+    private daemonUrls;
+    private lwsUrls;
+    private lwsLoggedIn;
+    private restoreHeight;
+    /** Cached scan state for daemon fallback */
+    private scanCache;
+    constructor(params?: XMRClientParams);
+    getAssetInfo(): AssetInfo;
+    getExplorerUrl(): string;
+    getExplorerAddressUrl(address: Address): string;
+    getExplorerTxUrl(txID: TxHash): string;
+    getFullDerivationPath(walletIndex: number): string;
+    /**
+     * Get the current address asynchronously.
+     * Derives keys from mnemonic and encodes as Monero address (pure JS, no WASM).
+     */
+    getAddressAsync(index?: number): Promise<string>;
+    /**
+     * @deprecated Use getAddressAsync instead
+     */
+    getAddress(): string;
+    validateAddress(address: Address): boolean;
+    /**
+     * Get balance via LWS, falling back to daemon scanning if LWS is unavailable.
+     */
+    getBalance(address: Address): Promise<Balance[]>;
+    /**
+     * Get transaction fees via daemon RPC.
+     */
+    getFees(): Promise<Fees>;
+    /**
+     * Get transaction details by hash via daemon RPC.
+     */
+    getTransactionData(txId: string): Promise<Tx>;
+    /**
+     * Get transaction history via LWS, falling back to daemon scanning.
+     * Due to Monero privacy, counterparty addresses are unavailable;
+     * the own address is used with net amount for from/to.
+     */
+    getTransactions(params?: TxHistoryParams): Promise<TxsPage>;
+    /**
+     * Transfer XMR to a recipient address.
+     * Builds a complete RingCT transaction with CLSAG signatures and Bulletproofs+ range proof.
+     */
+    transfer(params: TxParams): Promise<string>;
+    /**
+     * Broadcast a signed transaction hex to the network.
+     * Note: The returned hash is keccak256 of the raw tx blob, which differs from
+     * the canonical Monero txid (three-hash construction). Use transfer() for the correct txid.
+     */
+    broadcastTx(txHex: string): Promise<TxHash>;
+    /**
+     * Prepare an unsigned transaction.
+     * Monero transactions require private key context for ring signature
+     * construction, so this method is not supported.
+     */
+    prepareTx(_params: TxParams): Promise<PreparedTx>;
+    /**
+     * Get the private view key hex for a wallet index.
+     */
+    private getViewKeyHex;
+    /**
+     * Derives private spend key from BIP-39 mnemonic via SLIP-10 derivation.
+     */
+    private getPrivateSpendKey;
+    /**
+     * Scan the blockchain via daemon RPC to find owned outputs.
+     * Uses cached results and scans incrementally from the last scanned height.
+     */
+    private daemonScan;
+}

package/lib/const.d.ts

@@ -0,0 +1,15 @@
+import { Asset } from '@xchainjs/xchain-util';
+import { XMRClientParams } from './types';
+/**
+ * Monero chain symbol
+ */
+export declare const XMRChain: "XMR";
+/**
+ * Monero native asset decimals (piconero = 10^-12 XMR)
+ */
+export declare const XMR_DECIMALS = 12;
+/**
+ * Monero native asset
+ */
+export declare const AssetXMR: Asset;
+export declare const defaultXMRParams: XMRClientParams;

package/lib/crypto/address.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Encodes a standard Monero address from public spend/view keys.
+ * Format: [1-byte prefix][32-byte pubSpend][32-byte pubView][4-byte checksum]
+ * Result is 69 bytes → 95 base58 characters.
+ */
+export declare const encodeAddress: (publicSpendKey: Uint8Array, publicViewKey: Uint8Array, networkType: number) => string;
+/**
+ * Decodes a standard Monero address into its public spend/view keys.
+ * Validates the checksum.
+ */
+export declare const decodeAddress: (address: string) => {
+    publicSpendKey: Uint8Array;
+    publicViewKey: Uint8Array;
+    networkType: number;
+};

package/lib/crypto/base58monero.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Monero's custom base58 encoding.
+ * Unlike Bitcoin's base58, Monero encodes in fixed 8-byte blocks → 11-char blocks.
+ * The last block may be shorter depending on remaining bytes.
+ */
+/**
+ * Encodes a Uint8Array using Monero's base58 scheme.
+ */
+export declare const cnBase58Encode: (data: Uint8Array) => string;
+/**
+ * Decodes a Monero base58-encoded string to Uint8Array.
+ */
+export declare const cnBase58Decode: (encoded: string) => Uint8Array;

package/lib/crypto/bulletproofsPlus.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bulletproofs+ range proof implementation for Monero.
+ * Proves amounts are in [0, 2^64) without revealing them.
+ *
+ * Reference: monero/src/ringct/bulletproofs_plus.cc
+ */
+import type { BPPlusProof } from '../tx/types';
+/**
+ * Generate a Bulletproofs+ range proof.
+ *
+ * @param amounts - Array of amounts (bigint, each < 2^64)
+ * @param masks - Array of blinding factors (32-byte scalars)
+ * @returns BP+ proof
+ */
+export declare function bulletproofPlusProve(amounts: bigint[], masks: Uint8Array[]): BPPlusProof;
+/**
+ * Verify a Bulletproofs+ range proof.
+ *
+ * @param proof - BP+ proof to verify
+ * @param commitments - Output commitments (the actual commitments, NOT /8)
+ * @returns true if valid
+ */
+export declare function bulletproofPlusVerify(proof: BPPlusProof, commitments: Uint8Array[]): boolean;

package/lib/crypto/clsag.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CLSAG (Concise Linkable Spontaneous Anonymous Group) signature.
+ * Used in Monero RingCT for input authorization + commitment balance proof.
+ *
+ * Reference: monero/src/ringct/rctSigs.cpp (CLSAG_Gen, verRctCLSAGSimple)
+ */
+import type { ClsagSig, RingMember } from '../tx/types';
+/**
+ * CLSAG signing.
+ *
+ * @param message - 32-byte transaction prefix hash
+ * @param ring - Ring members (dest + mask for each)
+ * @param Cout - Pseudo-output commitment (C_offset)
+ * @param secretKey - Signer's one-time private key (p)
+ * @param secretMask - Commitment mask difference: z = input_mask - pseudo_out_mask
+ * @param realIndex - Index of real signer in ring
+ * @param keyImage - Pre-computed key image (p * Hp(P[l]))
+ * @returns CLSAG signature
+ */
+export declare function clsagSign(message: Uint8Array, ring: RingMember[], Cout: Uint8Array, secretKey: Uint8Array, secretMask: Uint8Array, realIndex: number, keyImage: Uint8Array): ClsagSig;
+/**
+ * CLSAG verification.
+ *
+ * @param message - 32-byte transaction prefix hash
+ * @param ring - Ring members (dest + mask for each)
+ * @param Cout - Pseudo-output commitment
+ * @param keyImage - Key image
+ * @param sig - CLSAG signature to verify
+ * @returns true if valid
+ */
+export declare function clsagVerify(message: Uint8Array, ring: RingMember[], Cout: Uint8Array, keyImage: Uint8Array, sig: ClsagSig): boolean;

package/lib/crypto/ecdh.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ECDH-based amount encryption/decryption for Monero RingCT.
+ *
+ * Shared secret: ss = 8 * r * A (or 8 * a * R)
+ * Amount mask: first 8 bytes of keccak256("amount" || Hs(ss || index))
+ * Encrypted amount: XOR of 8-byte LE amount with mask
+ */
+/**
+ * Derive ECDH shared secret point from tx private key and recipient's public view key.
+ * Returns the compressed point bytes of r*A.
+ */
+export declare function deriveSharedSecret(txPrivKey: Uint8Array, pubViewKey: Uint8Array): Uint8Array;
+/**
+ * Compute the 1-byte view tag for an output.
+ * view_tag = keccak256("view_tag" || derivation || varint(outputIndex))[0]
+ */
+export declare function computeViewTag(sharedSecret: Uint8Array, outputIndex: number): number;
+/**
+ * Encrypt an amount using ECDH-derived mask.
+ * @param amount - Amount in piconero (bigint)
+ * @param sharedSecret - ECDH shared secret (r*A compressed bytes)
+ * @param outputIndex - Output index for key derivation
+ * @returns 8-byte encrypted amount
+ */
+export declare function encryptAmount(amount: bigint, sharedSecret: Uint8Array, outputIndex: number): Uint8Array;
+/**
+ * Decrypt an amount using ECDH-derived mask.
+ * @param encrypted - 8-byte encrypted amount
+ * @param sharedSecret - ECDH shared secret (a*R compressed bytes)
+ * @param outputIndex - Output index for key derivation
+ * @returns Decrypted amount in piconero
+ */
+export declare function decryptAmount(encrypted: Uint8Array, sharedSecret: Uint8Array, outputIndex: number): bigint;

package/lib/crypto/hashToPoint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Monero's hash_to_ec / ge_fromfe_frombytes_vartime implementation.
+ * Ported from CoinSpace/monerolib (pure JS Monero library).
+ *
+ * Maps arbitrary data to an ed25519 point. This is NOT standard hash-to-curve
+ * (RFC 9380) — it matches Monero's specific algorithm from crypto-ops.c.
+ */
+declare const ExtPoint: import("@noble/curves/abstract/edwards").EdwardsPointCons;
+type Point = InstanceType<typeof ExtPoint>;
+/**
+ * Hash arbitrary data to an ed25519 point (Monero's hash_to_ec).
+ * Algorithm: ge_fromfe_frombytes_vartime
+ */
+export declare function hashToPoint(data: Uint8Array): Point;
+export {};

package/lib/crypto/keyImage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Key image generation for Monero ring signatures.
+ * KI = x * Hp(P) where x is the private key and P is the public key.
+ */
+/**
+ * Generate a key image from a private/public key pair.
+ * KI = x * Hp(P)
+ * @param privKey - Private key (32-byte scalar LE)
+ * @param pubKey - Corresponding public key (32-byte compressed point)
+ * @returns Key image as 32-byte compressed point
+ */
+export declare function generateKeyImage(privKey: Uint8Array, pubKey: Uint8Array): Uint8Array;

package/lib/crypto/keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Derives an ed25519 public key from a raw private key scalar.
+ * Unlike standard EdDSA (which applies SHA-512 + clamping), Monero uses the raw scalar directly.
+ */
+export declare const secretKeyToPublicKey: (privateKey: Uint8Array) => Uint8Array;
+/**
+ * Derives the private view key from a private spend key.
+ * view_key = sc_reduce32(keccak256(spend_key))
+ */
+export declare const derivePrivateViewKey: (privateSpendKey: Uint8Array) => Uint8Array;
+/**
+ * Derives all four Monero keys from a private spend key.
+ */
+export declare const deriveKeyPairs: (privateSpendKey: Uint8Array) => {
+    privateSpendKey: Uint8Array;
+    publicSpendKey: Uint8Array;
+    privateViewKey: Uint8Array;
+    publicViewKey: Uint8Array;
+};

package/lib/crypto/pedersen.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pedersen commitment scheme for Monero.
+ * C = mask*G + amount*H
+ */
+declare const ExtPoint: import("@noble/curves/abstract/edwards").EdwardsPointCons;
+type Point = InstanceType<typeof ExtPoint>;
+/**
+ * Get the Pedersen generator H.
+ */
+export declare function getH(): Point;
+/**
+ * Create a Pedersen commitment: C = mask*G + amount*H
+ * @param mask - Blinding factor (32-byte scalar LE)
+ * @param amount - Amount to commit to (bigint)
+ */
+export declare function commit(mask: Uint8Array, amount: bigint): Point;
+/**
+ * Create a zero-mask commitment for fees: C = 0*G + amount*H = amount*H
+ * Used for fee commitments where the mask is publicly known to be 0.
+ */
+export declare function zeroCommit(amount: bigint): Point;
+export {};

package/lib/crypto/stealth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Monero stealth address (one-time address) derivation.
+ *
+ * Output key: P = Hs(r*A || i)*G + B
+ * - r: tx private key
+ * - A: recipient's public view key
+ * - B: recipient's public spend key
+ * - i: output index
+ * - Hs: keccak256 -> sc_reduce32 (hash to scalar)
+ *
+ * Input key recovery: x = Hs(a*R || i) + b
+ * - a: recipient's private view key
+ * - R: tx public key (r*G)
+ * - b: recipient's private spend key
+ */
+/**
+ * Derive the one-time output public key for a transaction output.
+ * P = Hs(r*A || i)*G + B
+ *
+ * @param txPrivKey - Transaction private key r (32 bytes)
+ * @param recipPubViewKey - Recipient's public view key A (32 bytes)
+ * @param recipPubSpendKey - Recipient's public spend key B (32 bytes)
+ * @param outputIndex - Output index i
+ * @returns One-time public key P (32 bytes)
+ */
+export declare function deriveOutputKey(txPrivKey: Uint8Array, recipPubViewKey: Uint8Array, recipPubSpendKey: Uint8Array, outputIndex: number): Uint8Array;
+/**
+ * Derive the one-time private key for spending a received output.
+ * x = Hs(a*R || i) + b
+ *
+ * @param txPubKey - Transaction public key R = r*G (32 bytes)
+ * @param privViewKey - Recipient's private view key a (32 bytes)
+ * @param privSpendKey - Recipient's private spend key b (32 bytes)
+ * @param outputIndex - Output index i
+ * @returns One-time private key x (32 bytes)
+ */
+export declare function deriveInputKey(txPubKey: Uint8Array, privViewKey: Uint8Array, privSpendKey: Uint8Array, outputIndex: number): Uint8Array;
+/**
+ * Check if an output belongs to us.
+ * Computes P' = Hs(a*R || i)*G + B and checks if P' == P.
+ *
+ * @param txPubKey - Transaction public key R (32 bytes)
+ * @param privViewKey - Our private view key a (32 bytes)
+ * @param pubSpendKey - Our public spend key B (32 bytes)
+ * @param outputKey - The output's public key P (32 bytes)
+ * @param outputIndex - Output index i
+ * @returns true if the output belongs to us
+ */
+export declare function isOutputForUs(txPubKey: Uint8Array, privViewKey: Uint8Array, pubSpendKey: Uint8Array, outputKey: Uint8Array, outputIndex: number): boolean;

package/lib/daemon.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Monero daemon HTTP JSON-RPC client.
+ * Provides raw RPC calls without depending on monero-ts.
+ */
+interface TxEntry {
+    tx_hash: string;
+    as_hex: string;
+    block_height: number;
+    block_timestamp: number;
+    in_pool: boolean;
+}
+interface SendRawTxResponse {
+    status: string;
+    reason?: string;
+    double_spend: boolean;
+}
+/**
+ * Get fee estimate from daemon.
+ * Returns fee per byte in piconero.
+ */
+export declare const getFeeEstimate: (url: string) => Promise<number>;
+/**
+ * Get transaction details by hash(es).
+ */
+export declare const getTransactions: (url: string, txHashes: string[]) => Promise<TxEntry[]>;
+/**
+ * Get outputs by global indices (for building ring members).
+ */
+export interface OutputEntry {
+    key: string;
+    mask: string;
+    unlocked: boolean;
+    height: number;
+    txid: string;
+}
+export declare const getOuts: (url: string, outputs: {
+    amount: number;
+    index: number;
+}[]) => Promise<OutputEntry[]>;
+/**
+ * Get output distribution for decoy selection.
+ */
+export declare const getOutputDistribution: (url: string, fromHeight?: number, toHeight?: number) => Promise<{
+    distribution: number[];
+    startHeight: number;
+    base: number;
+}>;
+/**
+ * Get current blockchain height.
+ */
+export declare const getHeight: (url: string) => Promise<number>;
+/**
+ * Get block data at a specific height, including transaction hashes.
+ */
+export interface BlockHeader {
+    height: number;
+    timestamp: number;
+    num_txes: number;
+}
+export declare const getBlock: (url: string, height: number) => Promise<{
+    header: BlockHeader;
+    txHashes: string[];
+}>;
+/**
+ * Get transactions with decoded JSON for output scanning.
+ */
+export interface DecodedTxEntry {
+    tx_hash: string;
+    as_json: string;
+    block_height: number;
+    block_timestamp: number;
+    in_pool: boolean;
+}
+export declare const getTransactionsDecoded: (url: string, txHashes: string[]) => Promise<DecodedTxEntry[]>;
+/**
+ * Get block headers for a range of heights in a single RPC call.
+ */
+export interface BlockHeaderEntry {
+    height: number;
+    timestamp: number;
+    num_txes: number;
+}
+export declare const getBlockHeadersRange: (url: string, startHeight: number, endHeight: number) => Promise<BlockHeaderEntry[]>;
+/**
+ * Get block tx hashes for a specific height.
+ * Returns just the tx_hashes array (excludes miner tx).
+ */
+export declare const getBlockTxHashes: (url: string, height: number) => Promise<{
+    txHashes: string[];
+    timestamp: number;
+}>;
+/**
+ * Broadcast a raw transaction hex to the network.
+ */
+export declare const sendRawTransaction: (url: string, txHex: string) => Promise<SendRawTxResponse>;
+export {};

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export { Client } from './client';
+export * from './types';
+export * from './const';
+export type { LWSLoginResponse, LWSAddressInfoResponse, LWSAddressTxsResponse, LWSTxInfo, LWSUnspentOutsResponse, LWSUnspentOutput, } from './lws';
+export type { MoneroTransaction, TxInput, TxOutput, ClsagSig, BPPlusProof, RctSignatures, RingMember } from './tx/types';
+export type { SpendableOutput, Destination, BuiltTransaction } from './tx/builder';
+export type { OwnedOutput } from './scanner';
+export { scanBlocks, computeBalance, getUnspentOutputs } from './scanner';