checksumBehavior: update

nodeLinker: node-modules

npmScopes:
  coinweb:
    npmRegistryServer: "https://npm.coinweb.io/"

yarn add @coinweb/wallet-lib bip39 hdkey secp256k1

import {
    create_wallet as createWallet,
    from_hex_string as fromHexString,
    compose_ui_commands as composeUiCommand,
    create_tx_monitor as createTxMonitor,
    add_txs as addTxs,
    sign,
    NetworkName,
    embed,
    L2TransactionDataInput,
    UiCommand,
    TransactionMonitor,
    type Transaction,
} from '@coinweb/wallet-lib';
import { mnemonicToSeedSync } from 'bip39';
import HDKey from 'hdkey';
import secp256k1 from 'secp256k1';

/**
 * CoinWeb Wallet class
 * Manages wallet instance, transaction monitor, and UI command execution
 */
export class CoinWebWallet {
    public readonly wallet: Awaited<ReturnType<typeof createWallet>>;
    public readonly txMonitor: TransactionMonitor;
    public readonly pubKey: string;

    private constructor(
        wallet: Awaited<ReturnType<typeof createWallet>>,
        txMonitor: TransactionMonitor
    ) {
        this.wallet = wallet;
        this.txMonitor = txMonitor;
        this.pubKey = wallet.pub_key;
    }

    /**
     * Creates a CoinWeb wallet instance from a mnemonic phrase
     * Factory method to create and initialize a wallet with transaction monitor
     * 
     * @param params - Wallet configuration parameters
     * @returns CoinWebWallet instance ready for L2 operations
     */
    static async create(params: {
        mnemonic: string;
        backendUrl: string;
        shard: NetworkName;
    }): Promise<CoinWebWallet> {
        // Generate HD key from mnemonic
        const hdkey = CoinWebWallet.mnemonicToHDKey(params.mnemonic);

        // Create wallet with backend connection and signing configuration
        const wallet = await createWallet({
            address: params.backendUrl, // HTTP endpoint for wallet operations
            ws_address: `${params.backendUrl.replace(/^https:/, 'wss:')}`, // WebSocket endpoint (convert https to wss)
            pub_key: hdkey.publicKey?.toString('hex') ?? '', // Public key in hex format
            shard: params.shard, // Network shard
            max_retry_time_secs: null, // No retry timeout limit
            enable_retries: null, // Retry behavior (null = default)
            // Callback function for signing messages - converts private key and signs
            sign_callback: (msg) => {
                return sign(fromHexString(hdkey.privateKey?.toString('hex') ?? ''), msg);
            },
            broadcaster_wallet_address: null, // No custom broadcaster address
        });

        // Create transaction monitor
        const pendingTxs: Transaction[] = [];
        const utxos = new Map<string, unknown[]>();
        const txMonitor = createTxMonitor(pendingTxs, utxos);

        return new CoinWebWallet(wallet, txMonitor);
    }

    /**
     * Converts a mnemonic phrase to an HD (Hierarchical Deterministic) key
     * This function generates a master key from the mnemonic seed and sets up
     * a custom signing function that uses secp256k1 elliptic curve cryptography
     * 
     * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
     * @returns HDKey instance with custom signing capability for CoinWeb wallet
     */
    private static mnemonicToHDKey(mnemonic: string) {
        // Convert mnemonic to seed using BIP39 standard
        const seed = mnemonicToSeedSync(mnemonic);
        // Generate HD key from master seed
        const hdkey = HDKey.fromMasterSeed(seed);

        // Override the sign method to use secp256k1 signing algorithm
        // This is required for CoinWeb wallet signature format
        hdkey.sign = function (hash: Buffer<ArrayBufferLike>) {
            // Sign the hash with the private key using secp256k1 ECDSA
            const sig = secp256k1.ecdsaSign(Uint8Array.from(hash), Uint8Array.from(hdkey.privateKey ?? []));

            // Normalize the signature to ensure consistent format
            const array = secp256k1.signatureNormalize(sig.signature);

            // Export signature as Buffer for CoinWeb wallet library
            return Buffer.from(secp256k1.signatureExport(array));
        };

        return hdkey;
    }

