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

package/lib/esm/solana/json-rpc.js

@@ -0,0 +1,74 @@
+/**
+ * Helpers for JSON-RPC reads against {@link SolanaRpc} that return a
+ * web3.js-shaped `AccountInfo` (Buffer-backed `data`, plain Address strings).
+ * Used by the ACL/AntRegistry path so the deserializers can stay agnostic of
+ * the RPC client's response shape.
+ */
+import { address } from '@solana/kit';
+/**
+ * Map an arbitrary commitment string to one of kit's three supported tiers.
+ * Anything we don't recognise (or `undefined`) falls back to `confirmed`,
+ * which is the project-wide default for read paths.
+ */
+function toKitCommitment(commitment) {
+    if (commitment === 'finalized' ||
+        commitment === 'confirmed' ||
+        commitment === 'processed') {
+        return commitment;
+    }
+    return 'confirmed';
+}
+/**
+ * Fetch a single account and decode its data into a Buffer-backed shape that
+ * looks like the legacy `web3.js` `AccountInfo`. Returns `null` if the account
+ * doesn't exist (so callers can handle "missing PDA" without try/catch).
+ */
+export async function getAccountInfoLegacy(rpc, pda, commitment) {
+    const res = await rpc
+        .getAccountInfo(pda, {
+        encoding: 'base64',
+        commitment: toKitCommitment(commitment),
+    })
+        .send();
+    if (!res.value)
+        return null;
+    const [dataB64] = res.value.data;
+    return {
+        data: Buffer.from(dataB64, 'base64'),
+        owner: address(res.value.owner),
+        lamports: Number(res.value.lamports),
+        executable: res.value.executable,
+        rentEpoch: 0,
+    };
+}
+/**
+ * Fetch multiple accounts in a single RPC round-trip and decode each into
+ * the legacy `AccountInfo` shape. Missing accounts come back as `null`,
+ * preserving 1:1 alignment with the input `pdas` array.
+ *
+ * Used by paginated readers (ACL pages, etc.) to load all sibling pages
+ * via `getMultipleAccountsInfo` rather than firing N parallel
+ * `getAccountInfo` calls.
+ */
+export async function getMultipleAccountsInfoLegacy(rpc, pdas, commitment) {
+    if (pdas.length === 0)
+        return [];
+    const res = await rpc
+        .getMultipleAccounts(pdas, {
+        encoding: 'base64',
+        commitment: toKitCommitment(commitment),
+    })
+        .send();
+    return res.value.map((acct) => {
+        if (!acct)
+            return null;
+        const [dataB64] = acct.data;
+        return {
+            data: Buffer.from(dataB64, 'base64'),
+            owner: address(acct.owner),
+            lamports: Number(acct.lamports),
+            executable: acct.executable,
+            rentEpoch: 0,
+        };
+    });
+}

package/lib/esm/solana/metadata.js

