@dynamic-labs/aleo 4.79.2 → 4.80.0

package/src/utils/AleoUiTransaction/AleoUiTransaction.js

@@ -0,0 +1,350 @@
+'use client'
+import { __awaiter } from '../../../_virtual/_tslib.js';
+import { formatNumberText } from '@dynamic-labs/utils';
+import { recordMatchesSendableToken, extractRecordAtomicAmount, getAleoSendableTokensForNetwork, ALEO_CREDITS_PROGRAM, ALEO_CREDITS_DECIMALS } from '../aleoSendableTokens/aleoSendableTokens.js';
+
+// `10n ** decimals` via string construction. Equivalent to `BigInt(10) **
+// BigInt(decimals)` but avoids the TS2791 error in environments whose
+// `target` predates es2016 (which is where rollup compiles this package).
+const pow10 = (decimals) => BigInt(`1${'0'.repeat(decimals)}`);
+// Aleo addresses are 63-character strings: `aleo1` prefix + 58 lowercase
+// alphanumeric characters. We deliberately don't enforce the bech32m
+// alphabet — Aleo's encoding admits a wider character set than standard
+// bech32m (e.g. `o` appears in real testnet addresses). Format-level
+// validation only — the on-chain transition rejects bad checksums with a
+// clear error, so we don't pull the Provable WASM into the widget bundle
+// for client-side checksum verification.
+const ALEO_ADDRESS_REGEX = /^aleo1[a-z0-9]{58}$/;
+/**
+ * Aleo `IUITransaction` for the widget's Send flow.
+ *
+ * Both supported modes spend FROM a private record (so the wallet's
+ * available balance is always the shielded record sum); they differ
+ * only in what the recipient receives:
+ *
+ *  - **Individual** = `<program>/transfer_private` — recipient also gets
+ *    a private record. The most common Aleo flow.
+ *  - **Exchange**   = `<program>/transfer_private_to_public` —
+ *    recipient's *public* balance is incremented. Useful for off-ramps,
+ *    exchange deposits, etc.
+ *
+ * The submit path branches on the **selected token's program kind**:
+ *
+ *  - `credits`     → `credits.aleo` transitions, 3 inputs `[record, recipient, amount]`.
+ *  - `stablecoin`  → `<stablecoin>.aleo` transitions, 3 inputs
+ *                    `[recipient, amount, record]`. The iframe appends a
+ *                    Sealance freeze-list exclusion proof (and its type)
+ *                    automatically — see `proveTransaction` in the iframe's
+ *                    Aleo client.
+ *  - `arc21`       → `token_registry.aleo` transitions, 3 inputs
+ *                    `[recipient, amount, record]`. The token_id is
+ *                    encoded inside the record's plaintext, so the
+ *                    transition signature does NOT include it as a
+ *                    separate argument — only the record carries it.
+ *
+ * In all kinds, the form auto-picks the smallest single record (filtered
+ * to the selected token) that covers the amount. If no single record
+ * fits, the form surfaces a merge CTA backed by `joinAllRecordsForToken`.
+ */
+class AleoUiTransaction {
+    constructor({ from, networkId, listOwnedRecords, joinAllRecordsForToken, onSubmit, }) {
+        var _a;
+        this.chain = 'ALEO';
+        this.data = undefined;
+        this.fee = { gas: undefined };
+        this.transactionModes = [
+            {
+                icon: 'individual',
+                id: 'individual',
+                label: 'Individual',
+            },
+            {
+                icon: 'exchange',
+                id: 'exchange',
+                label: 'Exchange',
+            },
+        ];
+        // No default — the user must explicitly pick Individual or Exchange
+        // before submitting. Both modes spend from the same shielded balance,
+        // so the rest of the form stays interactive without a selection; we
+        // just gate the Preview/Submit button. Pre-selecting felt
+        // presumptuous given Individual vs. Exchange has real semantic
+        // differences (recipient gets a private record vs. public balance).
+        this.selectedTransactionMode = undefined;
+        this.from = from;
+        this.networkId = networkId;
+        this.listOwnedRecords = listOwnedRecords;
+        this.joinAllRecordsForToken = joinAllRecordsForToken;
+        this.onSubmitFn = onSubmit;
+        this.selectedToken = (_a = this.tokensForNetwork()[0]) !== null && _a !== void 0 ? _a : this.creditsFallback();
+    }
+    setTransactionMode(modeId) {
+        if (modeId !== 'exchange' && modeId !== 'individual')
+            return;
+        this.selectedTransactionMode = modeId;
+    }
+    setSelectedToken(contractAddress) {
+        const match = this.tokensForNetwork().find((t) => t.contractAddress === contractAddress);
+        if (match)
+            this.selectedToken = match;
+    }
+    setPendingAmount(amountInput) {
+        try {
+            this.pendingValue = this.parse(amountInput);
+        }
+        catch (_a) {
+            this.pendingValue = undefined;
+        }
+    }
+    /**
+     * Triggered by the form's "Merge records first" button. After this
+     * resolves the form re-evaluates `getRecordMergeAction`, so we drop the
+     * cached records first to force a fresh `listOwnedRecords` on the
+     * next call (the on-chain merge produced new records).
+     */
+    mergeRecordsForSelectedToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.joinAllRecordsForToken(this.selectedToken);
+            this.cachedRecords = undefined;
+        });
+    }
+    getRecordMergeAction() {
+        // Both modes consume one private record, so the CTA fires for either
+        // selection when the user's largest single record (of the selected
+        // token) can't cover the amount. (Exchange = transfer_private_to_public
+        // also burns a record; the only difference is that the recipient gets
+        // public balance instead of a private record.)
+        if (this.pendingValue === undefined || this.pendingValue <= BigInt(0)) {
+            return undefined;
+        }
+        // We can only know "fits / doesn't fit" if we've loaded records at
+        // least once. The form refreshes the action on amount blur — by then
+        // the iframe has typically been pinged at least once (e.g. when
+        // `getBalance` ran), but we also have to handle the cold case where
+        // records haven't been fetched yet. Returning `undefined` here is
+        // safe: the form will re-check on blur after the user types again,
+        // and `listOwnedRecords` will be invoked from the submit path
+        // anyway. We choose to never block submit on an unknown — the worst
+        // case is the user clicks Preview, sees the underlying error, and
+        // clicks merge from there.
+        if (!this.cachedRecords)
+            return undefined;
+        const matching = this.cachedRecords.filter((r) => recordMatchesSendableToken(r, this.selectedToken));
+        const largest = matching.reduce((acc, r) => {
+            const v = extractRecordAtomicAmount(r, this.selectedToken);
+            return v > acc ? v : acc;
+        }, BigInt(0));
+        if (largest >= this.pendingValue)
+            return undefined;
+        // No single record fits. The CTA mirrors the language we use in the
+        // demo + the merge button we already shipped. Action delegates back
+        // to the connector via the closure injected at construction time.
+        const { symbol } = this.selectedToken;
+        return {
+            actionLabel: 'Merge records first',
+            message: `No single private record covers this amount. Largest is ${this.format(largest)} ${symbol}; you're sending ${this.format(this.pendingValue)} ${symbol}.`,
+            onAction: () => this.mergeRecordsForSelectedToken(),
+        };
+    }
+    /**
+     * Parses a human-readable amount (e.g. `"0.5"`) into atomic units using
+     * the *selected token's* decimals (credits = 6, stablecoin = 6, each
+     * ARC-21 token has its own — wETH = 18, etc.). BigInt math via integer
+     * multiplication keeps precision lossless up to `decimals` places.
+     */
+    parse(input) {
+        const { decimals } = this.selectedToken;
+        const trimmed = input.trim();
+        const re = new RegExp(`^(\\d+)(?:\\.(\\d{1,${decimals}}))?$`);
+        const match = re.exec(trimmed);
+        if (!match) {
+            throw new Error(`Invalid amount — expected up to ${decimals} decimal places.`);
+        }
+        const [, whole, fracRaw] = match;
+        const frac = (fracRaw !== null && fracRaw !== void 0 ? fracRaw : '').padEnd(decimals, '0');
+        return BigInt(whole) * pow10(decimals) + BigInt(frac);
+    }
+    // Formats an atomic-units bigint into a display string using the
+    //  selected token's decimals. BigInt math throughout — Number() coercion
+    //  on the whole atomic value would lose precision for high-decimal tokens
+    //  (e.g. wETH at 18 decimals: 9 wETH ≈ 9·10¹⁸ atomic units, well past
+    //  Number.MAX_SAFE_INTEGER).
+    format(value, { precision } = {}) {
+        const { decimals } = this.selectedToken;
+        if (decimals === 0) {
+            return formatNumberText(value.toString(), { precision });
+        }
+        const negative = value < BigInt(0);
+        const abs = negative ? -value : value;
+        const divisor = pow10(decimals);
+        const wholePart = abs / divisor;
+        const fracPart = abs % divisor;
+        // Linear-time trailing-zero trim. Avoids `/0+$/` — anchored, bounded
+        //  input, but the SAST tooling flags any `+`-quantified regex as
+        //  ReDoS-prone, so we walk back manually.
+        const fracPadded = fracPart.toString().padStart(decimals, '0');
+        let fracEnd = fracPadded.length;
+        while (fracEnd > 0 && fracPadded[fracEnd - 1] === '0')
+            fracEnd -= 1;
+        const fracString = fracPadded.slice(0, fracEnd);
+        const sign = negative ? '-' : '';
+        const decimalString = fracString.length > 0
+            ? `${sign}${wholePart.toString()}.${fracString}`
+            : `${sign}${wholePart.toString()}`;
+        return formatNumberText(decimalString, { precision });
+    }
+    validateAddressFormat(address) {
+        return ALEO_ADDRESS_REGEX.test(address);
+    }
+    /**
+     * Returns the user's *available* balance for the selected token in
+     * atomic units — the sum of unspent matching records. Both Send modes
+     * spend FROM records, so the displayed available balance is the same
+     * regardless of the toggle. Caches the record list so the merge CTA
+     * (and the auto-pick at submit time) can share it.
+     */
+    getBalance() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const records = yield this.refreshRecordsCache();
+            return records
+                .filter((r) => recordMatchesSendableToken(r, this.selectedToken))
+                .reduce((acc, r) => acc + extractRecordAtomicAmount(r, this.selectedToken), BigInt(0));
+        });
+    }
+    /**
+     * Feemaster sponsors `credits.aleo/transfer_public` and `transfer_private`
+     * per ANF's policy, so the user pays zero on credits sends. Stablecoin
+     * + ARC-21 sends today fall through to user-paid (Feemaster policy
+     * doesn't yet cover them on testnet); the iframe still completes the
+     * transfer, just deducts the credits-fee directly. The optimistic `0n`
+     * here matches what we tell the user via `isGasSponsored()` below.
+     */
+    fetchFee() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.fee.gas = BigInt(0);
+        });
+    }
+    isGasSponsored() {
+        return this.selectedToken.programKind === 'credits';
+    }
+    /**
+     * Tells the SendBalanceView to populate the picker / "Available"
+     * display from the wallet's *shielded* balance per token — not from
+     * the redcoast public-balance fetch the form would otherwise use.
+     * Both Send modes (Individual = `transfer_private`, Exchange =
+     * `transfer_private_to_public`) consume a private record, so what
+     * the user can actually send is the records sum.
+     *
+     * Returns one entry per token in the network registry (credits +
+     * stablecoins always; mainnet additionally exposes the 5 ARC-21
+     * hyp_warp tokens). Tokens with zero matching records still appear so
+     * the user can see the full menu — picking a zero-balance token
+     * surfaces the merge / fund flow, not silently hides the option.
+     */
+    getSendableTokenBalances() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const records = yield this.refreshRecordsCache();
+            const tokens = this.tokensForNetwork();
+            return tokens.map((token) => {
+                var _a;
+                const sumAtomic = records
+                    .filter((r) => recordMatchesSendableToken(r, token))
+                    .reduce((acc, r) => acc + extractRecordAtomicAmount(r, token), BigInt(0));
+                const divisor = Number(pow10(token.decimals));
+                const rawBalance = Number(sumAtomic);
+                return {
+                    address: token.contractAddress,
+                    balance: rawBalance / divisor,
+                    decimals: token.decimals,
+                    // Every Aleo Send token uses the same record-spend mechanics and
+                    // the same `transaction.parse` / `getBalance` / `submit` pipeline
+                    // internally (decimals + program both come from `selectedToken`).
+                    // The form's "non-native" branch was designed for EVM-style ERC-20
+                    // tokens that need a separate `parseNonNativeToken` + a separate
+                    // contract balance source — neither of which applies here. Marking
+                    // every entry as native sends the form through `transaction.parse`
+                    // + `transaction.getBalance`, which is exactly what we want for
+                    // credits AND stablecoins AND ARC-21 alike. Not a hack — it's an
+                    // accurate description of the form's contract for this chain.
+                    isNative: true,
+                    logoURI: (_a = token.logoURI) !== null && _a !== void 0 ? _a : '',
+                    name: token.name,
+                    rawBalance,
+                    symbol: token.symbol,
+                };
+            });
+        });
+    }
+    submit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.selectedTransactionMode) {
+                throw new Error('Pick Individual or Exchange before submitting an Aleo transfer.');
+            }
+            if (!this.to) {
+                throw new Error('Recipient address is required');
+            }
+            if (this.value === undefined) {
+                throw new Error('Amount is required');
+            }
+            // Both modes consume one private record. Pick the smallest record of
+            // the SELECTED token that covers `value` for minimal change-record
+            // fragmentation. If none fits we throw — the form should have already
+            // shown the merge CTA, but we keep the safety net so a stale form
+            // state can't slip a doomed transaction past us.
+            const targetValue = this.value;
+            const records = yield this.refreshRecordsCache();
+            const fitting = records
+                .filter((r) => recordMatchesSendableToken(r, this.selectedToken) &&
+                typeof r.record_plaintext === 'string')
+                .map((r) => ({
+                atomic: extractRecordAtomicAmount(r, this.selectedToken),
+                plaintext: r.record_plaintext,
+            }))
+                .filter((r) => r.atomic >= targetValue)
+                .sort((a, b) => {
+                if (a.atomic < b.atomic)
+                    return -1;
+                if (a.atomic > b.atomic)
+                    return 1;
+                return 0;
+            });
+            if (fitting.length === 0) {
+                throw new Error('No single private record covers this amount. Merge records first.');
+            }
+            return this.onSubmitFn({
+                mode: this.selectedTransactionMode,
+                recordPlaintext: fitting[0].plaintext,
+                to: this.to,
+                token: this.selectedToken,
+                value: this.value,
+            });
+        });
+    }
+    refreshRecordsCache() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const records = yield this.listOwnedRecords();
+            this.cachedRecords = records;
+            return records;
+        });
+    }
+    tokensForNetwork() {
+        return getAleoSendableTokensForNetwork(this.networkId);
+    }
+    // Last-resort default when the network registry is empty (shouldn't
+    //  happen in practice — both supported networks include credits).
+    creditsFallback() {
+        return {
+            contractAddress: ALEO_CREDITS_PROGRAM,
+            decimals: ALEO_CREDITS_DECIMALS,
+            logoURI: '',
+            name: 'Aleo Credits',
+            programId: ALEO_CREDITS_PROGRAM,
+            programKind: 'credits',
+            recordName: 'credits',
+            recordTypeLiteral: 'credits.record',
+            symbol: 'ALEO',
+        };
+    }
+}
+
+export { AleoUiTransaction };

