@defdone/annon 0.0.0-stage → 0.1.0-alpha.1

package/dist/node/wallets.js

@@ -0,0 +1,146 @@
+import { readFile } from 'node:fs/promises';
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { base64 } from '@scure/base';
+import { Account, KeyPair } from 'near-api-js';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { signNearUpload } from '../browser/wallets.js';
+import { nep413Hash } from '../near/nep413.js';
+import { bytes, hex } from '../settle-near/codec.js';
+import { identityJson, parseIdentity } from '../settle-near/identity.js';
+import { nearKeyPairWallet } from '../wallet/wallet.js';
+import { AdapterError } from './errors.js';
+import { decodeKeychain, osKeychain } from './keychain.js';
+const credentialsError = () => new AdapterError('credentials_required', 'Select a wallet and provide its key through the documented environment variable or a named key file. Check the recovery identity matches.', 2);
+export function identity(value) {
+    const at = value.indexOf(':');
+    return parseIdentity({ kind: value.slice(0, at), id: value.slice(at + 1) });
+}
+async function source(file, env) {
+    if (file)
+        return (await readFile(file, 'utf8')).trim();
+    if (env)
+        return env.trim();
+    throw credentialsError();
+}
+export async function readBackupSecret(o, env) {
+    try {
+        const text = await source(o.backupSecretFile ?? env.ANNON_BACKUP_SECRET_FILE, env.ANNON_BACKUP_SECRET);
+        return bytes(text.startsWith('0x') ? text : `0x${text}`, 32);
+    }
+    catch {
+        throw new AdapterError('backup_secret_required', 'Provide a 32-byte random backup secret as 64 hex characters in ANNON_BACKUP_SECRET or a named backup secret file.', 2);
+    }
+}
+export async function loadWallet(o, env, nearRpc, keychain = osKeychain) {
+    try {
+        const selected = o.wallet ?? (o.recovery ? identity(o.recovery).kind : env.ANNON_WALLET);
+        let wallet;
+        if (selected === 'evm') {
+            const key = await source(o.evmKeyFile ?? env.ANNON_EVM_KEY_FILE, env.ANNON_EVM_PRIVATE_KEY);
+            if (!/^0x[0-9a-fA-F]{64}$/.test(key))
+                throw credentialsError();
+            const account = privateKeyToAccount(key);
+            const evm = {
+                identity: parseIdentity({ kind: 'evm', id: account.address.toLowerCase() }),
+                address: account.address.toLowerCase(),
+                authorize: async (text) => ({
+                    kind: 'evm',
+                    sig: await account.signMessage({ message: text }),
+                }),
+                signTypedData: (data) => account.signTypedData(data),
+                async sendBase(call, rpc) {
+                    const client = createWalletClient({
+                        account,
+                        chain: base,
+                        transport: http(rpc, { fetchOptions: { credentials: 'omit', redirect: 'error' } }),
+                    });
+                    const publicClient = createPublicClient({
+                        chain: base,
+                        transport: http(rpc, { fetchOptions: { credentials: 'omit', redirect: 'error' } }),
+                    });
+                    if ((await publicClient.getChainId()) !== base.id)
+                        throw new Error('wrong Base chain');
+                    const hash = await client.sendTransaction({
+                        to: call.to,
+                        data: call.data,
+                    });
+                    if ((await publicClient.waitForTransactionReceipt({ hash })).status !== 'success')
+                        throw new Error('split creation failed');
+                },
+            };
+            wallet = evm;
+        }
+        else if (selected === 'solana') {
+            const value = JSON.parse(await source(o.solanaKeyFile ?? env.ANNON_SOLANA_KEY_FILE, env.ANNON_SOLANA_KEYPAIR));
+            if (!Array.isArray(value) ||
+                value.length !== 64 ||
+                value.some((v) => !Number.isInteger(v) || v < 0 || v > 255))
+                throw credentialsError();
+            const key = Uint8Array.from(value);
+            const seed = key.subarray(0, 32);
+            const publicKey = ed25519.getPublicKey(seed);
+            if (hex(publicKey) !== hex(key.subarray(32)))
+                throw credentialsError();
+            wallet = {
+                identity: parseIdentity({ kind: 'solana', id: hex(publicKey).slice(2) }),
+                authorize: async (text) => ({
+                    kind: 'solana',
+                    sig: hex(ed25519.sign(new TextEncoder().encode(text), seed)),
+                }),
+            };
+        }
+        else if (selected === 'near') {
+            const file = o.nearKeyFile ?? env.ANNON_NEAR_KEY_FILE;
+            let raw;
+            if (file || env.ANNON_NEAR_CREDENTIALS)
+                raw = await source(file, env.ANNON_NEAR_CREDENTIALS);
+            else {
+                const account = o.nearAccount ?? env.ANNON_NEAR_ACCOUNT;
+                const publicKey = o.nearPublicKey ?? env.ANNON_NEAR_PUBLIC_KEY;
+                const network = (o.network ?? env.ANNON_NETWORK ?? 'near:mainnet').replace(/^near:/, '');
+                if (!account ||
+                    !publicKey ||
+                    !/^ed25519:[1-9A-HJ-NP-Za-km-z]+$/.test(publicKey) ||
+                    !['mainnet', 'testnet'].includes(network))
+                    throw credentialsError();
+                parseIdentity({ kind: 'near', id: account });
+                raw = decodeKeychain(await keychain.read(`near-${network}-${account}/${account}:${publicKey}`));
+            }
+            const c = JSON.parse(raw);
+            const accountId = c.account_id ?? o.nearAccount ?? env.ANNON_NEAR_ACCOUNT;
+            if (!accountId || !c.private_key?.startsWith('ed25519:'))
+                throw credentialsError();
+            parseIdentity({ kind: 'near', id: accountId });
+            const key = KeyPair.fromString(c.private_key);
+            const expected = o.nearPublicKey ?? env.ANNON_NEAR_PUBLIC_KEY ?? c.public_key;
+            if (expected && key.getPublicKey().toString() !== expected)
+                throw credentialsError();
+            if ((o.nearAccount ?? env.ANNON_NEAR_ACCOUNT ?? accountId) !== accountId)
+                throw credentialsError();
+            // Transport exception near_api_local_wallet: Account owns nonce lookup and broadcast.
+            // Its provider uses the third-party Node fetch transport.
+            const account = new Account(accountId, nearRpc, key.toString());
+            wallet = {
+                ...nearKeyPairWallet(account),
+                signUpload: (intent) => signNearUpload({
+                    getAccounts: async () => [{ accountId }],
+                    signMessage: async (payload) => ({
+                        accountId,
+                        publicKey: key.getPublicKey().toString(),
+                        signature: base64.encode(key.sign(nep413Hash(payload)).signature),
+                    }),
+                }, intent, nearRpc),
+            };
+        }
+        else
+            throw credentialsError();
+        if (o.recovery && identityJson(identity(o.recovery)) !== identityJson(wallet.identity))
+            throw credentialsError();
+        return wallet;
+    }
+    catch {
+        throw credentialsError();
+    }
+}