@@ -0,0 +1,66 @@
+/**
+ * Metaplex-standard JSON metadata builder for AR.IO ANT NFTs.
+ *
+ * The Core asset's `uri` field on chain points at a JSON file with this
+ * shape; marketplaces and DAS providers fetch + parse it for their
+ * inline name/image/description display. The 3 ArNS traits (`ArNS Name`,
+ * `Type`, `Undername Limit`) live in the on-chain Attributes plugin, NOT
+ * in this JSON — see ADR-012.
+ *
+ * This helper produces the exact same JSON shape as the migration import
+ * (`migration/import/src/metadata.ts::buildAntMetadata`); the two paths
+ * MUST stay in lock-step or migrated and freshly-spawned ANTs will
+ * render differently in marketplace UIs. A regression test in
+ * `spawn-ant.test.ts` asserts byte-equality between the two for matching
+ * inputs.
+ *
+ * Pure function. No network, no Turbo, no dependencies. Caller handles
+ * uploading the resulting JSON to Arweave (e.g. via `@ardrive/turbo-sdk`
+ * with a `HexSolanaSigner` — free for files under 100 KiB) and passes the
+ * resulting `ar://${txid}` to `spawnSolanaANT`'s `state.uri`.
+ */
+// Re-export the SDK-canonical AR.IO logo TX ID + ar:// protocol from the
+// shared constants module so this metadata builder stays in lock-step with
+// the rest of the SDK + the migration import package's JSON output.
+export { ARIO_LOGO_TX_ID, AR_IO_PROTOCOL as AR_PROTOCOL, } from '../constants.js';
+import { ARIO_LOGO_TX_ID, AR_IO_PROTOCOL as AR_PROTOCOL, } from '../constants.js';
+function makeUri(txId, gateway) {
+    return gateway ? `https://${gateway}/raw/${txId}` : `${AR_PROTOCOL}${txId}`;
+}
+/**
+ * Build ANT NFT JSON metadata.
+ *
+ * Output is byte-identical to the migration import's `buildAntMetadata`
+ * for matching inputs. Defaults to `ar://` URLs (ADR-012 canonical); pass
+ * `gateway` to opt into https URLs.
+ */
+export function buildAntMetadata(params) {
+    const logoTxId = params.logoTxId || ARIO_LOGO_TX_ID;
+    const ticker = params.ticker || 'ANT';
+    const arnsName = params.arnsName;
+    const gateway = params.gateway;
+    const description = params.description ||
+        (arnsName
+            ? `Arweave Name Token for ${arnsName}.ar.io`
+            : 'Arweave Name Token');
+    const logoUri = makeUri(logoTxId, gateway);
+    const metadata = {
+        name: arnsName || params.name,
+        symbol: ticker,
+        description,
+        image: logoUri,
+        properties: {
+            files: [{ uri: logoUri, type: 'image/png' }],
+            // Metaplex standard categories are image|video|audio|vr|html. The
+            // semantic "this is an ANT for an ArNS domain" is conveyed by the
+            // on-chain Attributes plugin (Type=lease/permabuy), not this JSON.
+            category: 'image',
+        },
+    };
+    if (arnsName) {
+        metadata.external_url = gateway
+            ? `https://${arnsName}.ar.io`
+            : `${AR_PROTOCOL}${arnsName}`;
+    }
+    return metadata;
+}

package/lib/esm/solana/mpl-core.js

