@ar.io/sdk 4.0.0-solana.34 → 4.0.0-solana.36

package/lib/esm/solana/ant-readable.js

@@ -22,7 +22,7 @@
  *   - AntControllers: list of controller pubkeys
  *   - AntRecord: undername records (transactionId, ttl, priority, etc.)
  */
-import { address, fetchEncodedAccount, } from '@solana/kit';
+import { address, fetchEncodedAccount, fetchEncodedAccounts, } from '@solana/kit';
 import bs58 from 'bs58';
 import { createHash as __createHash } from 'crypto';
 import { ANT_RECORD_DISCRIMINATOR, ANT_RECORD_METADATA_DISCRIMINATOR, decodeAntConfig, decodeAntControllers, getAntRecordDecoder, getAntRecordMetadataDecoder, } from '@ar.io/solana-contracts/ant';
@@ -148,6 +148,38 @@ export class SolanaANTReadable {
             controllers: decoded.controllers.map((c) => c),
         };
     }
+    /**
+     * Fetch AntConfig + AntControllers in a single `getMultipleAccounts` round
+     * trip (instead of two single-account reads). Used by `getState` to shave one
+     * RPC per ANT — meaningful when a UI loads many ANTs.
+     */
+    async _fetchConfigAndControllers() {
+        const [[configPda], [controllersPda]] = await Promise.all([
+            getAntConfigPDA(this.mint, this.antProgram),
+            getAntControllersPDA(this.mint, this.antProgram),
+        ]);
+        const [configAccount, controllersAccount] = await withRetry(() => fetchEncodedAccounts(this.rpc, [configPda, controllersPda], {
+            commitment: this.commitment,
+        }));
+        if (!configAccount.exists) {
+            throw new Error(`ANT config not found for ${this.processId}`);
+        }
+        const decodedConfig = decodeAntConfig(configAccount).data;
+        const config = {
+            mint: decodedConfig.mint,
+            name: decodedConfig.name,
+            ticker: decodedConfig.ticker,
+            logo: decodedConfig.logo,
+            description: decodedConfig.description,
+            keywords: decodedConfig.keywords,
+            owner: decodedConfig.lastKnownOwner,
+            version: decodedConfig.version.major,
+        };
+        const controllers = controllersAccount.exists
+            ? decodeAntControllers(controllersAccount).data.controllers.map((c) => c)
+            : [];
+        return { config, controllers };
+    }
     async getOwner(_opts) {
         const config = await this.fetchConfig();
         return config.owner;
@@ -186,10 +218,9 @@ export class SolanaANTReadable {
             getAntRecordPDA(this.mint, undername, this.antProgram),
             getAntRecordMetadataPDA(this.mint, undername, this.antProgram),
         ]);
-        const [recordAccount, metaAccount] = await Promise.all([
-            this.getAccount(recordPda),
-            this.getAccount(metaPda),
-        ]);
+        const [recordAccount, metaAccount] = await withRetry(() => fetchEncodedAccounts(this.rpc, [recordPda, metaPda], {
+            commitment: this.commitment,
+        }));
         if (!recordAccount.exists)
             return undefined;
         const recordDecoder = getAntRecordDecoder();
@@ -222,8 +253,12 @@ export class SolanaANTReadable {
                 : undefined,
         };
     }
-    async getRecords(_opts) {
-        // Fetch all AntRecord + AntRecordMetadata accounts for this mint in parallel.
+    async getRecords(opts) {
+        // Fetch all AntRecord accounts for this mint. AntRecordMetadata
+        // (displayName/logo/description/keywords) is a SECOND program scan and is
+        // only needed in detail/edit views, so skip it unless `includeMetadata` is
+        // set — halving the per-ANT request cost on list reads. See AntReadOptions.
+        const includeMetadata = opts?.includeMetadata === true;
         const gpaFilter = (discriminator) => [
             {
                 memcmp: {
@@ -248,13 +283,15 @@ export class SolanaANTReadable {
                 filters: gpaFilter(bs58.encode(ANT_RECORD_DISCRIMINATOR)),
             })
                 .send()),
-            withRetry(() => this.rpc
-                .getProgramAccounts(this.antProgram, {
-                commitment: this.commitment,
-                encoding: 'base64',
-                filters: gpaFilter(bs58.encode(ANT_RECORD_METADATA_DISCRIMINATOR)),
-            })
-                .send()),
+            includeMetadata
+                ? withRetry(() => this.rpc
+                    .getProgramAccounts(this.antProgram, {
+                    commitment: this.commitment,
+                    encoding: 'base64',
+                    filters: gpaFilter(bs58.encode(ANT_RECORD_METADATA_DISCRIMINATOR)),
+                })
+                    .send())
+                : Promise.resolve([]),
         ]));
         const recordDecoder = getAntRecordDecoder();
         const metaDecoder = getAntRecordMetadataDecoder();
@@ -312,6 +349,256 @@ export class SolanaANTReadable {
         }
         return result;
     }
