@taceo/merces-oft-client

Client SDK for the TACEO Merces confidential OFT protocol. Client wraps the on-chain Merces contract calls (deposit/withdraw/transfer/send/redeem/challenge) together with witness/proof generation, and drives a viem PublicClient/WalletClient to submit transactions.

Installation

npm add @taceo/merces-oft-client
# or: pnpm add @taceo/merces-oft-client

Quick Start

import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { Client } from "@taceo/merces-oft-client";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const publicClient = createPublicClient({ transport: http(process.env.RPC_URL) });
const walletClient = createWalletClient({ account, transport: http(process.env.RPC_URL) });

const client = await Client.create({
  contractAddress: "0x...",
  contractKind: "adapter", // or "oft"
  idRegistryAddress: "0x...",
  gatewayUrl: process.env.GATEWAY_URL, // required for deposit/withdraw/transfer/send
  token: "0x...", // omit to use the native token
  walletClient,
  publicClient,
});

await client.deposit(1_000_000n);
console.log(await client.balance());

Client.create registers the wallet with the ID registry on first use, prompting for signatures the first time it's called for a given wallet in a session.

ClientConfig

| Field | Description | | ------------------- | ------------------------------------------------------------------------ | | contractAddress | Address of the deployed Merces contract. | | contractKind | "adapter" or "oft" — selects the ABI to use. | | idRegistryAddress | Address of the chain's IdRegistry contract. | | gatewayUrl | Base URL of the gateway relay. Optional, but required by deposit/withdraw/transfer/send (not every chain has one, e.g. an OFT chain with no ERC20 token has no gasless deposit equivalent). | | token | ERC20 token address; omit to use the native token. | | walletClient | viem WalletClient (must have an account configured). | | publicClient | viem PublicClient. | | txReceiptTimeout | Timeout in ms to wait for a transaction receipt (default: 30_000). | | mpcEventTimeout | Timeout in ms to wait for the ProcessedMPC on-chain event, or for the action queue to drain (default: 330_000). |

Client methods

• address() — this signer's wallet address.
• registryIndex() — this signer's index in the ID registry.
• deposit(amount, onStep?) — deposits amount into this signer's own already-registered account. Returns { queuedTxHash, completedTxHash }.
• withdraw(amount, onStep?) — withdraws amount from this signer's own already-registered account, to client.address(). Returns { queuedTxHash, completedTxHash }.
• transfer(receiver, amount, onStep?) — transfers amount from this signer's own account to receiver's, on the same chain. Returns { queuedTxHash, completedTxHash }.
• send(dstChainId, dstIdRegistryAddress, dstPublicClient, receiver, amount, onStep?) — sends amount from this signer's own account to receiver's account on a different chain, identified by that chain's IdRegistry address and a PublicClient connected to it. Returns { queuedTxHash, completedTxHash }.
• balance() — scans on-chain notes (newest first) for the latest one addressed to this signer and returns its decrypted balance; returns zero if this signer has no note yet, or if it's already been redeemed.
• myCurrentNote() — this signer's current on-chain note (the one balance()/redeemNote() act on), including whether it's already been redeemed; null if this signer has no note yet. Unlike balance(), doesn't wait for the action queue to drain.
• redeemNote(noteIndex) — redeems this signer's own note at noteIndex via the escape hatch.
• challengeNote(noteIndex) — challenges a note at noteIndex, proving the MPC posted an inconsistent ciphertext; no-op if the local honesty check shows the MPC was actually correct. Returns whether the MPC was found dishonest.
• escapeHatchStatus() — MPC liveness, for gating the redeemNote escape hatch in a UI.

deposit/withdraw/transfer/send accept an optional onStep callback, called with 'proving' | 'submitting' | 'confirming' for UI progress display. deposit on an OFT chain can throw DepositConfirmationTimeoutError if the on-chain burn landed but confirmation timed out — callers must not retry, since the burn already happened.