@dynamic-labs/aleo 4.79.2 → 4.80.0

package/src/utils/AleoUiTransaction/AleoUiTransaction.cjs

@@ -0,0 +1,354 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../../_virtual/_tslib.cjs');
+var utils = require('@dynamic-labs/utils');
+var aleoSendableTokens = require('../aleoSendableTokens/aleoSendableTokens.cjs');
+
+// `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 _tslib.__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) => aleoSendableTokens.recordMatchesSendableToken(r, this.selectedToken));
+        const largest = matching.reduce((acc, r) => {
+            const v = aleoSendableTokens.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 utils.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 utils.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 _tslib.__awaiter(this, void 0, void 0, function* () {
+            const records = yield this.refreshRecordsCache();
+            return records
+                .filter((r) => aleoSendableTokens.recordMatchesSendableToken(r, this.selectedToken))
+                .reduce((acc, r) => acc + aleoSendableTokens.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 _tslib.__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 _tslib.__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) => aleoSendableTokens.recordMatchesSendableToken(r, token))
+                    .reduce((acc, r) => acc + aleoSendableTokens.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 _tslib.__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) => aleoSendableTokens.recordMatchesSendableToken(r, this.selectedToken) &&
+                typeof r.record_plaintext === 'string')
+                .map((r) => ({
+                atomic: aleoSendableTokens.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 _tslib.__awaiter(this, void 0, void 0, function* () {
+            const records = yield this.listOwnedRecords();
+            this.cachedRecords = records;
+            return records;
+        });
+    }
+    tokensForNetwork() {
+        return aleoSendableTokens.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: aleoSendableTokens.ALEO_CREDITS_PROGRAM,
+            decimals: aleoSendableTokens.ALEO_CREDITS_DECIMALS,
+            logoURI: '',
+            name: 'Aleo Credits',
+            programId: aleoSendableTokens.ALEO_CREDITS_PROGRAM,
+            programKind: 'credits',
+            recordName: 'credits',
+            recordTypeLiteral: 'credits.record',
+            symbol: 'ALEO',
+        };
+    }
+}
+
+exports.AleoUiTransaction = AleoUiTransaction;

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

@@ -0,0 +1,130 @@
+import { TokenBalance } from '@dynamic-labs/sdk-api-core';
+import { IUITransaction, IUITransactionFormatOptions, RecordMergeAction, TransactionModeOption } from '@dynamic-labs/types';
+import { AleoOwnedRecord, AleoSendableToken } from '../aleoSendableTokens';
+export type AleoTransferMode = 'exchange' | 'individual';
+export type AleoSubmitParams = {
+    to: string;
+    value: bigint;
+    mode: AleoTransferMode;
+    recordPlaintext: string;
+    token: AleoSendableToken;
+};
+type AleoUiTransactionProps = {
+    /** The sender's `aleo1...` address. */
+    from: string;
+    networkId: number;
+    listOwnedRecords: () => Promise<AleoOwnedRecord[]>;
+    joinAllRecordsForToken: (token: AleoSendableToken) => Promise<void>;
+    onSubmit: (params: AleoSubmitParams) => Promise<string>;
+};
+/**
+ * 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`.
+ */
+export declare class AleoUiTransaction implements IUITransaction {
+    chain: string;
+    to: string | undefined;
+    from: string;
+    value: bigint | undefined;
+    data: string | undefined;
+    receipt: string | undefined;
+    fee: {
+        gas: bigint | undefined;
+    };
+    nativePrice?: number;
+    readonly transactionModes: TransactionModeOption[];
+    selectedTransactionMode: AleoTransferMode | undefined;
+    private readonly networkId;
+    private readonly listOwnedRecords;
+    private readonly joinAllRecordsForToken;
+    private readonly onSubmitFn;
+    private pendingValue;
+    private cachedRecords;
+    private selectedToken;
+    constructor({ from, networkId, listOwnedRecords, joinAllRecordsForToken, onSubmit, }: AleoUiTransactionProps);
+    setTransactionMode(modeId: string): void;
+    setSelectedToken(contractAddress: string): void;
+    setPendingAmount(amountInput: string): void;
+    /**
+     * 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).
+     */
+    private mergeRecordsForSelectedToken;
+    getRecordMergeAction(): RecordMergeAction | undefined;
+    /**
+     * 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: string): bigint;
+    format(value: bigint, { precision }?: IUITransactionFormatOptions): string;
+    validateAddressFormat(address: string): boolean;
+    /**
+     * 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(): Promise<bigint>;
+    /**
+     * 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(): Promise<void>;
+    isGasSponsored(): boolean;
+    /**
+     * 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(): Promise<TokenBalance[]>;
+    submit(): Promise<string>;
+    private refreshRecordsCache;
+    private tokensForNetwork;
+    private creditsFallback;
+}
+export {};