+    /**
+     * Bulk-load lightweight {@link ANTSummary} state for many ANTs in a handful
+     * of `getMultipleAccounts` calls instead of `N × getState`. For each mint it
+     * batches AntConfig + AntControllers + the apex (`@`) AntRecord — everything a
+     * portfolio/names table needs. Full undername records are NOT loaded here;
+     * fetch them lazily per-ANT via {@link getRecords}/{@link getState} when a
+     * name is opened.
+     *
+     * Requests: ~`ceil(3N / 100)` calls for N mints (10 → 1, 250 → 8), versus
+     * ~`4N` with per-ANT `getState`. Assumes every mint is deployed under this
+     * instance's `antProgram` (true for the standard AR.IO ANT program).
+     *
+     * Mints whose AntConfig doesn't exist are omitted from the result.
+     */
+    async getANTSummaries(mints) {
+        const unique = Array.from(new Set(mints));
+        if (unique.length === 0)
+            return {};
+        // Derive config + controllers + apex('@') record PDAs for every mint.
+        const triples = await Promise.all(unique.map(async (m) => {
+            const mintAddr = address(m);
+            const [[configPda], [controllersPda], [apexPda]] = await Promise.all([
+                getAntConfigPDA(mintAddr, this.antProgram),
+                getAntControllersPDA(mintAddr, this.antProgram),
+                getAntRecordPDA(mintAddr, '@', this.antProgram),
+            ]);
+            return { mint: m, configPda, controllersPda, apexPda };
+        }));
+        // Batch-fetch all PDAs (3 per mint) — getMultipleAccounts caps at 100.
+        const allPdas = triples.flatMap((t) => [
+            t.configPda,
+            t.controllersPda,
+            t.apexPda,
+        ]);
+        const accounts = [];
+        for (let i = 0; i < allPdas.length; i += 100) {
+            const chunk = allPdas.slice(i, i + 100);
+            const res = await withRetry(() => fetchEncodedAccounts(this.rpc, chunk, { commitment: this.commitment }));
+            accounts.push(...res);
+        }
+        const recordDecoder = getAntRecordDecoder();
+        const result = {};
+        for (let i = 0; i < triples.length; i++) {
+            const { mint } = triples[i];
+            const configAccount = accounts[i * 3];
+            const controllersAccount = accounts[i * 3 + 1];
+            const apexAccount = accounts[i * 3 + 2];
+            if (!configAccount?.exists)
+                continue;
+            const config = decodeAntConfig(configAccount).data;
+            const controllers = controllersAccount?.exists
+                ? decodeAntControllers(controllersAccount).data.controllers.map((c) => c)
+                : [];
+            let apexRecord;
+            if (apexAccount?.exists) {
+                const rec = recordDecoder.decode(new Uint8Array(apexAccount.data));
+                apexRecord = {
+                    transactionId: rec.target,
+                    targetProtocol: rec.targetProtocol,
+                    ttlSeconds: rec.ttlSeconds,
+                    priority: rec.priority?.__option === 'Some' ? rec.priority.value : undefined,
+                    owner: rec.owner?.__option === 'Some'
+                        ? rec.owner.value
+                        : undefined,
+                };
+            }
+            result[mint] = {
+                processId: mint,
+                name: config.name,
+                ticker: config.ticker,
+                logo: config.logo,
+                description: config.description,
+                keywords: config.keywords,
+                owner: config.lastKnownOwner,
+                controllers,
+                apexRecord,
+            };
+        }
+        return result;
+    }
+    /**
+     * Bulk-load FULL {@link ANTState} (including all undername records) for many
+     * ANTs in a handful of calls instead of `N × getState`:
+     *   - AntConfig + AntControllers for every mint via `getMultipleAccounts`
+     *     (chunked at 100), and
+     *   - ALL undername records via a SINGLE program-wide `getProgramAccounts`
+     *     scan grouped by mint (offset 8), instead of one mint-filtered scan per
+     *     ANT.
+     *
+     * Requests: ~`ceil(2N / 100) + 1` (+1 when `includeMetadata`) regardless of
+     * N — e.g. 10 ANTs → 2 calls, 250 → ~6 — versus ~`2N` with per-ANT
+     * `getState`. The records scan reads every ANT's records program-wide (cheap
+     * per account, one round trip); prefer per-ANT {@link getState} when you only
+     * need one ANT. Mints with no AntConfig are omitted.
+     */
+    async getANTStates(mints, opts) {
+        const unique = Array.from(new Set(mints));
+        if (unique.length === 0)
+            return {};
+        // Config + controllers PDAs for every mint, batched (100 accounts/call).
+        const pairs = await Promise.all(unique.map(async (m) => {
+            const mintAddr = address(m);
+            const [[configPda], [controllersPda]] = await Promise.all([
+                getAntConfigPDA(mintAddr, this.antProgram),
+                getAntControllersPDA(mintAddr, this.antProgram),
+            ]);
+            return { mint: m, configPda, controllersPda };
+        }));
+        const allPdas = pairs.flatMap((p) => [p.configPda, p.controllersPda]);
+        const accounts = [];
+        for (let i = 0; i < allPdas.length; i += 100) {
+            const res = await withRetry(() => fetchEncodedAccounts(this.rpc, allPdas.slice(i, i + 100), {
+                commitment: this.commitment,
+            }));
+            accounts.push(...res);
+        }
+        const recordsByMint = await this._recordsByMint(opts?.includeMetadata === true);
+        const result = {};
+        for (let i = 0; i < pairs.length; i++) {
+            const { mint } = pairs[i];
+            const configAccount = accounts[i * 2];
+            const controllersAccount = accounts[i * 2 + 1];
+            if (!configAccount?.exists)
+                continue;
+            const config = decodeAntConfig(configAccount).data;
+            const controllers = controllersAccount?.exists
+                ? decodeAntControllers(controllersAccount).data.controllers.map((c) => c)
+                : [];
+            const sorted = recordsByMint.get(mint) ?? {};
+            const plainRecords = {};
+            for (const [key, val] of Object.entries(sorted)) {
+                const { index: _, ...rec } = val;
+                plainRecords[key] = rec;
+            }
+            const owner = config.lastKnownOwner;
+            result[mint] = {
+                Name: config.name,
+                Ticker: config.ticker,
+                Description: config.description,
+                Keywords: config.keywords,
+                Denomination: 0,
+                Owner: owner,
+                Controllers: controllers,
+                Records: plainRecords,
+                Balances: { [owner]: 1 },
+                Logo: config.logo,
+                TotalSupply: 1,
+                Initialized: true,
+            };
+        }
+        return result;
+    }
+    /**
+     * Group every AntRecord (+ optional metadata) in the program by mint via a
+     * single `getProgramAccounts` scan (the mint sits at offset 8). Used by
+     * {@link getANTStates} to load all ANTs' undername records in one round trip
+     * instead of one mint-filtered scan per ANT.
+     */
+    async _recordsByMint(includeMetadata) {
+        const discFilter = (discriminator) => [
+            {
+                memcmp: {
+                    offset: 0n,
+                    bytes: discriminator,
+                    encoding: 'base58',
+                },
+            },
+        ];
+        const [recordAccounts, metaAccounts] = (await Promise.all([
+            withRetry(() => this.rpc
+                .getProgramAccounts(this.antProgram, {
+                commitment: this.commitment,
+                encoding: 'base64',
+                filters: discFilter(bs58.encode(ANT_RECORD_DISCRIMINATOR)),
+            })
+                .send()),
+            includeMetadata
+                ? withRetry(() => this.rpc
+                    .getProgramAccounts(this.antProgram, {
+                    commitment: this.commitment,
+                    encoding: 'base64',
+                    filters: discFilter(bs58.encode(ANT_RECORD_METADATA_DISCRIMINATOR)),
+                })
+                    .send())
+                : Promise.resolve([]),
+        ]));
+        const recordDecoder = getAntRecordDecoder();
+        const metaDecoder = getAntRecordMetadataDecoder();
+        // Metadata keyed by `${mint}:${undernameHash}` (mint at 8, hash at 40).
+        const metaByKey = new Map();
+        for (const { account } of metaAccounts) {
+            try {
+                const buf = Buffer.from(account.data[0], 'base64');
+                const mint = bs58.encode(buf.subarray(8, 40));
+                const hash = buf.subarray(40, 72).toString('hex');
+                metaByKey.set(`${mint}:${hash}`, metaDecoder.decode(new Uint8Array(buf)));
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        const byMint = new Map();
+        const indexByMint = new Map();
+        for (const { account } of recordAccounts) {
+            try {
+                const buf = Buffer.from(account.data[0], 'base64');
+                const mint = bs58.encode(buf.subarray(8, 40));
+                const record = recordDecoder.decode(new Uint8Array(buf));
+                const hash = __createHash('sha256')
+                    .update(record.undername.toLowerCase())
+                    .digest('hex');
+                const meta = metaByKey.get(`${mint}:${hash}`);
+                const idx = indexByMint.get(mint) ?? 0;
+                let bucket = byMint.get(mint);
+                if (!bucket) {
+                    bucket = {};
+                    byMint.set(mint, bucket);
+                }
+                bucket[record.undername] = {
+                    transactionId: record.target,
+                    targetProtocol: record.targetProtocol,
+                    ttlSeconds: record.ttlSeconds,
+                    priority: record.priority?.__option === 'Some'
+                        ? record.priority.value
+                        : undefined,
+                    owner: record.owner?.__option === 'Some'
+                        ? record.owner.value
+                        : undefined,
+                    displayName: meta?.displayName?.__option === 'Some'
+                        ? meta.displayName.value
+                        : undefined,
+                    logo: meta?.recordLogo?.__option === 'Some'
+                        ? meta.recordLogo.value
+                        : undefined,
+                    description: meta?.recordDescription?.__option === 'Some'
+                        ? meta.recordDescription.value
+                        : undefined,
+                    keywords: meta?.recordKeywords?.__option === 'Some'
+                        ? meta.recordKeywords.value
+                        : undefined,
+                    index: idx,
+                };
+                indexByMint.set(mint, idx + 1);
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return byMint;
+    }
     // =========================================
     // Balance reads (NFT model — owner has balance 1)
     // =========================================
@@ -326,11 +613,10 @@ export class SolanaANTReadable {
     // =========================================
     // State / Info composites
     // =========================================
-    async getState(_opts) {
-        const [config, controllersData, records] = await Promise.all([
-            this.fetchConfig(),
-            this.fetchControllers(),
-            this.getRecords(),
+    async getState(opts) {
+        const [{ config, controllers }, records] = await Promise.all([
+            this._fetchConfigAndControllers(),
+            this.getRecords(opts),
         ]);
         // Convert SortedANTRecords to ANTRecords (strip index)
         const plainRecords = {};
@@ -345,7 +631,7 @@ export class SolanaANTReadable {
             Keywords: config.keywords,
             Denomination: 0,
             Owner: config.owner,
-            Controllers: controllersData.controllers,
+            Controllers: controllers,
             Records: plainRecords,
             Balances: { [config.owner]: 1 },
             Logo: config.logo,

package/lib/esm/solana/canonical-message.js

@@ -18,15 +18,18 @@
  *
  * Produces the EXACT bytes a recipient signs to release an escrowed
  * ANT. Output MUST be byte-identical to the Rust implementation in
- * `contracts/programs/ario-ant-escrow/src/canonical.rs::build_canonical_message`.
- * Cross-language equivalence is asserted by `canonical-message.test.ts`
- * which spawns the Rust `canonical` example binary and diffs the bytes.
+ * `ario-ant-escrow/src/canonical.rs::build_ant_escrow_claim_message`
+ * (header `ANT_ESCROW_CLAIM_HEADER = "ar.io ant-escrow claim"`). The on-chain
+ * program reconstructs these exact bytes and verifies the signature against
+ * them, so any drift (header, field set, or ordering) makes every claim fail
+ * `EthereumAddressMismatch` / signature verification.
  *
  * Format (UTF-8, line-feed separated, no trailing newline):
  *
  * ```text
- * ar.io ant-escrow claim v1
+ * ar.io ant-escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * ant: <ant_mint_base58>
  * claimant: <claimant_solana_pubkey_base58>
  * nonce: <nonce_hex_lowercase>
@@ -37,8 +40,9 @@
  * - Ethereum: `wallet.signMessage(bytes)` → 65-byte ECDSA + EIP-191 sig
  *   (the wallet applies the EIP-191 prefix; on-chain code re-applies it).
  */
-/** Header literal — must match Rust `CANONICAL_HEADER`. */
-const CANONICAL_HEADER = 'ar.io ant-escrow claim v1';
+import { sha256 } from '@noble/hashes/sha256';
+/** Header literal — must match Rust `ANT_ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER = 'ar.io ant-escrow claim';
 /**
  * Build the canonical claim message bytes. UTF-8 encoded, no trailing
  * newline, exactly the format shown in the docstring.
@@ -52,21 +56,23 @@ export function canonicalMessage(input) {
     }
     const text = `${CANONICAL_HEADER}\n` +
         `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
         `ant: ${input.antMint}\n` +
         `claimant: ${input.claimant}\n` +
         `nonce: ${bytesToHexLower(input.nonce)}`;
     return new TextEncoder().encode(text);
 }
-/** Header literal — must match Rust `CANONICAL_HEADER_V2`. */
-const CANONICAL_HEADER_V2 = 'ar.io escrow claim v2';
+/** Header literal — must match Rust `ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER_V2 = 'ar.io escrow claim';
 /**
  * Build the v2 canonical claim message bytes for token/vault escrows.
  * UTF-8 encoded, no trailing newline.
  *
  * Format:
  * ```text
- * ar.io escrow claim v2
+ * ar.io escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * type: <token|vault>
  * asset: <asset_id_hex_lowercase_64chars>
  * amount: <u64_decimal>
@@ -85,6 +91,7 @@ export function canonicalMessageV2(input) {
     }
     const text = `${CANONICAL_HEADER_V2}\n` +
         `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
         `type: ${input.assetType}\n` +
         `asset: ${bytesToHexLower(input.assetId)}\n` +
         `amount: ${input.amount.toString()}\n` +
@@ -95,6 +102,20 @@ export function canonicalMessageV2(input) {
 // =========================================
 // Shared utilities
 // =========================================
+/**
+ * Recipient identity bound into the claim message — `base64url(sha256(bytes))`
+ * with no padding (32-byte hash → 43 chars). Byte-identical to the contract's
+ * `canonical.rs::derive_recipient_id_b64url`. Input is the recipient pubkey
+ * bytes the deposit targeted (ETH 20-byte address / Solana 32-byte pubkey /
+ * Arweave RSA modulus, etc.).
+ */
+export function deriveRecipientId(recipient) {
+    if (recipient.length === 0) {
+        throw new Error('deriveRecipientId: recipient bytes must be non-empty');
+    }
+    // Node's 'base64url' encoding is unpadded — matches the Rust no-pad alphabet.
+    return Buffer.from(sha256(recipient)).toString('base64url');
+}
 /** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
 export function bytesToHexLower(bytes) {
     let s = '';

package/lib/esm/solana/index.js

@@ -91,7 +91,7 @@ export { ANTEscrow, TokenEscrow,
 // in lock-step so users never see a raw on-chain error.
 assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
 // Canonical claim-message helper (byte-equivalent to Rust impl)
-export { canonicalMessage, canonicalMessageV2, bytesToHexLower, } from './canonical-message.js';
+export { canonicalMessage, canonicalMessageV2, deriveRecipientId, bytesToHexLower, } from './canonical-message.js';
 // ANT spawn (mint MPL Core asset + initialize ario-ant state in one tx)
 export { spawnSolanaANT, ARIO_LOGO_TX_ID, DEFAULT_ANT_TRANSACTION_ID, } from './spawn-ant.js';
 // PDA derivation

package/lib/esm/solana/io-readable.js

@@ -105,6 +105,12 @@ function arnsRecordToWithName(record) {
             : {}),
     };
 }
+/**
+ * TTL for {@link SolanaARIOReadable.getCachedAccount}. DemandFactor / config
+ * accounts change on the order of epochs, so a few seconds of staleness is a
+ * safe trade for collapsing burst reads (e.g. per-row cost lookups).
+ */
+const CONFIG_CACHE_TTL_MS = 30_000;
 function paginate(items, params) {
     const limit = params?.limit ?? 100;
     const startIdx = params?.cursor ? parseInt(params.cursor, 10) : 0;
@@ -146,6 +152,11 @@ export class SolanaARIOReadable {
     // Memoized ARIO mint address (read once from ArioConfig.mint and reused
     // for every SPL-ATA derivation in getBalance/getBalances).
     _arioMint;
+    // Short-TTL cache for slow-changing config-ish accounts (DemandFactor,
+    // ArnsConfig, etc.). Collapses the many identical reads a UI fires in a
+    // burst — e.g. the returned-names page running `getCostDetails` per row,
+    // each re-reading the same DemandFactor PDA — into a single network call.
+    _accountCache = new Map();
     constructor(config) {
         this.rpc = config.rpc;
         this.commitment = config.commitment ?? 'confirmed';
@@ -161,6 +172,24 @@ export class SolanaARIOReadable {
             commitment: this.commitment,
         }));
     }
+    /**
+     * Like {@link getAccount} but caches the result per-PDA for `ttlMs`. Use only
+     * for accounts that change slowly (DemandFactor, ArnsConfig) where a few
+     * seconds of staleness is acceptable in exchange for collapsing repeated
+     * reads. A successful fetch is cached; misses (`exists: false`) are not.
+     */
+    async getCachedAccount(pda, ttlMs = CONFIG_CACHE_TTL_MS) {
+        const key = String(pda);
+        const now = Date.now();
+        const hit = this._accountCache.get(key);
+        if (hit && hit.expiresAt > now)
+            return hit.account;
+        const account = await this.getAccount(pda);
+        if (account.exists) {
+            this._accountCache.set(key, { account, expiresAt: now + ttlMs });
+        }
+        return account;
+    }
     /**
      * Helper for `getProgramAccounts` with a discriminator memcmp filter.
      *
@@ -959,7 +988,11 @@ export class SolanaARIOReadable {
     }
     async getArNSReturnedName({ name, }) {
         const [pda] = await getReturnedNamePDA(name, this.arnsProgram);
-        const account = await this.getAccount(pda);
+        // A ReturnedName account is immutable once created (its premium is derived
+        // client-side from the static start/end timestamps), so cache the read.
+        // The returned-names price table reads each name's PDA twice (lease +
+        // permabuy) and `getTokenCost` reads it again — all share one fetch.
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error(`Returned name not found: ${name}`);
         }
@@ -1239,7 +1272,7 @@ export class SolanaARIOReadable {
      */
     async getTokenCost(params) {
         const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
-        const dfAccount = await this.getAccount(dfPda);
+        const dfAccount = await this.getCachedAccount(dfPda);
         if (!dfAccount.exists)
             throw new Error('DemandFactor account not found');
         const df = deserializeDemandFactor(Buffer.from(dfAccount.data));
@@ -1327,14 +1360,22 @@ export class SolanaARIOReadable {
         const discounts = [];
         if (params.fromAddress) {
             try {
-                const gw = await this.getGateway({ address: params.fromAddress });
-                if (gw.status === 'joined') {
-                    const discountAmount = Math.floor((tokenCost * 200_000) / RATE_SCALE);
-                    discounts.push({
-                        name: 'Gateway Operator',
-                        discountTotal: discountAmount,
-                        multiplier: 0.8,
-                    });
+                // Operator-discount check. Read the gateway PDA through the short-TTL
+                // cache (NOT public `getGateway`, which stays fresh for gateway pages):
+                // a price table calls `getCostDetails` many times for the SAME
+                // `fromAddress`, so this collapses N redundant gateway reads to one.
+                const [gwPda] = await getGatewayPDA(address(params.fromAddress), this.garProgram);
+                const gwAccount = await this.getCachedAccount(gwPda);
+                if (gwAccount.exists) {
+                    const gw = deserializeGateway(Buffer.from(gwAccount.data));
+                    if (gw.status === 'joined') {
+                        const discountAmount = Math.floor((tokenCost * 200_000) / RATE_SCALE);
+                        discounts.push({
+                            name: 'Gateway Operator',
+                            discountTotal: discountAmount,
+                            multiplier: 0.8,
+                        });
+                    }
                 }
             }
             catch {
@@ -1441,7 +1482,7 @@ export class SolanaARIOReadable {
     }
     async getRegistrationFees() {
         const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(dfPda);
+        const account = await this.getCachedAccount(dfPda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1464,7 +1505,7 @@ export class SolanaARIOReadable {
     }
     async getDemandFactor() {
         const [pda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1473,7 +1514,7 @@ export class SolanaARIOReadable {
     }
     async getDemandFactorSettings() {
         const [pda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1730,7 +1771,7 @@ export class SolanaARIOReadable {
      */
     async getExpiredArnsRecords(now) {
         const [arnsConfigPda] = await getArnsSettingsPDA(this.arnsProgram);
-        const cfgAccount = await this.getAccount(arnsConfigPda);
+        const cfgAccount = await this.getCachedAccount(arnsConfigPda);
         if (!cfgAccount.exists)
             return [];
         const cfg = getArnsConfigDecoder().decode(cfgAccount.data);
@@ -1765,7 +1806,7 @@ export class SolanaARIOReadable {
      */
     async getExpiredReturnedNames(now) {
         const [arnsConfigPda] = await getArnsSettingsPDA(this.arnsProgram);
-        const cfgAccount = await this.getAccount(arnsConfigPda);
+        const cfgAccount = await this.getCachedAccount(arnsConfigPda);
         if (!cfgAccount.exists)
             return [];
         const cfg = getArnsConfigDecoder().decode(cfgAccount.data);
@@ -2011,7 +2052,7 @@ export class SolanaARIOReadable {
      */
     async getArnsConfigRaw() {
         const [pda] = await getArnsSettingsPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists)
             return null;
         const cfg = getArnsConfigDecoder().decode(account.data);

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-solana.34';
+export const version = '4.0.0-solana.36';

package/lib/types/solana/ant-readable.d.ts

@@ -24,7 +24,7 @@
  */
 import { type Address, type Commitment } from '@solana/kit';
 import { type ILogger } from '../common/logger.js';
-import type { ANTHandler, ANTInfo, ANTRecord, ANTState, AntReadOptions, SortedANTRecords } from '../types/ant.js';
+import type { ANTHandler, ANTInfo, ANTRecord, ANTState, ANTSummary, AntReadOptions, SortedANTRecords } from '../types/ant.js';
 import type { WalletAddress } from '../types/common.js';
 import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 import type { SolanaRpc } from './types.js';
@@ -99,6 +99,12 @@ export declare class SolanaANTReadable {
     private getAccount;
     private fetchConfig;
     private fetchControllers;
+    /**
+     * Fetch AntConfig + AntControllers in a single `getMultipleAccounts` round
+     * trip (instead of two single-account reads). Used by `getState` to shave one
+     * RPC per ANT — meaningful when a UI loads many ANTs.
+     */
+    private _fetchConfigAndControllers;
     getOwner(_opts?: AntReadOptions): Promise<WalletAddress>;
     /** Get the on-chain schema version of this ANT's config. */
     getConfigVersion(): Promise<number>;
@@ -111,12 +117,50 @@ export declare class SolanaANTReadable {
     getRecord({ undername }: {
         undername: string;
     }, _opts?: AntReadOptions): Promise<ANTRecord | undefined>;
-    getRecords(_opts?: AntReadOptions): Promise<SortedANTRecords>;
+    getRecords(opts?: AntReadOptions): Promise<SortedANTRecords>;
+    /**
+     * Bulk-load lightweight {@link ANTSummary} state for many ANTs in a handful
+     * of `getMultipleAccounts` calls instead of `N × getState`. For each mint it
+     * batches AntConfig + AntControllers + the apex (`@`) AntRecord — everything a
+     * portfolio/names table needs. Full undername records are NOT loaded here;
+     * fetch them lazily per-ANT via {@link getRecords}/{@link getState} when a
+     * name is opened.
+     *
+     * Requests: ~`ceil(3N / 100)` calls for N mints (10 → 1, 250 → 8), versus
+     * ~`4N` with per-ANT `getState`. Assumes every mint is deployed under this
+     * instance's `antProgram` (true for the standard AR.IO ANT program).
+     *
+     * Mints whose AntConfig doesn't exist are omitted from the result.
+     */
+    getANTSummaries(mints: ReadonlyArray<string>): Promise<Record<string, ANTSummary>>;
+    /**
+     * Bulk-load FULL {@link ANTState} (including all undername records) for many
+     * ANTs in a handful of calls instead of `N × getState`:
+     *   - AntConfig + AntControllers for every mint via `getMultipleAccounts`
+     *     (chunked at 100), and
+     *   - ALL undername records via a SINGLE program-wide `getProgramAccounts`
+     *     scan grouped by mint (offset 8), instead of one mint-filtered scan per
+     *     ANT.
+     *
+     * Requests: ~`ceil(2N / 100) + 1` (+1 when `includeMetadata`) regardless of
+     * N — e.g. 10 ANTs → 2 calls, 250 → ~6 — versus ~`2N` with per-ANT
+     * `getState`. The records scan reads every ANT's records program-wide (cheap
+     * per account, one round trip); prefer per-ANT {@link getState} when you only
+     * need one ANT. Mints with no AntConfig are omitted.
+     */
+    getANTStates(mints: ReadonlyArray<string>, opts?: AntReadOptions): Promise<Record<string, ANTState>>;
+    /**
+     * Group every AntRecord (+ optional metadata) in the program by mint via a
+     * single `getProgramAccounts` scan (the mint sits at offset 8). Used by
+     * {@link getANTStates} to load all ANTs' undername records in one round trip
+     * instead of one mint-filtered scan per ANT.
+     */
+    private _recordsByMint;
     getBalance({ address: queryAddress }: {
         address: WalletAddress;
     }, _opts?: AntReadOptions): Promise<number>;
     getBalances(_opts?: AntReadOptions): Promise<Record<WalletAddress, number>>;
-    getState(_opts?: AntReadOptions): Promise<ANTState>;
+    getState(opts?: AntReadOptions): Promise<ANTState>;
     getInfo(_opts?: AntReadOptions): Promise<ANTInfo>;
     getHandlers(): Promise<ANTHandler[]>;
     getModuleId(_opts?: {

package/lib/types/solana/canonical-message.d.ts

@@ -18,15 +18,18 @@
  *
  * Produces the EXACT bytes a recipient signs to release an escrowed
  * ANT. Output MUST be byte-identical to the Rust implementation in
- * `contracts/programs/ario-ant-escrow/src/canonical.rs::build_canonical_message`.
- * Cross-language equivalence is asserted by `canonical-message.test.ts`
- * which spawns the Rust `canonical` example binary and diffs the bytes.
+ * `ario-ant-escrow/src/canonical.rs::build_ant_escrow_claim_message`
+ * (header `ANT_ESCROW_CLAIM_HEADER = "ar.io ant-escrow claim"`). The on-chain
+ * program reconstructs these exact bytes and verifies the signature against
+ * them, so any drift (header, field set, or ordering) makes every claim fail
+ * `EthereumAddressMismatch` / signature verification.
  *
  * Format (UTF-8, line-feed separated, no trailing newline):
  *
  * ```text
- * ar.io ant-escrow claim v1
+ * ar.io ant-escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * ant: <ant_mint_base58>
  * claimant: <claimant_solana_pubkey_base58>
  * nonce: <nonce_hex_lowercase>
@@ -50,6 +53,12 @@ export interface CanonicalMessageInput {
     /** Solana pubkey that will receive the ANT on claim. Bound into the
      *  signature so front-runners can't redirect. */
     claimant: Address;
+    /** Recipient identity pubkey bytes the deposit targeted (ETH 20-byte
+     *  address, Solana 32-byte pubkey, or Arweave RSA modulus). Bound into the
+     *  message as `recipient: base64url(sha256(bytes))` to match the contract's
+     *  `derive_recipient_id_b64url`. REQUIRED — the program reconstructs this
+     *  line, so omitting it makes the claim mismatch. */
+    recipient: Uint8Array;
     /** 32-byte anti-replay nonce — read from the EscrowAnt account. */
     nonce: Uint8Array;
 }
@@ -72,6 +81,12 @@ export interface CanonicalMessageV2Input {
     amount: bigint;
     /** Solana pubkey that will receive the tokens on claim. */
     claimant: Address;
+    /** Recipient identity pubkey bytes the deposit targeted (ETH 20-byte
+     *  address, Solana 32-byte pubkey, or Arweave RSA modulus). Bound into the
+     *  message as `recipient: base64url(sha256(bytes))` to match the contract's
+     *  `derive_recipient_id_b64url`. REQUIRED — the program reconstructs this
+     *  line, so omitting it makes the claim mismatch. */
+    recipient: Uint8Array;
     /** 32-byte anti-replay nonce — read from the EscrowToken account. */
     nonce: Uint8Array;
 }
@@ -81,8 +96,9 @@ export interface CanonicalMessageV2Input {
  *
  * Format:
  * ```text
- * ar.io escrow claim v2
+ * ar.io escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * type: <token|vault>
  * asset: <asset_id_hex_lowercase_64chars>
  * amount: <u64_decimal>
@@ -93,5 +109,13 @@ export interface CanonicalMessageV2Input {
  * @throws if `assetId` or `nonce` aren't exactly 32 bytes.
  */
 export declare function canonicalMessageV2(input: CanonicalMessageV2Input): Uint8Array;
+/**
+ * Recipient identity bound into the claim message — `base64url(sha256(bytes))`
+ * with no padding (32-byte hash → 43 chars). Byte-identical to the contract's
+ * `canonical.rs::derive_recipient_id_b64url`. Input is the recipient pubkey
+ * bytes the deposit targeted (ETH 20-byte address / Solana 32-byte pubkey /
+ * Arweave RSA modulus, etc.).
+ */
+export declare function deriveRecipientId(recipient: Uint8Array): string;
 /** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
 export declare function bytesToHexLower(bytes: Uint8Array): string;

package/lib/types/solana/index.d.ts

@@ -68,7 +68,7 @@ export type { SolanaANTRegistryWriteableConfig } from './ant-registry-writeable.
 export type { AclMaintenanceOp, AclMaintenanceRole, } from '../types/ant-registry.js';
 export { ANTEscrow, TokenEscrow, assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
 export type { ANTEscrowConfig, EscrowAntState, EscrowAssetType, EscrowProtocol, EscrowTokenState, } from './escrow.js';
-export { canonicalMessage, canonicalMessageV2, bytesToHexLower, } from './canonical-message.js';
+export { canonicalMessage, canonicalMessageV2, deriveRecipientId, bytesToHexLower, } from './canonical-message.js';
 export type { CanonicalMessageInput, CanonicalMessageV2Input, EscrowNetwork, } from './canonical-message.js';
 export { spawnSolanaANT, ARIO_LOGO_TX_ID, DEFAULT_ANT_TRANSACTION_ID, } from './spawn-ant.js';
 export type { SpawnSolanaANTParams, SpawnSolanaANTResult, SpawnSolanaANTState, } from './spawn-ant.js';

package/lib/types/solana/io-readable.d.ts

@@ -49,6 +49,7 @@ export declare class SolanaARIOReadable {
     protected readonly arnsProgram: Address;
     protected readonly antProgram: Address;
     private _arioMint?;
+    private _accountCache;
     constructor(config: SolanaReadConfig & {
         logger?: ILogger;
         coreProgramId?: Address;
@@ -58,6 +59,13 @@ export declare class SolanaARIOReadable {
     });
     /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
     private getAccount;
+    /**
+     * Like {@link getAccount} but caches the result per-PDA for `ttlMs`. Use only
+     * for accounts that change slowly (DemandFactor, ArnsConfig) where a few
+     * seconds of staleness is acceptable in exchange for collapsing repeated
+     * reads. A successful fetch is cached; misses (`exists: false`) are not.
+     */
+    private getCachedAccount;
     /**
      * Helper for `getProgramAccounts` with a discriminator memcmp filter.
      *

package/lib/types/types/ant.d.ts

@@ -193,6 +193,25 @@ export declare const AntStateSchema: z.ZodObject<{
     Initialized: boolean;
 }>;
 export type ANTState = z.infer<typeof AntStateSchema>;
+/**
+ * Lightweight ANT view for portfolio/list rendering. Carries the config fields
+ * plus controllers and the apex (`@`) record — everything a names table needs —
+ * WITHOUT the full undername record set. Produced in bulk by
+ * `getANTSummaries(mints)` in a handful of `getMultipleAccounts` calls; fetch
+ * full undernames lazily via `getRecords`/`getState` when a name is opened.
+ */
+export type ANTSummary = {
+    processId: string;
+    name: string;
+    ticker: string;
+    logo: string;
+    description: string;
+    keywords: string[];
+    owner: WalletAddress;
+    controllers: WalletAddress[];
+    /** The apex (`@`) record — the name's primary target — if set. */
+    apexRecord?: ANTRecord;
+};
 export declare const SpawnANTStateSchema: z.ZodObject<{
     name: z.ZodString;
     ticker: z.ZodString;
@@ -324,6 +343,14 @@ export type ANTInfo = z.infer<typeof AntInfoSchema>;
 export declare function isANTState(state: object): state is ANTState;
 export type AntReadOptions = {
     strict?: boolean;
+    /**
+     * Include per-record metadata (`displayName`/`logo`/`description`/`keywords`)
+     * when reading undername records. Defaults to `false` — metadata requires a
+     * second `getProgramAccounts` scan per ANT and is only needed in detail/edit
+     * views, so list reads (`getState`/`getRecords`) skip it by default. Fetch a
+     * single record's metadata on demand via `getRecord`.
+     */
+    includeMetadata?: boolean;
 };
 export interface ANTRead {
     processId: string;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.33";
+export declare const version = "4.0.0-solana.35";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.34",
+  "version": "4.0.0-solana.36",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -115,6 +115,7 @@
   },
   "dependencies": {
     "@ar.io/solana-contracts": "0.7.0-staging.17",
+    "@noble/hashes": "^1.8.0",
     "@solana-program/address-lookup-table": "^0.11.0",
     "@solana-program/compute-budget": "^0.15.0",
     "@solana-program/token": "^0.13.0",