@@ -0,0 +1,142 @@
+/**
+ * Reader for the on-chain Metaplex Core asset (`AssetV1` + plugin chain).
+ *
+ * The codama-generated decoders in `generated/mpl-core` only cover the
+ * fixed-shape header section (`AssetV1`, `PluginHeaderV1`, etc.) — they
+ * don't know how to follow the variable-offset registry chain to a
+ * specific plugin payload. This module fills that gap with a small
+ * walker that:
+ *
+ *   1. decodes the `AssetV1` prefix (key + owner + update authority +
+ *      name + uri + seq);
+ *   2. follows the `PluginHeaderV1.pluginRegistryOffset` to the
+ *      `PluginRegistryV1`;
+ *   3. iterates registry records to find the requested plugin variant;
+ *   4. decodes the `Plugin` enum at the registry record's offset.
+ *
+ * The same walk lives on-chain in `programs/ario-arns/src/state/mod.rs`
+ * (`read_mpl_core_attribute`) and `programs/ario-core/src/mpl_core.rs`
+ * (`read_ant_program`). The three implementations are pinned against
+ * each other by the migration import's edge-case fixtures and unit
+ * tests at all three layers.
+ *
+ * Reading is best-effort: any parse failure returns `null` rather than
+ * throwing, so callers can fall back to canonical defaults
+ * (e.g. `ARIO_ANT_PROGRAM_ID`) when an asset was minted without the
+ * `ANT Program` attribute or has a layout the walker doesn't recognise.
+ */
+import { fetchEncodedAccount, } from '@solana/kit';
+import { getAssetV1Decoder } from './generated/mpl-core/accounts/assetV1.js';
+import { getPluginHeaderV1Decoder } from './generated/mpl-core/accounts/pluginHeaderV1.js';
+import { getPluginRegistryV1Decoder } from './generated/mpl-core/accounts/pluginRegistryV1.js';
+import { getPluginDecoder } from './generated/mpl-core/types/plugin.js';
+import { PluginType } from './generated/mpl-core/types/pluginType.js';
+/**
+ * On-chain trait keys. Marketplaces and DAS indexers query these by
+ * exact string match — keep in lock-step with:
+ *   - `migration/import/src/phases/phase2-ants.ts`
+ *   - `programs/ario-arns/src/mpl_core_cpi.rs::TRAIT_KEY_*`
+ *   - `programs/ario-core/src/mpl_core.rs::TRAIT_KEY_ANT_PROGRAM`
+ */
+export const TRAIT_KEY_ARNS_NAME = 'ArNS Name';
+export const TRAIT_KEY_TYPE = 'Type';
+export const TRAIT_KEY_UNDERNAME_LIMIT = 'Undername Limit';
+export const TRAIT_KEY_ANT_PROGRAM = 'ANT Program';
+/**
+ * Read a single attribute value from a Metaplex Core asset's Attributes
+ * plugin. Returns `null` when the asset has no plugin section, has no
+ * Attributes plugin, the requested key is absent, or any layer of the
+ * walk fails to decode. This is a best-effort lookup — callers should
+ * use a canonical default rather than treating absence as an error.
+ *
+ * `data` is the raw account data (post-discriminator? no — MPL Core
+ * doesn't use the 8-byte Anchor discriminator, the asset is the
+ * account's full data starting from the `Key` enum byte).
+ */
+export function readAttribute(data, key) {
+    try {
+        // ── 1. Asset header (variable size — name and uri are length-prefixed).
+        const [, afterAsset] = getAssetV1Decoder().read(data, 0);
+        // No plugin section → no attributes.
+        if (afterAsset >= data.length)
+            return null;
+        // ── 2. PluginHeaderV1: 9 bytes (1-byte key + u64 registry offset).
+        const [pluginHeader] = getPluginHeaderV1Decoder().read(data, afterAsset);
+        const registryOffset = Number(pluginHeader.pluginRegistryOffset);
+        if (registryOffset >= data.length)
+            return null;
+        // ── 3. PluginRegistryV1: list of (pluginType, authority, offset).
+        const [registry] = getPluginRegistryV1Decoder().read(data, registryOffset);
+        for (const record of registry.registry) {
+            // `pluginType` is the kit-decoded numeric `PluginType` enum value
+            // (e.g. `PluginType.Attributes === 6`). The matching `Plugin`
+            // payload at `record.offset` is a discriminated union whose
+            // `__kind` is the string variant name — so we use the numeric
+            // enum here and the string tag below.
+            if (record.pluginType !== PluginType.Attributes)
+                continue;
+            const [plugin] = getPluginDecoder().read(data, Number(record.offset));
+            if (plugin.__kind !== 'Attributes')
+                continue;
+            const attrs = plugin.fields[0].attributeList;
+            const found = attrs.find((a) => a.key === key);
+            return found ? found.value : null;
+        }
+        return null;
+    }
+    catch {
+        // Any decode failure (truncated buffer, unknown plugin variant, etc.)
+        // — treat as "no override" and let the caller fall back.
+        return null;
+    }
+}
+/**
+ * Convenience wrapper: fetch the asset account and parse its
+ * `ANT Program` attribute. Returns `null` when the account doesn't
+ * exist, has no `ANT Program` trait, or the value can't be parsed —
+ * callers should fall back to the canonical `ARIO_ANT_PROGRAM_ID`.
+ *
+ * Importing this here (rather than wiring it directly into the resolver
+ * paths) lets `ant-readable.ts` keep its constructor synchronous and
+ * have a separate async `fromAsset(rpc, mint)` factory that does the
+ * lookup once and caches the result.
+ */
+export async function fetchAntProgramFromAsset(rpc, mint, config) {
+    const account = await fetchEncodedAccount(rpc, mint, config);
+    if (!account.exists)
+        return null;
+    const value = readAttribute(account.data, TRAIT_KEY_ANT_PROGRAM);
+    if (value === null)
+        return null;
+    // The ANT Program attribute is a base58-encoded program address.
+    // We don't validate length here — the kit `Address` brand is
+    // structural and downstream `getProgramDerivedAddress` will reject
+    // malformed values. Returning `null` on missing keeps the call site
+    // simple ("found a value or didn't"); a malformed value is a holder
+    // self-grief that surfaces at the next PDA derivation.
+    return value;
+}
+/**
+ * Fetch the current owner of an MPL Core asset. Returns `null` when the
+ * account doesn't exist or the AssetV1 layout can't be decoded.
+ *
+ * Used by `SolanaARIOWriteable` to decide whether to bundle
+ * `ant.sync_attributes` into a buy / manage tx. The Attributes plugin's
+ * `BasePluginAuthority` is `Owner`, so only the current asset holder
+ * can sign the inner CPI; if the caller isn't the holder, bundling
+ * would abort the whole tx (BD-095 — non-holder ArNS lease management
+ * must continue to succeed; the actual ANT owner can call the public
+ * `syncAttributes` later to converge state).
+ */
+export async function fetchMplCoreOwner(rpc, mint, config) {
+    const account = await fetchEncodedAccount(rpc, mint, config);
+    if (!account.exists)
+        return null;
+    try {
+        const [asset] = getAssetV1Decoder().read(account.data, 0);
+        return asset.owner;
+    }
+    catch {
+        return null;
+    }
+}