package/src/utils/AleoUiTransaction/index.d.ts

@@ -0,0 +1,2 @@
+export { AleoUiTransaction } from './AleoUiTransaction';
+export type { AleoSubmitParams, AleoTransferMode } from './AleoUiTransaction';

package/src/utils/aleoSendableTokens/aleoSendableTokens.cjs

@@ -0,0 +1,185 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Per-network registry of tokens spendable from the wallet's *shielded*
+ * (private record) state via the widget Send view.
+ *
+ * Three program kinds, three submit paths:
+ *
+ *   - `credits`     `credits.aleo/transfer_private`
+ *                   inputs:     [record, recipient, amount]
+ *                   inputTypes: ['credits.record','address.private','u64.private']
+ *
+ *                   `credits.aleo/transfer_private_to_public`
+ *                   inputs:     [record, recipient, amount]
+ *                   inputTypes: ['credits.record','address.public','u64.public']
+ *
+ *   - `stablecoin`  `<stablecoin>/transfer_private`
+ *                   inputs:     [recipient, amount, record]
+ *                   inputTypes: ['address.private','u128.private','Token.record']
+ *                   (Sealance proof + its `[MerkleProof; 2u32].private` type
+ *                   are appended by the iframe — see
+ *                   `dynamic-waas-sdk/packages/aleo/src/client/client.ts`.)
+ *
+ *   - `arc21`       `token_registry.aleo/transfer_private`
+ *                   inputs:     [recipient, amount, record]
+ *                   inputTypes: ['address.private','u128.private','Token.record']
+ *                   (token_id is encoded inside the record's plaintext, not
+ *                   passed as an explicit input.)
+ *
+ * The 5 ARC-21 entries are mainnet-only (Hyperlane warp routes are not
+ * deployed on testnet). Stablecoins and credits exist on both networks.
+ */
+const ALEO_MAINNET_NETWORK_ID = 0;
+const ALEO_TESTNET_NETWORK_ID = 1;
+const ALEO_CREDITS_DECIMALS = 6;
+const ALEO_CREDITS_PROGRAM = 'credits.aleo';
+const ALEO_TOKEN_REGISTRY_PROGRAM = 'token_registry.aleo';
+const ALEO_CREDITS_TOKEN = {
+    contractAddress: ALEO_CREDITS_PROGRAM,
+    decimals: ALEO_CREDITS_DECIMALS,
+    logoURI: '',
+    name: 'Aleo Credits',
+    programId: ALEO_CREDITS_PROGRAM,
+    programKind: 'credits',
+    recordName: 'credits',
+    recordTypeLiteral: 'credits.record',
+    symbol: 'ALEO',
+};
+const ALEO_STABLECOIN_DECIMALS = 6;
+const buildStablecoin = (programId, symbol, name) => ({
+    contractAddress: programId,
+    decimals: ALEO_STABLECOIN_DECIMALS,
+    name,
+    programId,
+    programKind: 'stablecoin',
+    recordName: 'Token',
+    recordTypeLiteral: 'Token.record',
+    symbol,
+});
+const buildArc21 = (args) => ({
+    contractAddress: args.warpProgram,
+    decimals: args.decimals,
+    externalAuthRequired: false,
+    name: args.name,
+    programId: ALEO_TOKEN_REGISTRY_PROGRAM,
+    programKind: 'arc21',
+    recordName: 'Token',
+    recordTypeLiteral: 'Token.record',
+    symbol: args.symbol,
+    tokenId: args.tokenId,
+});
+const ALEO_SENDABLE_TOKENS_BY_NETWORK = {
+    [ALEO_MAINNET_NETWORK_ID]: [
+        ALEO_CREDITS_TOKEN,
+        buildStablecoin('usad_stablecoin.aleo', 'USAD', 'USAD'),
+        buildStablecoin('usdcx_stablecoin.aleo', 'USDCx', 'USDCx'),
+        buildArc21({
+            decimals: 9,
+            name: 'Wrapped SOL',
+            symbol: 'wSOL',
+            tokenId: '2045969100091121326225168054634646230244820821909676777152465722877810201564field',
+            warpProgram: 'hyp_warp_token_sol.aleo',
+        }),
+        buildArc21({
+            decimals: 18,
+            name: 'Wrapped ETH',
+            symbol: 'wETH',
+            tokenId: '8189585964265444162798552221009403350643900573290534096996249214099143169251field',
+            warpProgram: 'hyp_warp_token_eth.aleo',
+        }),
+        buildArc21({
+            decimals: 8,
+            name: 'Wrapped BTC',
+            symbol: 'wBTC',
+            tokenId: '3491859903473482085250871387962132231204352466326026409883548131580582527809field',
+            warpProgram: 'hyp_warp_token_wbtc.aleo',
+        }),
+        buildArc21({
+            decimals: 6,
+            name: 'Tether USD',
+            symbol: 'USDT',
+            tokenId: '7881654794448182580124231856035865816599796419758925654292946277940935117913field',
+            warpProgram: 'hyp_warp_token_usdt.aleo',
+        }),
+        buildArc21({
+            decimals: 6,
+            name: 'USD Coin',
+            symbol: 'USDC',
+            tokenId: '4697275201844475848710842677807162058146139844643350200269139278887318953049field',
+            warpProgram: 'hyp_warp_token_usdc.aleo',
+        }),
+    ],
+    [ALEO_TESTNET_NETWORK_ID]: [
+        ALEO_CREDITS_TOKEN,
+        buildStablecoin('test_usad_stablecoin.aleo', 'USAD', 'USAD'),
+        buildStablecoin('test_usdcx_stablecoin.aleo', 'USDCx', 'USDCx'),
+    ],
+};
+const getAleoSendableTokensForNetwork = (networkId) => { var _a; return (_a = ALEO_SENDABLE_TOKENS_BY_NETWORK[networkId]) !== null && _a !== void 0 ? _a : []; };
+/**
+ * True when the owned record matches the given sendable token: same program
+ * + record name, and (for ARC-21) same token_id encoded in the plaintext.
+ *
+ * For ARC-21, multiple tokens share `token_registry.aleo/Token`, so the
+ * plaintext-level token_id check is what disambiguates wSOL records from
+ * USDT records, etc. We match by substring rather than parsing the full
+ * record DSL — the field literal `<digits>field` is unambiguous and the
+ * record DSL is stable across snarkVM versions.
+ */
+const recordMatchesSendableToken = (record, token) => {
+    if (record.program_name !== token.programId)
+        return false;
+    if (record.record_name !== token.recordName)
+        return false;
+    if (typeof record.record_plaintext !== 'string')
+        return false;
+    if (token.programKind !== 'arc21')
+        return true;
+    if (!token.tokenId)
+        return false;
+    return record.record_plaintext.includes(`token_id: ${token.tokenId}`);
+};
+/**
+ * Atomic-units amount from the record plaintext.
+ *
+ *   - credits → pre-parsed `microcredits` (decimal string).
+ *   - stablecoin / arc21 → parsed from `amount: <digits>u128` in plaintext.
+ *
+ * Returns `0n` when nothing parses — the caller's UI rules
+ * (sum / merge CTA / picker entry) all degrade gracefully on a zero amount.
+ */
+const extractRecordAtomicAmount = (record, token) => {
+    if (token.programKind === 'credits') {
+        if (typeof record.microcredits !== 'string')
+            return BigInt(0);
+        try {
+            return BigInt(record.microcredits);
+        }
+        catch (_a) {
+            return BigInt(0);
+        }
+    }
+    if (typeof record.record_plaintext !== 'string')
+        return BigInt(0);
+    const match = /amount:\s*(\d+)u128/.exec(record.record_plaintext);
+    if (!match)
+        return BigInt(0);
+    try {
+        return BigInt(match[1]);
+    }
+    catch (_b) {
+        return BigInt(0);
+    }
+};
+
+exports.ALEO_CREDITS_DECIMALS = ALEO_CREDITS_DECIMALS;
+exports.ALEO_CREDITS_PROGRAM = ALEO_CREDITS_PROGRAM;
+exports.ALEO_SENDABLE_TOKENS_BY_NETWORK = ALEO_SENDABLE_TOKENS_BY_NETWORK;
+exports.ALEO_TOKEN_REGISTRY_PROGRAM = ALEO_TOKEN_REGISTRY_PROGRAM;
+exports.extractRecordAtomicAmount = extractRecordAtomicAmount;
+exports.getAleoSendableTokensForNetwork = getAleoSendableTokensForNetwork;
+exports.recordMatchesSendableToken = recordMatchesSendableToken;