    /**
     * Executes a UI command by composing it into an L2 transaction and embedding it
     * This is a convenience method that combines compose and embed operations
     * 
     * @param jsonTokenCommand - UI command in JSON format (deposit, orders, etc.)
     * @param networkWrite - Optional network name for write operations (null = default)
     * @returns Transaction UUID (hash) for tracking the transaction
     */
    async executeUiCommand(
        jsonTokenCommand: UiCommand,
        networkWrite: NetworkName | null = null
    ): Promise<string> {
        if (!jsonTokenCommand) throw new Error('UI command not found');

        // Compose the UI command into an L2 transaction structure
        const l2TransactionData = await composeUiCommand(this.wallet, [jsonTokenCommand], networkWrite);
        
        // Add the transaction to the monitor for tracking and state management
        await addTxs(this.txMonitor, l2TransactionData?.l2_transaction);

        // Submit transaction to L2 network and get transaction UUID
        const uuid = await embed(this.wallet, l2TransactionData.l2_transaction);

        return uuid;
    }

    /**
     * Composes and adds a token command to the transaction monitor
     * This function takes a UI command (like deposit or create orders), composes it into
     * an L2 transaction, and adds it to the transaction monitor for tracking
     * 
     * @param jsonTokenCommand - UI command in JSON format (deposit, orders, etc.)
     * @param networkWrite - Optional network name for write operations (null = default)
     * @returns Object containing L2 transaction data and newly added transactions
     */
    async composeTokenCommand(
        jsonTokenCommand: UiCommand,
        networkWrite: NetworkName | null = null
    ) {
        if (!jsonTokenCommand) throw new Error('UI command not found');

        // Compose the UI command into an L2 transaction structure
        const l2TransactionData = await composeUiCommand(this.wallet, [jsonTokenCommand], networkWrite);
        // Add the transaction to the monitor for tracking and state management
        const newTxs = await addTxs(this.txMonitor, l2TransactionData?.l2_transaction);

        return { l2TransactionData, newTxs };
    }

    /**
     * Embeds an L2 transaction into the blockchain
     * This submits the transaction to the CoinWeb L2 network and returns a transaction UUID
     * 
     * @param l2Transaction - L2 transaction data to embed
     * @returns Transaction UUID (hash) for tracking the transaction
     */
    async embedTransaction(l2Transaction: L2TransactionDataInput): Promise<string> {
        if (!l2Transaction) throw new Error('L2 transaction not found');

        // Submit transaction to L2 network and get transaction UUID
        const uuid = await embed(this.wallet, l2Transaction);

        return uuid;
    }
}

    // Step 1: Import dependencies
    import { CoinWebWallet } from "./coinweb-wallet.ts"
    import { NetworkName } from '@coinweb/claims-client';

    // Step 2: Create wallet from mnemonic
    const coinWebWallet = await CoinWebWallet.create({
        mnemonic: 'Coinweb Wallet mnemonic',
        backendUrl: 'https://api-cloud.coinweb.io/wallet', // Coinweb Backend wallet url'
        shard: NetworkName.BNB // Shard to operate on Coinweb Chain
    });
    console.log('✅ Wallet created');
    console.log('   Public Key:', coinWebWallet.pubKey);

    // Step 3: Call Pactswap REST API to build the UI Command for the "/c2/makeDeposit"
    const depositAmount = 100 * 10 ** 18; // 100 CWEB

    const data = await axios.post<{ rawTx: string }>(`https://cwap-api.coinhq.store/pactswap_cm/ui-commands/c2/makeDeposit`, {
            contractId: 'C2 contract id',
            depositAmount: depositAmount,
    });

    // The UI Command
    const rawTx = data.data.rawTx; 
    console.log('   📝 Composed deposit collateral command');

    // Step 4: Propagate(Compose/Sign/Broadcast) the UI Command via the Coinweb wallet library
    const hashTxDeposit = await this.coinWebWallet.executeUiCommand(JSON.parse(rawTx));
    console.log('   ✅ Deposit transaction hash:', hashTxDeposit);