package/lib/esm/solana/pda.js

@@ -0,0 +1,317 @@
+import { createHash } from 'crypto';
+/**
+ * PDA derivation helpers for AR.IO Solana programs.
+ *
+ * Each function derives the on-chain address for a given account type,
+ * mirroring the seeds defined in the Anchor programs.
+ *
+ * All helpers are async — kit's `getProgramDerivedAddress` is async because
+ * it may perform bump-seed search off the main thread in some environments.
+ */
+import { getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { ACL_CONFIG_SEED, ACL_PAGE_SEED, ALLOWLIST_SEED, ANT_CONFIG_SEED, ANT_CONTROLLERS_SEED, ANT_RECORD_META_SEED, ANT_RECORD_SEED, ARIO_ANT_ESCROW_PROGRAM_ID, ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CONFIG_SEED, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARNS_RECORD_SEED, ARNS_REGISTRY_SEED, ARNS_SETTINGS_SEED, BALANCE_SEED, DELEGATION_SEED, DEMAND_FACTOR_SEED, EPOCH_SEED, EPOCH_SETTINGS_SEED, ESCROW_ANT_SEED, ESCROW_TOKEN_SEED, ESCROW_VAULT_SEED, GAR_SETTINGS_SEED, GATEWAY_REGISTRY_SEED, GATEWAY_SEED, OBSERVATION_SEED, OBSERVER_LOOKUP_SEED, PRIMARY_NAME_REQUEST_SEED, PRIMARY_NAME_REVERSE_SEED, PRIMARY_NAME_SEED, REDELEGATION_SEED, RESERVED_NAME_SEED, RETURNED_NAME_SEED, VAULT_COUNTER_SEED, VAULT_SEED, WITHDRAWAL_COUNTER_SEED, WITHDRAWAL_SEED, } from './constants.js';
+const addressEncoder = getAddressEncoder();
+/**
+ * Hash a variable-length name for use as PDA seed.
+ * Matches Rust: hash(name.to_lowercase().as_bytes())
+ */
+export function hashName(name) {
+    return createHash('sha256')
+        .update(name.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+}
+// =========================================
+// ario-core PDAs
+// =========================================
+export async function getArioConfigPDA(programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARIO_CONFIG_SEED],
+    });
+}
+export async function getBalancePDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [BALANCE_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getVaultPDA(owner, vaultId, programId = ARIO_CORE_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(vaultId));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [VAULT_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+export async function getVaultCounterPDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [VAULT_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getPrimaryNamePDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getPrimaryNameRequestPDA(initiator, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_REQUEST_SEED, addressEncoder.encode(initiator)],
+    });
+}
+export async function getPrimaryNameReversePDA(name, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_REVERSE_SEED, hashName(name)],
+    });
+}
+// =========================================
+// ario-gar PDAs
+// =========================================
+export async function getGatewayRegistryPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GATEWAY_REGISTRY_SEED],
+    });
+}
+export async function getGarSettingsPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GAR_SETTINGS_SEED],
+    });
+}
+export async function getGatewayPDA(operator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GATEWAY_SEED, addressEncoder.encode(operator)],
+    });
+}
+export async function getDelegationPDA(gateway, delegator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [
+            DELEGATION_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegator),
+        ],
+    });
+}
+export async function getWithdrawalPDA(owner, withdrawalId, programId = ARIO_GAR_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(withdrawalId));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [WITHDRAWAL_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+export async function getWithdrawalCounterPDA(owner, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [WITHDRAWAL_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getAllowlistPDA(gateway, delegate, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [
+            ALLOWLIST_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegate),
+        ],
+    });
+}
+export async function getEpochPDA(epochIndex, programId = ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [EPOCH_SEED, indexBuf],
+    });
+}
+export async function getEpochSettingsPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [EPOCH_SETTINGS_SEED],
+    });
+}
+export async function getRedelegationRecordPDA(delegator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [REDELEGATION_SEED, addressEncoder.encode(delegator)],
+    });
+}
+export async function getObservationPDA(epochIndex, observer, programId = ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [OBSERVATION_SEED, indexBuf, addressEncoder.encode(observer)],
+    });
+}
+export async function getObserverLookupPDA(observerAddress, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [OBSERVER_LOOKUP_SEED, addressEncoder.encode(observerAddress)],
+    });
+}
+// =========================================
+// ario-arns PDAs
+// =========================================
+export async function getArnsRegistryPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_REGISTRY_SEED],
+    });
+}
+export async function getArnsSettingsPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_SETTINGS_SEED],
+    });
+}
+export async function getArnsRecordPDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_RECORD_SEED, hashName(name)],
+    });
+}
+/**
+ * Derive ArNS record PDA from a raw 32-byte name hash.
+ * Used when resolving prescribed name hashes from Epoch data.
+ */
+export async function getArnsRecordPDAFromHash(nameHash, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_RECORD_SEED, nameHash],
+    });
+}
+export async function getReservedNamePDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [RESERVED_NAME_SEED, hashName(name)],
+    });
+}
+export async function getReturnedNamePDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [RETURNED_NAME_SEED, hashName(name)],
+    });
+}
+export async function getDemandFactorPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [DEMAND_FACTOR_SEED],
+    });
+}
+// =========================================
+// ario-ant PDAs
+// =========================================
+export async function getAntConfigPDA(mint, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_CONFIG_SEED, addressEncoder.encode(mint)],
+    });
+}
+export async function getAntControllersPDA(mint, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_CONTROLLERS_SEED, addressEncoder.encode(mint)],
+    });
+}
+export async function getAntRecordPDA(mint, undername, programId = ARIO_ANT_PROGRAM_ID) {
+    const nameHash = createHash('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_RECORD_SEED, addressEncoder.encode(mint), nameHash],
+    });
+}
+export async function getAntRecordMetadataPDA(mint, undername, programId = ARIO_ANT_PROGRAM_ID) {
+    const nameHash = createHash('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_RECORD_META_SEED, addressEncoder.encode(mint), nameHash],
+    });
+}
+/**
+ * Derive the `AclConfig` head PDA for a given wallet address.
+ *
+ * Seeds: `["acl_config", user]` under the ario-ant program.
+ *
+ * See ADR-012 (docs/DECISIONS.md): `AclConfig` is the head record for a
+ * user's paginated ACL. It tracks `page_count` (how many `AclPage` PDAs
+ * exist) and `total_entries` (sum across pages). Frontends point-read
+ * this once, then fan out to each `AclPage` via `getMultipleAccountsInfo`.
+ */
+export async function getAclConfigPDA(user, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ACL_CONFIG_SEED, addressEncoder.encode(user)],
+    });
+}
+/**
+ * Derive an `AclPage` PDA for a given user + page index.
+ *
+ * Seeds: `["acl_page", user, page_idx_le]` where `page_idx_le` is the
+ * 8-byte little-endian encoding of `u64` (matches the contract).
+ *
+ * Each page address is content-derivable from `(user, page_idx)`, so any
+ * single page can be loaded in O(1) without scanning sibling pages.
+ */
+export async function getAclPagePDA(user, pageIdx, programId = ARIO_ANT_PROGRAM_ID) {
+    const idxBuf = Buffer.alloc(8);
+    idxBuf.writeBigUInt64LE(BigInt(pageIdx));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ACL_PAGE_SEED, addressEncoder.encode(user), idxBuf],
+    });
+}
+// =========================================
+// ario-ant-escrow PDAs
+// =========================================
+/**
+ * Derive the EscrowAnt PDA for a given ANT mint. Exactly one escrow per
+ * ANT — re-deriving the address tells you whether an escrow already
+ * exists (look up the account and check `data.length`).
+ *
+ * Seeds: ["escrow_ant", ant_mint]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_ANT_SEED
+ */
+export async function getEscrowAntPDA(antMint, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_ANT_SEED, addressEncoder.encode(antMint)],
+    });
+}
+/**
+ * Derive the EscrowToken PDA for a given depositor and asset ID.
+ *
+ * Seeds: ["escrow_token", depositor, asset_id]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_TOKEN_SEED
+ */
+export async function getEscrowTokenPDA(depositor, assetId, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_TOKEN_SEED, addressEncoder.encode(depositor), assetId],
+    });
+}
+/**
+ * Derive the EscrowVault PDA for a given depositor and asset ID.
+ *
+ * Seeds: ["escrow_vault", depositor, asset_id]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_VAULT_SEED
+ */
+export async function getEscrowVaultPDA(depositor, assetId, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_VAULT_SEED, addressEncoder.encode(depositor), assetId],
+    });
+}