package/src/utils/aleoSendableTokens/aleoSendableTokens.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-network registry of tokens spendable from the wallet's *shielded*
+ * (private record) state via the widget Send view.
+ *
+ * Three program kinds, three submit paths:
+ *
+ *   - `credits`     `credits.aleo/transfer_private`
+ *                   inputs:     [record, recipient, amount]
+ *                   inputTypes: ['credits.record','address.private','u64.private']
+ *
+ *                   `credits.aleo/transfer_private_to_public`
+ *                   inputs:     [record, recipient, amount]
+ *                   inputTypes: ['credits.record','address.public','u64.public']
+ *
+ *   - `stablecoin`  `<stablecoin>/transfer_private`
+ *                   inputs:     [recipient, amount, record]
+ *                   inputTypes: ['address.private','u128.private','Token.record']
+ *                   (Sealance proof + its `[MerkleProof; 2u32].private` type
+ *                   are appended by the iframe — see
+ *                   `dynamic-waas-sdk/packages/aleo/src/client/client.ts`.)
+ *
+ *   - `arc21`       `token_registry.aleo/transfer_private`
+ *                   inputs:     [recipient, amount, record]
+ *                   inputTypes: ['address.private','u128.private','Token.record']
+ *                   (token_id is encoded inside the record's plaintext, not
+ *                   passed as an explicit input.)
+ *
+ * The 5 ARC-21 entries are mainnet-only (Hyperlane warp routes are not
+ * deployed on testnet). Stablecoins and credits exist on both networks.
+ */
+export declare const ALEO_CREDITS_DECIMALS = 6;
+export declare const ALEO_CREDITS_PROGRAM = "credits.aleo";
+export declare const ALEO_TOKEN_REGISTRY_PROGRAM = "token_registry.aleo";
+export type AleoProgramKind = 'arc21' | 'credits' | 'stablecoin';
+export type AleoSendableToken = {
+    contractAddress: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    programId: string;
+    tokenId?: string;
+    externalAuthRequired?: boolean;
+    recordTypeLiteral: string;
+    recordName: string;
+    programKind: AleoProgramKind;
+    logoURI?: string;
+};
+export declare const ALEO_SENDABLE_TOKENS_BY_NETWORK: Record<number, AleoSendableToken[]>;
+export declare const getAleoSendableTokensForNetwork: (networkId: number) => AleoSendableToken[];
+/** Owned record as returned by `DynamicAleoWalletClient.findOwnedRecords`. */
+export type AleoOwnedRecord = {
+    program_name?: string;
+    record_name?: string;
+    record_plaintext?: string;
+    /** Set only for `credits.aleo/credits` records — pre-parsed by the iframe. */
+    microcredits?: string;
+};
+/**
+ * True when the owned record matches the given sendable token: same program
+ * + record name, and (for ARC-21) same token_id encoded in the plaintext.
+ *
+ * For ARC-21, multiple tokens share `token_registry.aleo/Token`, so the
+ * plaintext-level token_id check is what disambiguates wSOL records from
+ * USDT records, etc. We match by substring rather than parsing the full
+ * record DSL — the field literal `<digits>field` is unambiguous and the
+ * record DSL is stable across snarkVM versions.
+ */
+export declare const recordMatchesSendableToken: (record: AleoOwnedRecord, token: AleoSendableToken) => boolean;
+/**
+ * Atomic-units amount from the record plaintext.
+ *
+ *   - credits → pre-parsed `microcredits` (decimal string).
+ *   - stablecoin / arc21 → parsed from `amount: <digits>u128` in plaintext.
+ *
+ * Returns `0n` when nothing parses — the caller's UI rules
+ * (sum / merge CTA / picker entry) all degrade gracefully on a zero amount.
+ */
+export declare const extractRecordAtomicAmount: (record: AleoOwnedRecord, token: AleoSendableToken) => bigint;