package/dist/oneclick/oneclick.d.ts

@@ -0,0 +1,132 @@
+import { AnnonError } from '../errors.js';
+export interface Origin {
+    asset: string;
+    chain: 'evm' | 'solana' | 'near' | 'other';
+    refundTo: string;
+    refundType?: 'ORIGIN_CHAIN' | 'INTENTS';
+    blockchain?: string;
+    depositMode?: 'SIMPLE' | 'MEMO';
+}
+export interface Token {
+    assetId: string;
+    blockchain: string;
+    symbol: string;
+    decimals: number;
+    [key: string]: unknown;
+}
+export declare function originFamily(blockchain: string): Origin['chain'];
+/** Exact catalog selection. Unsupported and slow chains are deliberately unavailable. */
+export declare function originFromToken(tokens: readonly Token[], asset: string, blockchain: string, refundTo: string): Origin;
+export declare function validateRefundAddress(chain: Origin['chain'], value: string): void;
+/** Catalog origins bind an exact blockchain; other families use explicit refund syntax. */
+export declare function validateOrigin(origin: Origin): void;
+export interface QuotePreview {
+    request: QuoteRequest;
+    amountIn: string;
+    amountOut: string;
+    timeEstimate: number;
+}
+export interface PollCheckpoint {
+    address: string;
+    memo?: string;
+    attempts: number;
+    errors: number;
+    lastStatus?: SwapStatus;
+    nextPollAt?: number;
+}
+export interface PollOptions {
+    memo?: string;
+    signal?: AbortSignal;
+    maxPolls?: number;
+    intervalMs?: number;
+    checkpoint?: PollCheckpoint;
+    /** Awaited so a durable checkpoint can be saved before polling again. */
+    onProgress?: (checkpoint: PollCheckpoint) => void | Promise<void>;
+}
+export interface QuoteRequest {
+    dry: boolean;
+    swapType: 'EXACT_OUTPUT';
+    slippageTolerance: number;
+    originAsset: string;
+    depositType: 'ORIGIN_CHAIN';
+    depositMode?: 'SIMPLE' | 'MEMO';
+    destinationAsset: string;
+    amount: string;
+    refundTo: string;
+    refundType: 'ORIGIN_CHAIN' | 'INTENTS';
+    recipient: string;
+    recipientType: 'DESTINATION_CHAIN';
+    deadline: string;
+    customRecipientMsg: string;
+}
+export interface Deposit {
+    address: string;
+    amount: string;
+    asset: string;
+    chain: Origin['chain'];
+    /** Exact catalog blockchain, when supplied by a catalog-selected origin. */
+    blockchain?: string;
+    memo?: string;
+    qrData: string;
+    /** Deposit must be confirmed by this earlier cutoff; delivery has a ten-minute buffer. */
+    depositBefore: string;
+    purchaseExpiresAt: string;
+}
+export interface OneClickQuote {
+    request: QuoteRequest;
+    response: Record<string, unknown>;
+    deposit: Deposit;
+}
+declare const states: readonly ["PENDING_DEPOSIT", "KNOWN_DEPOSIT_TX", "PROCESSING", "SUCCESS", "REFUNDED", "FAILED", "INCOMPLETE_DEPOSIT"];
+export interface SwapStatus {
+    status: (typeof states)[number];
+    [key: string]: unknown;
+}
+export interface OneClickOptions {
+    endpoint?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare class OneClickQuoteExpired extends AnnonError {
+    readonly code = "quote_expired";
+    constructor();
+}
+/** Only recognized public service messages may cross the CLI/MCP boundary. */
+export declare class OneClickRefused extends AnnonError {
+    readonly code = "quote_refused";
+    readonly minimumAmountUsdc?: string;
+    constructor(message: string);
+}
+export declare class OneClick {
+    private readonly options;
+    constructor(options?: OneClickOptions);
+    private request;
+    private now;
+    tokens(signal?: AbortSignal): Promise<Token[]>;
+    preview(message: string, origin: Origin, options?: {
+        slippageTolerance?: number;
+        signal?: AbortSignal;
+    }): Promise<QuotePreview>;
+    quote(message: string, origin: Origin, options: {
+        dry: true;
+        slippageTolerance?: number;
+        signal?: AbortSignal;
+    }): Promise<QuotePreview>;
+    quote(message: string, origin: Origin, options?: {
+        dry?: false;
+        slippageTolerance?: number;
+        signal?: AbortSignal;
+    }): Promise<OneClickQuote>;
+    quote(message: string, origin: Origin, options: {
+        dry?: boolean;
+        slippageTolerance?: number;
+        signal?: AbortSignal;
+    }): Promise<OneClickQuote | QuotePreview>;
+    status(depositAddress: string, options?: {
+        memo?: string;
+        signal?: AbortSignal;
+    }): Promise<SwapStatus>;
+    poll(address: string, options?: PollOptions): Promise<SwapStatus>;
+}
+export {};

package/dist/oneclick/oneclick.js

@@ -0,0 +1,342 @@
+/** Native NEAR USDC delivery through 1Click. SUCCESS is delivery, not purchase acceptance. */
+import { base58 } from '@scure/base';
+import { isAddress } from 'viem/utils';
+import { AnnonError, isTransient } from '../errors.js';
+import { parseRetryAfterMs, sleep } from '../net/retry.js';
+import { account, uint, usdc } from '../settle-near/codec.js';
+import { parsePurchaseMessage } from '../settle-near/purchase.js';
+import { NEAR_USDC } from '../settle-near/terms.js';
+const evmChains = [
+    'eth',
+    'base',
+    'arb',
+    'arbitrum',
+    'op',
+    'optimism',
+    'polygon',
+    'pol',
+    'bera',
+    'scroll',
+    'monad',
+    'xlayer',
+    'abs',
+    'plasma',
+    'bsc',
+    'avax',
+    'avalanche',
+    'gnosis',
+];
+export function originFamily(blockchain) {
+    if (evmChains.includes(blockchain))
+        return 'evm';
+    if (blockchain === 'sol' || blockchain === 'solana')
+        return 'solana';
+    if (blockchain === 'near')
+        return 'near';
+    return 'other';
+}
+function chainFamily(blockchain) {
+    const family = originFamily(blockchain);
+    if (family === 'other')
+        throw new TypeError('unsupported origin chain or purchase window');
+    return family;
+}
+/** Exact catalog selection. Unsupported and slow chains are deliberately unavailable. */
+export function originFromToken(tokens, asset, blockchain, refundTo) {
+    if (tokens.filter((t) => t.assetId === asset && t.blockchain === blockchain).length !== 1)
+        throw new TypeError('select an exact catalog asset and blockchain');
+    const chain = chainFamily(blockchain);
+    validateRefundAddress(chain, refundTo);
+    return { asset, blockchain, chain, refundTo, refundType: 'ORIGIN_CHAIN' };
+}
+export function validateRefundAddress(chain, value) {
+    if (typeof value !== 'string' || !value || /\s/.test(value))
+        throw new TypeError('invalid refund address');
+    if (chain === 'evm') {
+        if (!isAddress(value) || /^0x0{40}$/i.test(value))
+            throw new TypeError('invalid EVM refund address');
+    }
+    else if (chain === 'solana') {
+        if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value) || base58.decode(value).length !== 32)
+            throw new TypeError('invalid Solana refund address');
+    }
+    else if (chain === 'near')
+        account(value);
+    else if (chain !== 'other')
+        throw new TypeError('unsupported refund chain family');
+}
+/** Catalog origins bind an exact blockchain; other families use explicit refund syntax. */
+export function validateOrigin(origin) {
+    if (!origin ||
+        typeof origin.asset !== 'string' ||
+        !origin.asset.startsWith('nep141:') ||
+        !origin.asset.slice(7) ||
+        /\s/.test(origin.asset))
+        throw new TypeError('invalid origin asset');
+    if (origin.blockchain && chainFamily(origin.blockchain) !== origin.chain)
+        throw new TypeError('origin chain family mismatch');
+    if (origin.depositMode !== undefined && !['SIMPLE', 'MEMO'].includes(origin.depositMode))
+        throw new TypeError('invalid deposit mode');
+    if (origin.refundType !== undefined && !['ORIGIN_CHAIN', 'INTENTS'].includes(origin.refundType))
+        throw new TypeError('invalid refund type');
+    validateRefundAddress(origin.chain, origin.refundTo);
+    if (origin.refundType === 'INTENTS')
+        account(origin.refundTo);
+}
+class TransportError extends AnnonError {
+    retryAfterMs;
+    constructor(retryAfterMs = 0) {
+        super('transport', '1Click transport unavailable');
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'TransportError';
+    }
+}
+const states = [
+    'PENDING_DEPOSIT',
+    'KNOWN_DEPOSIT_TX',
+    'PROCESSING',
+    'SUCCESS',
+    'REFUNDED',
+    'FAILED',
+    'INCOMPLETE_DEPOSIT',
+];
+export class OneClickQuoteExpired extends AnnonError {
+    code = 'quote_expired';
+    constructor() {
+        super('quote_expired', 'The 1Click quote expired. Run buy again.');
+        this.name = 'OneClickQuoteExpired';
+    }
+}
+/** Only recognized public service messages may cross the CLI/MCP boundary. */
+export class OneClickRefused extends AnnonError {
+    code = 'quote_refused';
+    minimumAmountUsdc;
+    constructor(message) {
+        super('quote_refused', message);
+        this.name = 'OneClickRefused';
+        const minimum = /^Amount is too low for bridge, try at least ([0-9]{1,39})[.]?$/i.exec(message);
+        if (minimum?.[1])
+            this.minimumAmountUsdc = usdc(minimum[1]);
+    }
+}
+function refusalMessage(value) {
+    // Do not expose arbitrary upstream text: it can echo requests, credentials or signed payloads.
+    return (typeof value === 'string' &&
+        (/^Amount is too low for bridge, try at least [0-9]{1,39}[.]?$/i.test(value) ||
+            /^(No routes found|No liquidity available|Amount is too low|Amount is too high|Unsupported (origin|destination) asset)[.]?$/i.test(value)));
+}
+/** A dry response has no deposit destination or inactivity deadline. */
+function parseQuotePreview(request, response) {
+    const q = response.quote;
+    if (!q ||
+        q.amountOut !== request.amount ||
+        (q.minAmountOut !== undefined && uint(q.minAmountOut, 128) < BigInt(request.amount)))
+        throw new Error('1Click quote has wrong output');
+    const echo = response.quoteRequest;
+    if (!echo || Object.entries(request).some(([key, value]) => echo[key] !== value))
+        throw new Error('1Click quoteRequest echo mismatch');
+    if (typeof q.timeEstimate !== 'number' ||
+        !Number.isFinite(q.timeEstimate) ||
+        q.timeEstimate < 0 ||
+        q.timeEstimate > 600)
+        throw new Error('1Click delivery estimate exceeds purchase delivery window');
+    if (typeof q.amountIn !== 'string' || uint(q.amountIn, 128) === 0n)
+        throw new Error('invalid quote input amount');
+    return {
+        request,
+        amountIn: q.amountIn,
+        amountOut: request.amount,
+        timeEstimate: q.timeEstimate,
+    };
+}
+export class OneClick {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async request(path, body, signal) {
+        signal?.throwIfAborted();
+        let response;
+        try {
+            response = await (this.options.fetch ?? fetch)(`${this.options.endpoint ?? 'https://1click.chaindefuser.com/v0'}${path}`, {
+                credentials: 'omit',
+                method: body === undefined ? 'GET' : 'POST',
+                ...(body === undefined
+                    ? {}
+                    : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }),
+                signal: signal
+                    ? AbortSignal.any([signal, AbortSignal.timeout(20000)])
+                    : AbortSignal.timeout(20000),
+            });
+        }
+        catch {
+            signal?.throwIfAborted();
+            throw new TransportError();
+        }
+        if (response.status === 429 || response.status >= 500) {
+            const delay = parseRetryAfterMs(response.headers.get('retry-after'), this.now() * 1000) ?? 0;
+            throw new TransportError(Math.max(0, Math.min(300000, delay || 0)));
+        }
+        if (!response.ok) {
+            if (path === '/quote' && response.status >= 400 && response.status < 500) {
+                const body = await response.json().catch(() => null);
+                const message = body?.message;
+                throw new OneClickRefused(refusalMessage(message) ? message : 'The 1Click quote was refused.');
+            }
+            throw new Error(`1Click HTTP ${response.status}`);
+        }
+        const result = await response.json();
+        if (!result || typeof result !== 'object' || (Array.isArray(result) && path !== '/tokens'))
+            throw new Error('malformed 1Click response');
+        return result;
+    }
+    now() {
+        return (this.options.now ?? (() => Math.floor(Date.now() / 1000)))();
+    }
+    async tokens(signal) {
+        const result = await this.request('/tokens', undefined, signal);
+        if (!Array.isArray(result))
+            throw new Error('malformed token catalog');
+        return result.filter((t) => !!t &&
+            typeof t === 'object' &&
+            typeof t.assetId === 'string' &&
+            t.assetId.startsWith('nep141:') &&
+            !!t.assetId.slice(7) &&
+            typeof t.blockchain === 'string' &&
+            !!t.blockchain &&
+            typeof t.symbol === 'string' &&
+            Number.isInteger(t.decimals) &&
+            t.decimals >= 0 &&
+            t.decimals <= 255);
+    }
+    async preview(message, origin, options = {}) {
+        return this.quote(message, origin, { ...options, dry: true });
+    }
+    async quote(message, origin, options = {}) {
+        const p = parsePurchaseMessage(message);
+        if (p.route !== 'near-usdc' || p.asset !== NEAR_USDC)
+            throw new TypeError('1Click requires the NEAR USDC route');
+        const now = (this.options.now ?? (() => Math.floor(Date.now() / 1000)))();
+        const depositCutoff = Number(p.expires_at) - 600;
+        if (!Number.isSafeInteger(depositCutoff) || depositCutoff <= now)
+            throw new Error('purchase expired or insufficient delivery window');
+        validateOrigin(origin);
+        const refundType = origin.refundType ?? 'ORIGIN_CHAIN';
+        if (refundType === 'INTENTS')
+            account(origin.refundTo);
+        const tolerance = options.slippageTolerance ?? 100;
+        if (!Number.isInteger(tolerance) || tolerance < 0 || tolerance > 10000)
+            throw new TypeError('invalid slippage');
+        const request = {
+            dry: options.dry ?? false,
+            swapType: 'EXACT_OUTPUT',
+            slippageTolerance: tolerance,
+            originAsset: origin.asset,
+            depositType: 'ORIGIN_CHAIN',
+            ...(origin.depositMode ? { depositMode: origin.depositMode } : {}),
+            destinationAsset: `nep141:${NEAR_USDC}`,
+            amount: p.price,
+            refundTo: origin.refundTo,
+            refundType,
+            recipient: p.contract,
+            recipientType: 'DESTINATION_CHAIN',
+            deadline: new Date(depositCutoff * 1000).toISOString(),
+            customRecipientMsg: message,
+        };
+        const response = (await this.request('/quote', request, options.signal));
+        const preview = parseQuotePreview(request, response);
+        if (request.dry)
+            return preview;
+        const q = response.quote;
+        const deadline = typeof q.deadline === 'string' ? Date.parse(q.deadline) : NaN;
+        // The service's address-inactivity deadline is request.deadline + 72h in recorded
+        // quotes. It is not the buyer's cutoff. Never extend the echoed request deadline.
+        if (!Number.isFinite(deadline) || deadline < depositCutoff * 1000)
+            throw new Error('1Click deposit address deadline expires before the deposit cutoff');
+        if (typeof q.depositAddress !== 'string' || !q.depositAddress || q.depositAddress.length > 256)
+            throw new Error('quote has no deposit address');
+        const memo = q.depositMemo;
+        if ((origin.depositMode === 'MEMO' && (typeof memo !== 'string' || !memo)) ||
+            (memo !== undefined &&
+                (typeof memo !== 'string' ||
+                    memo.length > 256 ||
+                    Array.from(memo).some((c) => c.charCodeAt(0) < 32))))
+            throw new Error('invalid deposit memo');
+        const data = {
+            address: q.depositAddress,
+            amount: preview.amountIn,
+            asset: origin.asset,
+            chain: origin.chain,
+            ...(origin.blockchain ? { blockchain: origin.blockchain } : {}),
+            depositBefore: request.deadline,
+            purchaseExpiresAt: new Date(Number(p.expires_at) * 1000).toISOString(),
+            ...(memo === undefined ? {} : { memo }),
+        };
+        return { request, response, deposit: { ...data, qrData: JSON.stringify(data) } };
+    }
+    async status(depositAddress, options = {}) {
+        if (!depositAddress || depositAddress.length > 256)
+            throw new TypeError('invalid deposit address');
+        const result = (await this.request(`/status?depositAddress=${encodeURIComponent(depositAddress)}${options.memo === undefined ? '' : `&depositMemo=${encodeURIComponent(options.memo)}`}`, undefined, options.signal));
+        if (!states.includes(result.status))
+            throw new Error('unknown 1Click status');
+        return result;
+    }
+    async poll(address, options = {}) {
+        const max = options.maxPolls ?? 1200;
+        if (!Number.isInteger(max) || max < 1)
+            throw new TypeError('invalid poll count');
+        const ms = options.intervalMs ?? 3000;
+        if (!Number.isFinite(ms) || ms < 0 || ms > 30000)
+            throw new TypeError('invalid poll interval');
+        let checkpoint = options.checkpoint ?? {
+            address,
+            ...(options.memo === undefined ? {} : { memo: options.memo }),
+            attempts: 0,
+            errors: 0,
+        };
+        if (checkpoint.address !== address ||
+            checkpoint.memo !== options.memo ||
+            !Number.isSafeInteger(checkpoint.attempts) ||
+            checkpoint.attempts < 0 ||
+            !Number.isSafeInteger(checkpoint.errors) ||
+            checkpoint.errors < 0 ||
+            (checkpoint.nextPollAt !== undefined &&
+                (!Number.isFinite(checkpoint.nextPollAt) || checkpoint.nextPollAt < 0)))
+            throw new TypeError('invalid poll checkpoint');
+        options.signal?.throwIfAborted();
+        if (checkpoint.lastStatus &&
+            ['SUCCESS', 'REFUNDED', 'FAILED'].includes(checkpoint.lastStatus.status)) {
+            await options.onProgress?.(structuredClone(checkpoint));
+            return checkpoint.lastStatus;
+        }
+        if (checkpoint.nextPollAt && checkpoint.nextPollAt > this.now() * 1000)
+            await (this.options.wait ?? sleep)(Math.min(300000, checkpoint.nextPollAt - this.now() * 1000), options.signal);
+        for (let i = 0; i < max; i++) {
+            options.signal?.throwIfAborted();
+            let result;
+            let delay = ms;
+            try {
+                result = await this.status(address, options);
+            }
+            catch (error) {
+                if (!isTransient(error))
+                    throw error;
+                delay = Math.max(Math.min(30000, ms * 2 ** Math.min(checkpoint.errors, 8)), error instanceof TransportError ? error.retryAfterMs : 0);
+            }
+            checkpoint = {
+                ...checkpoint,
+                attempts: checkpoint.attempts + 1,
+                errors: result ? 0 : checkpoint.errors + 1,
+                ...(result ? { lastStatus: result } : {}),
+                nextPollAt: this.now() * 1000 + delay,
+            };
+            await options.onProgress?.(structuredClone(checkpoint));
+            if (result && ['SUCCESS', 'REFUNDED', 'FAILED'].includes(result.status))
+                return result;
+            if (i + 1 < max)
+                await (this.options.wait ?? sleep)(delay, options.signal);
+        }
+        throw new AnnonError('settlement_pending', '1Click status still pending');
+    }
+}