@ar.io/sdk 3.24.0 → 4.0.0-solana.1

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

@@ -0,0 +1,1349 @@
+/**
+ * Solana implementation of the AoARIORead interface.
+ *
+ * Reads AR.IO protocol state directly from Solana PDAs using RPC,
+ * returning the same types that the AO implementation returns.
+ * This allows consumers to switch backends transparently.
+ */
+import { address, fetchEncodedAccount, fetchEncodedAccounts, getAddressDecoder, } from '@solana/kit';
+import bs58 from 'bs58';
+import { Logger } from '../common/logger.js';
+import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
+import { getAssociatedTokenAddressKit } from './ata.js';
+import { ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARNS_RECORD_ANT_OFFSET, RATE_SCALE, } from './constants.js';
+import { deserializeAllowlist, deserializeArioConfig, deserializeArnsRecord, deserializeDelegation, deserializeDemandFactor, deserializeEpoch, deserializeEpochSettings, deserializeEpochSettingsFull, deserializeGarSettings, deserializeGarSupplyCounters, deserializeGateway, deserializeObservation, deserializePrimaryName, deserializePrimaryNameRequest, deserializeRedelegationRecord, deserializeReservedName, deserializeReturnedName, deserializeVault, deserializeWithdrawal, } from './deserialize.js';
+import { ARNS_RECORD_DISCRIMINATOR } from './generated/arns/accounts/arnsRecord.js';
+import { RESERVED_NAME_DISCRIMINATOR } from './generated/arns/accounts/reservedName.js';
+import { RETURNED_NAME_DISCRIMINATOR } from './generated/arns/accounts/returnedName.js';
+import { PRIMARY_NAME_DISCRIMINATOR } from './generated/core/accounts/primaryName.js';
+import { PRIMARY_NAME_REQUEST_DISCRIMINATOR } from './generated/core/accounts/primaryNameRequest.js';
+import { VAULT_DISCRIMINATOR } from './generated/core/accounts/vault.js';
+import { ALLOWLIST_ENTRY_DISCRIMINATOR } from './generated/gar/accounts/allowlistEntry.js';
+import { DELEGATION_DISCRIMINATOR } from './generated/gar/accounts/delegation.js';
+import { GATEWAY_DISCRIMINATOR } from './generated/gar/accounts/gateway.js';
+import { OBSERVATION_DISCRIMINATOR } from './generated/gar/accounts/observation.js';
+import { WITHDRAWAL_DISCRIMINATOR } from './generated/gar/accounts/withdrawal.js';
+import { TOKEN_PROGRAM_ADDRESS } from './instruction.js';
+import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
+const addressDecoder = getAddressDecoder();
+/** All-zero address — equivalent of web3.js `PublicKey.default`. */
+const DEFAULT_ADDRESS = address('11111111111111111111111111111111');
+// =========================================
+// Pagination helper
+// =========================================
+/**
+ * Normalize whatever `params.filters?.processId` shape came in (undefined,
+ * single string, or array — `PaginationParams` widens it past what ArNS
+ * actually supports) into a flat `string[]` ANT-mint list.
+ */
+function normalizeProcessIdFilter(raw) {
+    if (raw == null)
+        return [];
+    if (typeof raw === 'string')
+        return [raw];
+    if (Array.isArray(raw))
+        return raw.filter((v) => typeof v === 'string');
+    return [];
+}
+/**
+ * On-chain timestamps in the Solana programs are stored in **seconds**
+ * (matching the Lua-source convention as ported), but the public SDK
+ * surface — shared with the AO backend — exposes them in **milliseconds**
+ * because every JS consumer (UI, cranker, migration tools) feeds them into
+ * `new Date()`/`Date.now()` arithmetic. This boundary helper converts at
+ * the read-path projection layer so internal arithmetic in this file can
+ * keep working in seconds against the deserializer output, but everything
+ * we hand back to a caller is in JS-millisecond units.
+ *
+ * Use `toMsTimestamps(obj)` for projection-layer return values, and
+ * `secToMs(n)` for one-off scalars.
+ */
+const TIMESTAMP_FIELDS_MS = [
+    'startTimestamp',
+    'endTimestamp',
+    'distributionTimestamp',
+];
+function secToMs(n) {
+    return n * 1000;
+}
+function toMsTimestamps(obj) {
+    const out = { ...obj };
+    for (const f of TIMESTAMP_FIELDS_MS) {
+        const v = out[f];
+        if (typeof v === 'number')
+            out[f] = v * 1000;
+    }
+    return out;
+}
+/**
+ * Drop the SDK-internal extras (`name`, `owner`) and the `processId` re-key
+ * that `deserializeArnsRecord` adds, projecting back to the cross-backend
+ * `AoArNSNameDataWithName` shape consumers expect.
+ *
+ * Timestamps are converted from on-chain seconds to JS milliseconds here
+ * (see `toMsTimestamps` above for rationale).
+ */
+function arnsRecordToWithName(record) {
+    return {
+        name: record.name,
+        processId: record.processId,
+        startTimestamp: secToMs(record.startTimestamp),
+        undernameLimit: record.undernameLimit,
+        purchasePrice: record.purchasePrice,
+        type: record.type,
+        ...('endTimestamp' in record
+            ? { endTimestamp: secToMs(record.endTimestamp) }
+            : {}),
+    };
+}
+function paginate(items, params) {
+    const limit = params?.limit ?? 100;
+    const startIdx = params?.cursor ? parseInt(params.cursor, 10) : 0;
+    const page = items.slice(startIdx, startIdx + limit);
+    const hasMore = startIdx + limit < items.length;
+    return {
+        items: page,
+        limit,
+        totalItems: items.length,
+        sortOrder: params?.sortOrder ?? 'asc',
+        hasMore,
+        nextCursor: hasMore ? String(startIdx + limit) : undefined,
+    };
+}
+/**
+ * Solana-backed read-only client for the AR.IO protocol.
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc } from '@solana/kit';
+ * import { SolanaARIOReadable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const ario = new SolanaARIOReadable({ rpc });
+ *
+ * const gateway = await ario.getGateway({ address: 'GatewayOperatorPubkey...' });
+ * const record = await ario.getArNSRecord({ name: 'ardrive' });
+ * ```
+ */
+export class SolanaARIOReadable {
+    rpc;
+    commitment;
+    logger;
+    // Allow overriding program IDs (e.g., for devnet/localnet)
+    coreProgram;
+    garProgram;
+    arnsProgram;
+    antProgram;
+    // Memoized ARIO mint address (read once from ArioConfig.mint and reused
+    // for every SPL-ATA derivation in getBalance/getBalances).
+    _arioMint;
+    constructor(config) {
+        this.rpc = config.rpc;
+        this.commitment = config.commitment ?? 'confirmed';
+        this.logger = config.logger ?? Logger.default;
+        this.coreProgram = config.coreProgramId ?? ARIO_CORE_PROGRAM_ID;
+        this.garProgram = config.garProgramId ?? ARIO_GAR_PROGRAM_ID;
+        this.arnsProgram = config.arnsProgramId ?? ARIO_ARNS_PROGRAM_ID;
+        this.antProgram = config.antProgramId ?? ARIO_ANT_PROGRAM_ID;
+    }
+    /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
+    async getAccount(pda) {
+        return fetchEncodedAccount(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+    }
+    /**
+     * Helper for `getProgramAccounts` with a discriminator memcmp filter.
+     *
+     * Pass the Codama-generated `<NAME>_DISCRIMINATOR: Uint8Array` constant
+     * directly — kit's RPC requires a base58 string for `memcmp.bytes`, so
+     * we bs58-encode here to keep call sites from doing it inline (and to
+     * keep the IDL-derived bytes as the single source of truth).
+     */
+    async getAccountsByDiscriminator(programId, discriminator, extraFilters = []) {
+        const filters = [
+            {
+                memcmp: {
+                    offset: 0n,
+                    bytes: bs58.encode(discriminator),
+                    encoding: 'base58',
+                },
+            },
+            ...extraFilters,
+        ];
+        // Note: kit's getProgramAccounts returns a plain array (no context wrapper)
+        // when called without `withContext: true`. With `encoding: 'base64'`, each
+        // account's `data` is a `[base64, 'base64']` tuple. We bypass kit's strict
+        // generic overload typing here with a cast — the runtime shape is stable.
+        const result = (await this.rpc
+            .getProgramAccounts(programId, {
+            commitment: this.commitment,
+            encoding: 'base64',
+            filters,
+        })
+            .send());
+        return result.map((entry) => ({
+            pubkey: entry.pubkey,
+            data: Buffer.from(entry.account.data[0], 'base64'),
+        }));
+    }
+    /** Read the gateway registry and return addresses in registry index order */
+    async getRegistryGatewayAddresses() {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await this.getAccount(registryPda);
+        if (!registryAccount.exists)
+            return [];
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40); // 8 disc + 32 authority
+        const slotsOffset = 48; // 8 + 32 + 4 + 4
+        // GatewaySlot: address(32) + composite_weight(8) + start_timestamp(8)
+        //            + status(1) + _padding(7) = 56 bytes (see ario-gar
+        //            state/mod.rs::GatewaySlot).
+        const SLOT_STRIDE = 56;
+        const addresses = [];
+        for (let i = 0; i < count && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            addresses.push(addr);
+        }
+        return addresses;
+    }
+    // =========================================
+    // Protocol info
+    // =========================================
+    async getInfo() {
+        const [[configPda], [epochSettingsPda]] = await Promise.all([
+            getArioConfigPDA(this.coreProgram),
+            getEpochSettingsPDA(this.garProgram),
+        ]);
+        const [configAccount, epochAccount] = await Promise.all([
+            this.getAccount(configPda),
+            this.getAccount(epochSettingsPda),
+        ]);
+        const config = configAccount.exists
+            ? deserializeArioConfig(Buffer.from(configAccount.data))
+            : null;
+        const epoch = epochAccount.exists
+            ? deserializeEpochSettings(Buffer.from(epochAccount.data))
+            : null;
+        return {
+            Ticker: 'ARIO',
+            Name: 'AR.IO',
+            Logo: '',
+            Denomination: 6,
+            Handlers: [],
+            LastCreatedEpochIndex: 0,
+            LastDistributedEpochIndex: 0,
+            ...(config
+                ? {
+                    totalSupply: config.totalSupply,
+                    protocolBalance: config.protocolBalance,
+                }
+                : {}),
+            ...(epoch ? { epochSettings: epoch } : {}),
+        };
+    }
+    async getTokenSupply() {
+        const [configPda] = await getArioConfigPDA(this.coreProgram);
+        const [garSettingsPda] = await getGarSettingsPDA(this.garProgram);
+        const [configAccount, garSettingsAccount] = await Promise.all([
+            this.getAccount(configPda),
+            this.getAccount(garSettingsPda),
+        ]);
+        if (!configAccount.exists) {
+            throw new Error('ArioConfig account not found');
+        }
+        const config = deserializeArioConfig(Buffer.from(configAccount.data));
+        // Supply counters from GatewaySettings (staked/delegated/withdrawn).
+        // Falls back to 0 if GatewaySettings doesn't exist yet or is at the
+        // old size (pre-supply-counters layout).
+        let staked = 0;
+        let delegated = 0;
+        let withdrawn = 0;
+        if (garSettingsAccount.exists) {
+            try {
+                const counters = deserializeGarSupplyCounters(Buffer.from(garSettingsAccount.data));
+                staked = counters.totalStaked;
+                delegated = counters.totalDelegated;
+                withdrawn = counters.totalWithdrawn;
+            }
+            catch {
+                // Old-layout account without supply counters — fall back to 0
+            }
+        }
+        return {
+            total: config.totalSupply,
+            circulating: config.circulatingSupply,
+            locked: config.lockedSupply,
+            staked,
+            delegated,
+            withdrawn,
+            protocolBalance: config.protocolBalance,
+        };
+    }
+    // =========================================
+    // Balance read methods
+    // =========================================
+    /**
+     * Resolve the ARIO SPL mint address from the on-chain `ArioConfig`.
+     *
+     * `ArioConfig` layout: [8 disc][32 authority][32 mint][...]. We decode
+     * the mint at offset 40 and cache it for the lifetime of this instance —
+     * the mint never changes once the protocol is deployed.
+     */
+    async getArioMint() {
+        if (this._arioMint)
+            return this._arioMint;
+        const [configPda] = await getArioConfigPDA(this.coreProgram);
+        const account = await this.getAccount(configPda);
+        if (!account.exists) {
+            throw new Error(`ArioConfig not found at ${configPda} on coreProgram ${this.coreProgram} — is the program deployed and initialized?`);
+        }
+        const data = Buffer.from(account.data);
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        this._arioMint = mint;
+        return mint;
+    }
+    /**
+     * Liquid ARIO balance for an address.
+     *
+     * On Solana the ARIO token is a real SPL mint, so the canonical liquid
+     * balance lives on the user's Associated Token Account — *not* the
+     * `ario-core::Balance` PDA. The Balance PDA is only populated by the
+     * one-shot AO-to-Solana migration importer for legacy snapshot accounts;
+     * spending it requires a separate claim flow that mints/transfers SPL
+     * tokens to the user's ATA. Steady-state instructions like `buy_name`,
+     * gateway/delegate stake, and ARIO transfers all move SPL tokens, so the
+     * ATA is what every UI and on-chain caller cares about.
+     *
+     * Returns 0 if the user has no ATA initialized yet.
+     */
+    async getBalance({ address: owner, }) {
+        const mint = await this.getArioMint();
+        const ata = await getAssociatedTokenAddressKit(mint, address(owner));
+        const account = await this.getAccount(ata);
+        if (!account.exists)
+            return 0;
+        // SPL Token Account layout: [0..32]=mint, [32..64]=owner, [64..72]=amount(u64 LE), …
+        const data = account.data;
+        if (data.length < 72)
+            return 0;
+        // NOTE: avoid `Buffer.readBigUInt64LE` — some browser bundlers (notably
+        // arns-react's Vite output) strip the BigInt readers from the
+        // `buffer@6.0.3` shim's prototype. Manual little-endian u64 decode is
+        // portable across every JS runtime.
+        let amount = 0n;
+        for (let i = 7; i >= 0; i--) {
+            amount = (amount << 8n) | BigInt(data[64 + i]);
+        }
+        // ARIO supply caps at 1B * 1e6 mARIO ≈ 2^50, well under Number.MAX_SAFE_INTEGER.
+        return Number(amount);
+    }
+    /**
+     * Enumerate liquid ARIO balances by querying the SPL Token program for
+     * every initialized token account on the ARIO mint.
+     *
+     * Filters: token-account size = 165, mint at offset 0. We then decode
+     * `owner` (offset 32) and `amount` (offset 64) from each.
+     */
+    async getBalances(params) {
+        const mint = await this.getArioMint();
+        const filters = [
+            { dataSize: 165n },
+            {
+                memcmp: {
+                    offset: 0n,
+                    bytes: mint,
+                    encoding: 'base58',
+                },
+            },
+        ];
+        const result = (await this.rpc
+            .getProgramAccounts(TOKEN_PROGRAM_ADDRESS, {
+            commitment: this.commitment,
+            encoding: 'base64',
+            filters,
+        })
+            .send());
+        const items = [];
+        for (const entry of result) {
+            try {
+                const data = Buffer.from(entry.account.data[0], 'base64');
+                if (data.length < 72)
+                    continue;
+                const ownerAddress = addressDecoder.decode(data.subarray(32, 64));
+                const amount = Number(data.readBigUInt64LE(64));
+                if (amount > 0) {
+                    items.push({ address: ownerAddress, balance: amount });
+                }
+            }
+            catch {
+                // Skip malformed accounts
+            }
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // Vault read methods
+    // =========================================
+    async getVault({ address: owner, vaultId, }) {
+        const [pda] = await getVaultPDA(address(owner), BigInt(vaultId), this.coreProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Vault not found for ${owner}:${vaultId}`);
+        }
+        const vault = deserializeVault(Buffer.from(account.data));
+        return {
+            balance: vault.balance,
+            startTimestamp: secToMs(vault.startTimestamp),
+            endTimestamp: secToMs(vault.endTimestamp),
+            controller: vault.controller,
+        };
+    }
+    async getVaults(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.coreProgram, VAULT_DISCRIMINATOR);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const vault = deserializeVault(data);
+                items.push({
+                    address: vault.owner,
+                    vaultId: pubkey,
+                    balance: vault.balance,
+                    startTimestamp: secToMs(vault.startTimestamp),
+                    endTimestamp: secToMs(vault.endTimestamp),
+                    controller: vault.controller,
+                });
+            }
+            catch {
+                // Skip malformed accounts
+            }
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // Gateway read methods
+    // =========================================
+    async getGateway({ address: addr }) {
+        const [pda] = await getGatewayPDA(address(addr), this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Gateway not found for operator ${addr}`);
+        }
+        const gw = deserializeGateway(Buffer.from(account.data));
+        const { operator: _, ...gateway } = gw;
+        return toMsTimestamps(gateway);
+    }
+    async getGateways(params) {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await this.getAccount(registryPda);
+        if (!registryAccount.exists) {
+            return paginate([], params);
+        }
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40);
+        const slotsOffset = 48;
+        // GatewaySlot = address(32) + composite_weight(8) + start_timestamp(8)
+        //              + status(1) + _padding(7) = 56 bytes (see ario-gar
+        //              state/mod.rs::GatewaySlot). A previous off-by-16-bytes-per-slot
+        //              stride silently read garbage for slots 1+, returning at most
+        //              one gateway no matter how many had joined.
+        const SLOT_STRIDE = 56;
+        const gatewayAddresses = [];
+        for (let i = 0; i < count && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            if (addr !== DEFAULT_ADDRESS) {
+                gatewayAddresses.push(addr);
+            }
+        }
+        // Batch fetch gateway PDAs (kit has no hard limit but keep 100-at-a-time
+        // for sensible RPC request sizes).
+        const allItems = [];
+        for (let i = 0; i < gatewayAddresses.length; i += 100) {
+            const batch = gatewayAddresses.slice(i, i + 100);
+            const pdas = await Promise.all(batch.map(async (addr) => (await getGatewayPDA(addr, this.garProgram))[0]));
+            const accounts = await fetchEncodedAccounts(this.rpc, pdas, {
+                commitment: this.commitment,
+            });
+            for (const acct of accounts) {
+                if (!acct.exists)
+                    continue;
+                try {
+                    const gw = deserializeGateway(Buffer.from(acct.data));
+                    allItems.push(toMsTimestamps({ ...gw, gatewayAddress: gw.operator }));
+                }
+                catch {
+                    // Skip malformed
+                }
+            }
+        }
+        return paginate(allItems, params);
+    }
+    async getGatewayDelegates(params) {
+        const gateway = address(params.address);
+        // Filter delegations by gateway pubkey at offset 8 (after discriminator)
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR, [
+            {
+                memcmp: { offset: 8n, bytes: gateway, encoding: 'base58' },
+            },
+        ]);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                const del = deserializeDelegation(data);
+                items.push({
+                    address: del.delegator,
+                    delegatedStake: del.delegatedStake,
+                    startTimestamp: secToMs(del.startTimestamp),
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getGatewayDelegateAllowList(params) {
+        const gateway = address(params.address);
+        // Filter allowlist entries by gateway pubkey at offset 8
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, ALLOWLIST_ENTRY_DISCRIMINATOR, [
+            {
+                memcmp: { offset: 8n, bytes: gateway, encoding: 'base58' },
+            },
+        ]);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                const entry = deserializeAllowlist(data);
+                items.push(entry.delegate);
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getDelegations(params) {
+        const delegator = address(params.address);
+        // Filter delegations by delegator pubkey at offset 40 (8 disc + 32 gateway)
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR, [
+            {
+                memcmp: {
+                    offset: 40n,
+                    bytes: delegator,
+                    encoding: 'base58',
+                },
+            },
+        ]);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const del = deserializeDelegation(data);
+                items.push({
+                    type: 'stake',
+                    gatewayAddress: del.gateway,
+                    delegationId: pubkey,
+                    startTimestamp: secToMs(del.startTimestamp),
+                    balance: del.delegatedStake,
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getAllowedDelegates(params) {
+        return this.getGatewayDelegateAllowList(params);
+    }
+    async getGatewayVaults(params) {
+        const gateway = address(params.address);
+        // Withdrawal: disc(8) + owner(32) + withdrawal_id(8) + gateway(32)
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR, [
+            {
+                memcmp: { offset: 48n, bytes: gateway, encoding: 'base58' },
+            },
+        ]);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const w = deserializeWithdrawal(data);
+                if (!w.isDelegate) {
+                    items.push({
+                        cursorId: pubkey,
+                        vaultId: w.vaultId,
+                        balance: w.balance,
+                        startTimestamp: secToMs(w.startTimestamp),
+                        endTimestamp: secToMs(w.endTimestamp),
+                    });
+                }
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // ArNS read methods
+    // =========================================
+    async getArNSRecord({ name }) {
+        const [pda] = await getArnsRecordPDA(name, this.arnsProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`ArNS record not found: ${name}`);
+        }
+        const record = deserializeArnsRecord(Buffer.from(account.data));
+        const { name: _, owner: __, ...nameData } = record;
+        return nameData;
+    }
+    async getArNSRecords(params) {
+        // `processId` is the only filter the AO backend supports today and the
+        // only one that maps to a fixed-offset memcmp on `ArnsRecord` (the
+        // `ant` field, see `ARNS_RECORD_ANT_OFFSET`). When supplied we
+        // dispatch through the bulk-by-mint path so the RPC does the
+        // filtering instead of streaming every record back to the client.
+        const filterMints = normalizeProcessIdFilter(params?.filters?.processId);
+        if (filterMints.length > 0) {
+            const items = await this.fetchArnsRecordsByAntMints(filterMints);
+            return paginate(items, params);
+        }
+        const accounts = await this.getAccountsByDiscriminator(this.arnsProgram, ARNS_RECORD_DISCRIMINATOR);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                items.push(arnsRecordToWithName(deserializeArnsRecord(data)));
+            }
+            catch {
+                // Skip accounts that don't match
+            }
+        }
+        return paginate(items, params);
+    }
+    /**
+     * Fetch every `ArnsRecord` whose `ant` field equals one of `mints`.
+     *
+     * Issues one `getProgramAccounts` per mint with a memcmp filter at
+     * `ARNS_RECORD_ANT_OFFSET`, in parallel. Cheaper than scanning the
+     * whole registry as soon as the caller has fewer mints than the
+     * registry has records (today the break-even is ≈ a few hundred
+     * mints against ≈ 4k records, and rises as the registry grows).
+     *
+     * The shape mirrors `getArNSRecord` / `getArNSRecords` — same
+     * `AoArNSNameDataWithName` items, no pagination wrapper. Callers
+     * that want pagination should drive it via `getArNSRecords({
+     * filters: { processId: mints } })` instead.
+     */
+    async getArNSRecordsByAntMints({ mints, }) {
+        return this.fetchArnsRecordsByAntMints(mints);
+    }
+    async fetchArnsRecordsByAntMints(mints) {
+        const unique = Array.from(new Set(mints));
+        if (unique.length === 0)
+            return [];
+        // Parallel fan-out: one filtered gPA per mint. Each request is
+        // selective (matches at most one record on a healthy registry),
+        // so the marginal cost is mostly the round trip; major RPCs index
+        // memcmp filters at stable offsets, keeping this O(N) in network
+        // round trips rather than O(N) in registry size.
+        const perMint = await Promise.all(unique.map((mint) => this.getAccountsByDiscriminator(this.arnsProgram, ARNS_RECORD_DISCRIMINATOR, [
+            {
+                memcmp: {
+                    offset: BigInt(ARNS_RECORD_ANT_OFFSET),
+                    bytes: mint,
+                    encoding: 'base58',
+                },
+            },
+        ])));
+        const items = [];
+        const seen = new Set();
+        for (const accounts of perMint) {
+            for (const { pubkey, data } of accounts) {
+                const key = String(pubkey);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                try {
+                    items.push(arnsRecordToWithName(deserializeArnsRecord(data)));
+                }
+                catch {
+                    // Skip malformed
+                }
+            }
+        }
+        return items;
+    }
+    /**
+     * Resolve every ArNS record currently controlled by `address`.
+     *
+     * Mirrors the AO backend: walk the on-chain ANT ACL for the wallet
+     * (`Owned ∪ Controlled`), then issue point-queries against the
+     * ArNS registry for those mints. This is semantically *not* a query
+     * over `ArnsRecord.owner` — that field is a write-once "purchase
+     * receipt" and never reflects current control on Solana (see
+     * ISSUES.md). Authoritative control flows through the ANT NFT
+     * owner / `AntControllers`, which is exactly what the ACL
+     * indexes.
+     */
+    async getArNSRecordsForAddress(params) {
+        const registry = new SolanaANTRegistryReadable({
+            rpc: this.rpc,
+            commitment: this.commitment,
+            logger: this.logger,
+            antProgramId: this.antProgram,
+        });
+        const { Owned = [], Controlled = [] } = await registry.accessControlList({
+            address: params.address,
+        });
+        const mints = Array.from(new Set([...Owned, ...Controlled]));
+        if (mints.length === 0) {
+            return {
+                items: [],
+                hasMore: false,
+                nextCursor: undefined,
+                limit: params.limit ?? 100,
+                totalItems: 0,
+                sortOrder: params.sortOrder ?? 'asc',
+            };
+        }
+        const items = await this.fetchArnsRecordsByAntMints(mints);
+        return paginate(items, params);
+    }
+    async getArNSReservedNames(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.arnsProgram, RESERVED_NAME_DISCRIMINATOR);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                const reserved = deserializeReservedName(data);
+                items.push({
+                    name: reserved.name,
+                    target: reserved.target,
+                    endTimestamp: typeof reserved.endTimestamp === 'number'
+                        ? secToMs(reserved.endTimestamp)
+                        : reserved.endTimestamp,
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getArNSReservedName({ name, }) {
+        const [pda] = await getReservedNamePDA(name, this.arnsProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Reserved name not found: ${name}`);
+        }
+        const reserved = deserializeReservedName(Buffer.from(account.data));
+        return {
+            target: reserved.target,
+            endTimestamp: typeof reserved.endTimestamp === 'number'
+                ? secToMs(reserved.endTimestamp)
+                : reserved.endTimestamp,
+        };
+    }
+    async getArNSReturnedNames(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.arnsProgram, RETURNED_NAME_DISCRIMINATOR);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                items.push(toMsTimestamps(deserializeReturnedName(data)));
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getArNSReturnedName({ name, }) {
+        const [pda] = await getReturnedNamePDA(name, this.arnsProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Returned name not found: ${name}`);
+        }
+        return toMsTimestamps(deserializeReturnedName(Buffer.from(account.data)));
+    }
+    // =========================================
+    // Epoch read methods
+    // =========================================
+    async getEpochSettings() {
+        const [pda] = await getEpochSettingsPDA(this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error('Epoch settings account not found');
+        }
+        return deserializeEpochSettings(Buffer.from(account.data));
+    }
+    /**
+     * Resolve an EpochInput to an epoch index number.
+     * - undefined: returns current epoch index from EpochSettings
+     * - { epochIndex }: returns directly
+     * - { timestamp }: computes from genesis timestamp and epoch duration
+     */
+    async resolveEpochIndex(epoch) {
+        if (epoch && 'epochIndex' in epoch) {
+            return epoch.epochIndex;
+        }
+        const [pda] = await getEpochSettingsPDA(this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists)
+            throw new Error('EpochSettings account not found');
+        const settings = deserializeEpochSettingsFull(Buffer.from(account.data));
+        if (!epoch) {
+            return settings.currentEpochIndex;
+        }
+        // { timestamp } — compute epoch index. The public API takes `timestamp`
+        // in JS milliseconds (matching the AO contract convention), but
+        // genesisTimestamp/epochDuration come straight off chain in seconds, so
+        // normalize to seconds before doing the division.
+        const tsSeconds = Math.floor(epoch.timestamp / 1000);
+        const elapsed = tsSeconds - settings.genesisTimestamp;
+        return Math.floor(elapsed / settings.epochDuration);
+    }
+    /** Fetch and deserialize an Epoch account by index */
+    async fetchEpoch(epochIndex) {
+        const [pda] = await getEpochPDA(epochIndex, this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Epoch ${epochIndex} not found`);
+        }
+        return deserializeEpoch(Buffer.from(account.data));
+    }
+    async getEpoch(epoch) {
+        const epochIndex = await this.resolveEpochIndex(epoch);
+        const epochData = await this.fetchEpoch(epochIndex);
+        // Build prescribed observers list (only up to observerCount)
+        const prescribedObservers = [];
+        for (let i = 0; i < epochData.observerCount; i++) {
+            const observerAddress = epochData.prescribedObservers[i];
+            const gatewayAddress = epochData.prescribedObserverGateways[i];
+            if (observerAddress === DEFAULT_ADDRESS)
+                continue;
+            // Try to fetch gateway data for weights
+            let weights = {
+                stakeWeight: 0,
+                tenureWeight: 0,
+                gatewayRewardRatioWeight: 0,
+                observerRewardRatioWeight: 0,
+                gatewayPerformanceRatio: 0,
+                observerPerformanceRatio: 0,
+                compositeWeight: 0,
+                normalizedCompositeWeight: 0,
+            };
+            let stake = 0;
+            let startTimestamp = 0;
+            try {
+                const gw = await this.getGateway({ address: gatewayAddress });
+                weights = gw.weights;
+                stake = gw.operatorStake;
+                // gw.startTimestamp is already converted to ms by getGateway.
+                startTimestamp = gw.startTimestamp;
+            }
+            catch {
+                // Gateway may no longer exist
+            }
+            prescribedObservers.push({
+                gatewayAddress: gatewayAddress,
+                observerAddress: observerAddress,
+                stake,
+                startTimestamp,
+                ...weights,
+            });
+        }
+        // Build prescribed names list by resolving hashes → ArnsRecord PDAs
+        const prescribedNames = [];
+        const zeroHash = Buffer.alloc(32);
+        for (let i = 0; i < epochData.nameCount; i++) {
+            const nameHash = epochData.prescribedNameHashes[i];
+            if (!nameHash || nameHash.equals(zeroHash))
+                continue;
+            try {
+                const [recordPda] = await getArnsRecordPDAFromHash(nameHash, this.arnsProgram);
+                const recordAccount = await this.getAccount(recordPda);
+                if (recordAccount.exists) {
+                    const record = deserializeArnsRecord(Buffer.from(recordAccount.data));
+                    prescribedNames.push(record.name);
+                }
+            }
+            catch {
+                // Record may have been removed
+            }
+        }
+        // Build observations from Observation PDAs
+        const observations = await this.getObservations({ epochIndex });
+        // Build distribution totals
+        const distributions = {
+            totalEligibleGateways: epochData.activeGatewayCount,
+            totalEligibleRewards: epochData.totalEligibleRewards,
+            totalEligibleObserverReward: epochData.perObserverReward * epochData.observerCount,
+            totalEligibleGatewayReward: epochData.perGatewayReward * epochData.activeGatewayCount,
+        };
+        return {
+            epochIndex,
+            startHeight: 0, // Solana doesn't use AO block heights
+            startTimestamp: secToMs(epochData.startTimestamp),
+            endTimestamp: secToMs(epochData.endTimestamp),
+            distributionTimestamp: secToMs(epochData.endTimestamp),
+            observations,
+            prescribedObservers,
+            prescribedNames,
+            distributions,
+            arnsStats: {
+                totalReturnedNames: 0,
+                totalActiveNames: 0,
+                totalGracePeriodNames: 0,
+                totalReservedNames: 0,
+            },
+        };
+    }
+    async getCurrentEpoch() {
+        return this.getEpoch(undefined);
+    }
+    async getPrescribedObservers(epoch) {
+        const epochData = await this.getEpoch(epoch);
+        return epochData.prescribedObservers;
+    }
+    async getPrescribedNames(epoch) {
+        const epochIndex = await this.resolveEpochIndex(epoch);
+        const epochData = await this.fetchEpoch(epochIndex);
+        const names = [];
+        const zeroHash = Buffer.alloc(32);
+        for (let i = 0; i < epochData.nameCount; i++) {
+            const nameHash = epochData.prescribedNameHashes[i];
+            if (!nameHash || nameHash.equals(zeroHash))
+                continue;
+            try {
+                const [recordPda] = await getArnsRecordPDAFromHash(nameHash, this.arnsProgram);
+                const recordAccount = await this.getAccount(recordPda);
+                if (recordAccount.exists) {
+                    const record = deserializeArnsRecord(Buffer.from(recordAccount.data));
+                    names.push(record.name);
+                }
+            }
+            catch {
+                // Record may have been removed
+            }
+        }
+        return names;
+    }
+    async getObservations(epoch) {
+        const epochIndex = await this.resolveEpochIndex(epoch);
+        // Fetch all Observation accounts for this epoch
+        const epochIndexBuf = Buffer.alloc(8);
+        epochIndexBuf.writeBigUInt64LE(BigInt(epochIndex));
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, OBSERVATION_DISCRIMINATOR, [
+            {
+                memcmp: {
+                    offset: 8n,
+                    bytes: bs58.encode(epochIndexBuf),
+                    encoding: 'base58',
+                },
+            },
+        ]);
+        const failureSummaries = {};
+        const reports = {};
+        // Read gateway registry to get index-to-address mapping (matches bitfield order)
+        const gatewayAddresses = await this.getRegistryGatewayAddresses();
+        for (const { data } of accounts) {
+            try {
+                const obs = deserializeObservation(data);
+                reports[obs.observer] = obs.reportTxId;
+                // Parse gateway_results bitmap — 1 = passed, 0 = failed (on-chain convention)
+                for (let i = 0; i < obs.gatewayCount && i < gatewayAddresses.length; i++) {
+                    const byteIdx = Math.floor(i / 8);
+                    const bitIdx = i % 8;
+                    const passed = (obs.gatewayResults[byteIdx] >> bitIdx) & 1;
+                    if (!passed) {
+                        const gwAddr = gatewayAddresses[i];
+                        if (!failureSummaries[gwAddr]) {
+                            failureSummaries[gwAddr] = [];
+                        }
+                        failureSummaries[gwAddr].push(obs.observer);
+                    }
+                }
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return { failureSummaries, reports };
+    }
+    async getDistributions(epoch) {
+        const epochIndex = await this.resolveEpochIndex(epoch);
+        const epochData = await this.fetchEpoch(epochIndex);
+        return {
+            totalEligibleGateways: epochData.activeGatewayCount,
+            totalEligibleRewards: epochData.totalEligibleRewards,
+            totalEligibleObserverReward: epochData.perObserverReward * epochData.observerCount,
+            totalEligibleGatewayReward: epochData.perGatewayReward * epochData.activeGatewayCount,
+        };
+    }
+    async getEligibleEpochRewards(epoch, params) {
+        const epochIndex = await this.resolveEpochIndex(epoch);
+        const epochData = await this.fetchEpoch(epochIndex);
+        const items = [];
+        // Each gateway operator gets a gateway reward
+        const gatewayAccounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
+        for (const { data } of gatewayAccounts) {
+            try {
+                const gw = deserializeGateway(data);
+                if (gw.status !== 'joined')
+                    continue;
+                items.push({
+                    type: 'operatorReward',
+                    recipient: gw.operator,
+                    eligibleReward: epochData.perGatewayReward,
+                    gatewayAddress: gw.operator,
+                    cursorId: gw.operator,
+                });
+            }
+            catch {
+                // skip
+            }
+        }
+        // Each prescribed observer gets an observer reward
+        for (let i = 0; i < epochData.observerCount; i++) {
+            const observerAddr = epochData.prescribedObservers[i];
+            const gatewayAddr = epochData.prescribedObserverGateways[i];
+            if (observerAddr === DEFAULT_ADDRESS)
+                continue;
+            items.push({
+                type: 'operatorReward',
+                recipient: gatewayAddr,
+                eligibleReward: epochData.perObserverReward,
+                gatewayAddress: gatewayAddr,
+                cursorId: `${gatewayAddr}-observer`,
+            });
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // Pricing / cost read methods
+    // =========================================
+    /**
+     * Compute the token cost for an ArNS operation.
+     *
+     * Mirrors the Rust pricing functions in ario-arns/src/pricing.rs.
+     * Uses BigInt for u128-equivalent overflow-safe arithmetic.
+     */
+    async getTokenCost(params) {
+        const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
+        const dfAccount = await this.getAccount(dfPda);
+        if (!dfAccount.exists)
+            throw new Error('DemandFactor account not found');
+        const df = deserializeDemandFactor(Buffer.from(dfAccount.data));
+        const name = params.name.toLowerCase();
+        const nameLen = Math.min(Math.max(name.length, 1), 51);
+        const baseFee = df.fees[nameLen - 1] ?? df.fees[df.fees.length - 1];
+        // currentDemandFactor is already divided by RATE_SCALE in deserializer,
+        // but we need the raw scaled value for integer math
+        const demandFactorRaw = BigInt(Math.round(df.currentDemandFactor * RATE_SCALE));
+        const scale = BigInt(RATE_SCALE);
+        const bf = BigInt(baseFee);
+        let cost;
+        switch (params.intent) {
+            case 'Buy-Name':
+            case 'Buy-Record': {
+                const purchaseType = params.type ?? 'lease';
+                if (purchaseType === 'permabuy') {
+                    cost = (bf * demandFactorRaw * 5n) / scale;
+                }
+                else {
+                    const years = BigInt(params.years ?? 1);
+                    const annualPct = 200000n;
+                    const yearFactor = scale + annualPct * years;
+                    cost = (bf * demandFactorRaw * yearFactor) / scale / scale;
+                }
+                try {
+                    const returned = await this.getArNSReturnedName({ name });
+                    if (returned) {
+                        // returned.startTimestamp is in ms (public API convention),
+                        // so the rest of this comparison is in ms too.
+                        const now = Date.now();
+                        const elapsed = now - returned.startTimestamp;
+                        const duration = 14 * 86_400_000;
+                        if (elapsed < duration) {
+                            const remaining = BigInt(duration - elapsed);
+                            const dur = BigInt(duration);
+                            const pctRemaining = (remaining * scale) / dur;
+                            const multiplier = 50n * pctRemaining;
+                            cost = (cost * multiplier) / scale;
+                        }
+                    }
+                }
+                catch {
+                    // Not a returned name — no premium
+                }
+                break;
+            }
+            case 'Extend-Lease': {
+                const years = BigInt(params.years ?? 1);
+                const annualPct = 200000n;
+                cost = (bf * demandFactorRaw * annualPct * years) / scale / scale;
+                break;
+            }
+            case 'Increase-Undername-Limit': {
+                const qty = BigInt(params.quantity ?? 1);
+                let isPermabuy = false;
+                try {
+                    const record = await this.getArNSRecord({ name });
+                    isPermabuy = record.type === 'permabuy';
+                }
+                catch {
+                    // default to lease pricing
+                }
+                const pct = isPermabuy ? 5000n : 1000n;
+                cost = (bf * demandFactorRaw * pct * qty) / scale / scale;
+                break;
+            }
+            case 'Upgrade-Name': {
+                const permabuyCost = (bf * demandFactorRaw * 5n) / scale;
+                cost = permabuyCost;
+                break;
+            }
+            case 'Primary-Name-Request': {
+                const primaryBaseFee = BigInt(df.fees[50]);
+                const annualPct = 200000n;
+                const yearFactor = scale + annualPct;
+                cost = (primaryBaseFee * demandFactorRaw * yearFactor) / scale / scale;
+                break;
+            }
+            default:
+                throw new Error(`Unknown intent: ${params.intent}`);
+        }
+        return Number(cost);
+    }
+    async getCostDetails(params) {
+        const tokenCost = await this.getTokenCost(params);
+        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,
+                    });
+                }
+            }
+            catch {
+                // Not a gateway operator — no discount
+            }
+        }
+        const totalDiscount = discounts.reduce((sum, d) => sum + d.discountTotal, 0);
+        return {
+            tokenCost: tokenCost - totalDiscount,
+            discounts,
+        };
+    }
+    async getRegistrationFees() {
+        const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
+        const account = await this.getAccount(dfPda);
+        if (!account.exists) {
+            throw new Error('DemandFactor account not found');
+        }
+        const df = deserializeDemandFactor(Buffer.from(account.data));
+        const result = {};
+        for (let len = 1; len <= 51; len++) {
+            const baseFee = df.fees[len - 1] ?? 0;
+            result[len] = {
+                lease: {
+                    1: Math.floor(baseFee * (1 + 0.2 * 1) * df.currentDemandFactor),
+                    2: Math.floor(baseFee * (1 + 0.2 * 2) * df.currentDemandFactor),
+                    3: Math.floor(baseFee * (1 + 0.2 * 3) * df.currentDemandFactor),
+                    4: Math.floor(baseFee * (1 + 0.2 * 4) * df.currentDemandFactor),
+                    5: Math.floor(baseFee * (1 + 0.2 * 5) * df.currentDemandFactor),
+                },
+                permabuy: Math.floor(baseFee * 5 * df.currentDemandFactor),
+            };
+        }
+        return result;
+    }
+    async getDemandFactor() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error('DemandFactor account not found');
+        }
+        return deserializeDemandFactor(Buffer.from(account.data))
+            .currentDemandFactor;
+    }
+    async getDemandFactorSettings() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error('DemandFactor account not found');
+        }
+        const df = deserializeDemandFactor(Buffer.from(account.data));
+        return {
+            periodZeroStartTimestamp: df.periodZeroStartTimestamp,
+            movingAvgPeriodCount: 7,
+            periodLengthMs: 86_400 * 1000,
+            demandFactorBaseValue: 1,
+            demandFactorMin: 0.5,
+            demandFactorUpAdjustmentRate: 50,
+            demandFactorDownAdjustmentRate: 25,
+            maxPeriodsAtMinDemandFactor: df.consecutivePeriodsWithMinDemandFactor,
+            criteria: 'revenue',
+        };
+    }
+    // =========================================
+    // Primary name read methods
+    // =========================================
+    async getPrimaryName(params) {
+        if ('address' in params) {
+            const [pda] = await getPrimaryNamePDA(address(params.address), this.coreProgram);
+            const account = await this.getAccount(pda);
+            if (!account.exists) {
+                throw new Error(`Primary name not found for address ${params.address}`);
+            }
+            return deserializePrimaryName(Buffer.from(account.data));
+        }
+        // Lookup by name — scan all primary name accounts
+        const accounts = await this.getAccountsByDiscriminator(this.coreProgram, PRIMARY_NAME_DISCRIMINATOR);
+        for (const { data } of accounts) {
+            try {
+                const pn = deserializePrimaryName(data);
+                if (pn.name === params.name) {
+                    return pn;
+                }
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        throw new Error(`Primary name not found: ${params.name}`);
+    }
+    async getPrimaryNameRequest(params) {
+        const [pda] = await getPrimaryNameRequestPDA(address(params.initiator), this.coreProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error(`Primary name request not found for ${params.initiator}`);
+        }
+        return deserializePrimaryNameRequest(Buffer.from(account.data));
+    }
+    async getPrimaryNameRequests(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.coreProgram, PRIMARY_NAME_REQUEST_DISCRIMINATOR);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                items.push(deserializePrimaryNameRequest(data));
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getPrimaryNames(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.coreProgram, PRIMARY_NAME_DISCRIMINATOR);
+        const items = [];
+        for (const { data } of accounts) {
+            try {
+                items.push(deserializePrimaryName(data));
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // Redelegation fee
+    // =========================================
+    async getRedelegationFee(params) {
+        const { getRedelegationRecordPDA } = await import('./pda.js');
+        const [pda] = await getRedelegationRecordPDA(address(params.address), this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            return { redelegationFeeRate: 0, feeResetTimestamp: 0 };
+        }
+        const record = deserializeRedelegationRecord(Buffer.from(account.data));
+        const now = Math.floor(Date.now() / 1000);
+        if (now >= record.feeResetAt) {
+            return { redelegationFeeRate: 0, feeResetTimestamp: record.feeResetAt };
+        }
+        const feeRate = Math.min(record.redelegationCount * 10, 60);
+        return {
+            redelegationFeeRate: feeRate,
+            feeResetTimestamp: record.feeResetAt,
+        };
+    }
+    // =========================================
+    // Gateway registry settings
+    // =========================================
+    async getGatewayRegistrySettings() {
+        const [pda] = await getGarSettingsPDA(this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists) {
+            throw new Error('GarSettings account not found');
+        }
+        return deserializeGarSettings(Buffer.from(account.data));
+    }
+    // =========================================
+    // Aggregate queries
+    // =========================================
+    async getAllDelegates(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const del = deserializeDelegation(data);
+                items.push({
+                    address: del.delegator,
+                    gatewayAddress: del.gateway,
+                    delegatedStake: del.delegatedStake,
+                    startTimestamp: secToMs(del.startTimestamp),
+                    vaultedStake: 0,
+                    cursorId: pubkey,
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    async getAllGatewayVaults(params) {
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const w = deserializeWithdrawal(data);
+                items.push({
+                    cursorId: pubkey,
+                    vaultId: w.vaultId,
+                    balance: w.balance,
+                    startTimestamp: secToMs(w.startTimestamp),
+                    endTimestamp: secToMs(w.endTimestamp),
+                    gatewayAddress: w.gateway,
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
+    // =========================================
+    // Name resolution (ArNSNameResolver)
+    // =========================================
+    async resolveArNSName({ name }) {
+        const parts = name.split('_');
+        const baseName = parts.length > 1 ? parts[parts.length - 1] : parts[0];
+        const record = await this.getArNSRecord({ name: baseName });
+        // TODO: resolve undername via ANT program when undername !== '@'
+        return {
+            name: baseName,
+            txId: '',
+            type: record.type,
+            processId: record.processId,
+            ttlSeconds: 3600,
+            undernameLimit: record.undernameLimit,
+        };
+    }
+}