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

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAccountInfoLegacy = getAccountInfoLegacy;
+exports.getMultipleAccountsInfoLegacy = getMultipleAccountsInfoLegacy;
+/**
+ * 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.
+ */
+const kit_1 = require("@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).
+ */
+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: (0, kit_1.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.
+ */
+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: (0, kit_1.address)(acct.owner),
+            lamports: Number(acct.lamports),
+            executable: acct.executable,
+            rentEpoch: 0,
+        };
+    });
+}

package/lib/cjs/solana/metadata.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AR_PROTOCOL = exports.ARIO_LOGO_TX_ID = void 0;
+exports.buildAntMetadata = buildAntMetadata;
+// 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.
+var constants_js_1 = require("../constants.js");
+Object.defineProperty(exports, "ARIO_LOGO_TX_ID", { enumerable: true, get: function () { return constants_js_1.ARIO_LOGO_TX_ID; } });
+Object.defineProperty(exports, "AR_PROTOCOL", { enumerable: true, get: function () { return constants_js_1.AR_IO_PROTOCOL; } });
+const constants_js_2 = require("../constants.js");
+function makeUri(txId, gateway) {
+    return gateway ? `https://${gateway}/raw/${txId}` : `${constants_js_2.AR_IO_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.
+ */
+function buildAntMetadata(params) {
+    const logoTxId = params.logoTxId || constants_js_2.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`
+            : `${constants_js_2.AR_IO_PROTOCOL}${arnsName}`;
+    }
+    return metadata;
+}

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

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRAIT_KEY_ANT_PROGRAM = exports.TRAIT_KEY_UNDERNAME_LIMIT = exports.TRAIT_KEY_TYPE = exports.TRAIT_KEY_ARNS_NAME = void 0;
+exports.readAttribute = readAttribute;
+exports.fetchAntProgramFromAsset = fetchAntProgramFromAsset;
+exports.fetchMplCoreOwner = fetchMplCoreOwner;
+const kit_1 = require("@solana/kit");
+const assetV1_js_1 = require("./generated/mpl-core/accounts/assetV1.js");
+const pluginHeaderV1_js_1 = require("./generated/mpl-core/accounts/pluginHeaderV1.js");
+const pluginRegistryV1_js_1 = require("./generated/mpl-core/accounts/pluginRegistryV1.js");
+const plugin_js_1 = require("./generated/mpl-core/types/plugin.js");
+const pluginType_js_1 = require("./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`
+ */
+exports.TRAIT_KEY_ARNS_NAME = 'ArNS Name';
+exports.TRAIT_KEY_TYPE = 'Type';
+exports.TRAIT_KEY_UNDERNAME_LIMIT = 'Undername Limit';
+exports.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).
+ */
+function readAttribute(data, key) {
+    try {
+        // ── 1. Asset header (variable size — name and uri are length-prefixed).
+        const [, afterAsset] = (0, assetV1_js_1.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] = (0, pluginHeaderV1_js_1.getPluginHeaderV1Decoder)().read(data, afterAsset);
+        const registryOffset = Number(pluginHeader.pluginRegistryOffset);
+        if (registryOffset >= data.length)
+            return null;
+        // ── 3. PluginRegistryV1: list of (pluginType, authority, offset).
+        const [registry] = (0, pluginRegistryV1_js_1.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_js_1.PluginType.Attributes)
+                continue;
+            const [plugin] = (0, plugin_js_1.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.
+ */
+async function fetchAntProgramFromAsset(rpc, mint, config) {
+    const account = await (0, kit_1.fetchEncodedAccount)(rpc, mint, config);
+    if (!account.exists)
+        return null;
+    const value = readAttribute(account.data, exports.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).
+ */
+async function fetchMplCoreOwner(rpc, mint, config) {
+    const account = await (0, kit_1.fetchEncodedAccount)(rpc, mint, config);
+    if (!account.exists)
+        return null;
+    try {
+        const [asset] = (0, assetV1_js_1.getAssetV1Decoder)().read(account.data, 0);
+        return asset.owner;
+    }
+    catch {
+        return null;
+    }
+}

package/lib/cjs/solana/pda.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashName = hashName;
+exports.getArioConfigPDA = getArioConfigPDA;
+exports.getBalancePDA = getBalancePDA;
+exports.getVaultPDA = getVaultPDA;
+exports.getVaultCounterPDA = getVaultCounterPDA;
+exports.getPrimaryNamePDA = getPrimaryNamePDA;
+exports.getPrimaryNameRequestPDA = getPrimaryNameRequestPDA;
+exports.getPrimaryNameReversePDA = getPrimaryNameReversePDA;
+exports.getGatewayRegistryPDA = getGatewayRegistryPDA;
+exports.getGarSettingsPDA = getGarSettingsPDA;
+exports.getGatewayPDA = getGatewayPDA;
+exports.getDelegationPDA = getDelegationPDA;
+exports.getWithdrawalPDA = getWithdrawalPDA;
+exports.getWithdrawalCounterPDA = getWithdrawalCounterPDA;
+exports.getAllowlistPDA = getAllowlistPDA;
+exports.getEpochPDA = getEpochPDA;
+exports.getEpochSettingsPDA = getEpochSettingsPDA;
+exports.getRedelegationRecordPDA = getRedelegationRecordPDA;
+exports.getObservationPDA = getObservationPDA;
+exports.getObserverLookupPDA = getObserverLookupPDA;
+exports.getArnsRegistryPDA = getArnsRegistryPDA;
+exports.getArnsSettingsPDA = getArnsSettingsPDA;
+exports.getArnsRecordPDA = getArnsRecordPDA;
+exports.getArnsRecordPDAFromHash = getArnsRecordPDAFromHash;
+exports.getReservedNamePDA = getReservedNamePDA;
+exports.getReturnedNamePDA = getReturnedNamePDA;
+exports.getDemandFactorPDA = getDemandFactorPDA;
+exports.getAntConfigPDA = getAntConfigPDA;
+exports.getAntControllersPDA = getAntControllersPDA;
+exports.getAntRecordPDA = getAntRecordPDA;
+exports.getAntRecordMetadataPDA = getAntRecordMetadataPDA;
+exports.getAclConfigPDA = getAclConfigPDA;
+exports.getAclPagePDA = getAclPagePDA;
+exports.getEscrowAntPDA = getEscrowAntPDA;
+exports.getEscrowTokenPDA = getEscrowTokenPDA;
+exports.getEscrowVaultPDA = getEscrowVaultPDA;
+const crypto_1 = require("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.
+ */
+const kit_1 = require("@solana/kit");
+const constants_js_1 = require("./constants.js");
+const addressEncoder = (0, kit_1.getAddressEncoder)();
+/**
+ * Hash a variable-length name for use as PDA seed.
+ * Matches Rust: hash(name.to_lowercase().as_bytes())
+ */
+function hashName(name) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(name.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+}
+// =========================================
+// ario-core PDAs
+// =========================================
+async function getArioConfigPDA(programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ARIO_CONFIG_SEED],
+    });
+}
+async function getBalancePDA(owner, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.BALANCE_SEED, addressEncoder.encode(owner)],
+    });
+}
+async function getVaultPDA(owner, vaultId, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(vaultId));
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.VAULT_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+async function getVaultCounterPDA(owner, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.VAULT_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+async function getPrimaryNamePDA(owner, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.PRIMARY_NAME_SEED, addressEncoder.encode(owner)],
+    });
+}
+async function getPrimaryNameRequestPDA(initiator, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.PRIMARY_NAME_REQUEST_SEED, addressEncoder.encode(initiator)],
+    });
+}
+async function getPrimaryNameReversePDA(name, programId = constants_js_1.ARIO_CORE_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.PRIMARY_NAME_REVERSE_SEED, hashName(name)],
+    });
+}
+// =========================================
+// ario-gar PDAs
+// =========================================
+async function getGatewayRegistryPDA(programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.GATEWAY_REGISTRY_SEED],
+    });
+}
+async function getGarSettingsPDA(programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.GAR_SETTINGS_SEED],
+    });
+}
+async function getGatewayPDA(operator, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.GATEWAY_SEED, addressEncoder.encode(operator)],
+    });
+}
+async function getDelegationPDA(gateway, delegator, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [
+            constants_js_1.DELEGATION_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegator),
+        ],
+    });
+}
+async function getWithdrawalPDA(owner, withdrawalId, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(withdrawalId));
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.WITHDRAWAL_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+async function getWithdrawalCounterPDA(owner, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.WITHDRAWAL_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+async function getAllowlistPDA(gateway, delegate, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [
+            constants_js_1.ALLOWLIST_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegate),
+        ],
+    });
+}
+async function getEpochPDA(epochIndex, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.EPOCH_SEED, indexBuf],
+    });
+}
+async function getEpochSettingsPDA(programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.EPOCH_SETTINGS_SEED],
+    });
+}
+async function getRedelegationRecordPDA(delegator, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.REDELEGATION_SEED, addressEncoder.encode(delegator)],
+    });
+}
+async function getObservationPDA(epochIndex, observer, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.OBSERVATION_SEED, indexBuf, addressEncoder.encode(observer)],
+    });
+}
+async function getObserverLookupPDA(observerAddress, programId = constants_js_1.ARIO_GAR_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.OBSERVER_LOOKUP_SEED, addressEncoder.encode(observerAddress)],
+    });
+}
+// =========================================
+// ario-arns PDAs
+// =========================================
+async function getArnsRegistryPDA(programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ARNS_REGISTRY_SEED],
+    });
+}
+async function getArnsSettingsPDA(programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ARNS_SETTINGS_SEED],
+    });
+}
+async function getArnsRecordPDA(name, programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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.
+ */
+async function getArnsRecordPDAFromHash(nameHash, programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ARNS_RECORD_SEED, nameHash],
+    });
+}
+async function getReservedNamePDA(name, programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.RESERVED_NAME_SEED, hashName(name)],
+    });
+}
+async function getReturnedNamePDA(name, programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.RETURNED_NAME_SEED, hashName(name)],
+    });
+}
+async function getDemandFactorPDA(programId = constants_js_1.ARIO_ARNS_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.DEMAND_FACTOR_SEED],
+    });
+}
+// =========================================
+// ario-ant PDAs
+// =========================================
+async function getAntConfigPDA(mint, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ANT_CONFIG_SEED, addressEncoder.encode(mint)],
+    });
+}
+async function getAntControllersPDA(mint, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ANT_CONTROLLERS_SEED, addressEncoder.encode(mint)],
+    });
+}
+async function getAntRecordPDA(mint, undername, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    const nameHash = (0, crypto_1.createHash)('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ANT_RECORD_SEED, addressEncoder.encode(mint), nameHash],
+    });
+}
+async function getAntRecordMetadataPDA(mint, undername, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    const nameHash = (0, crypto_1.createHash)('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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`.
+ */
+async function getAclConfigPDA(user, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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.
+ */
+async function getAclPagePDA(user, pageIdx, programId = constants_js_1.ARIO_ANT_PROGRAM_ID) {
+    const idxBuf = Buffer.alloc(8);
+    idxBuf.writeBigUInt64LE(BigInt(pageIdx));
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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
+ */
+async function getEscrowAntPDA(antMint, programId = constants_js_1.ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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
+ */
+async function getEscrowTokenPDA(depositor, assetId, programId = constants_js_1.ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.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
+ */
+async function getEscrowVaultPDA(depositor, assetId, programId = constants_js_1.ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return (0, kit_1.getProgramDerivedAddress)({
+        programAddress: programId,
+        seeds: [constants_js_1.ESCROW_VAULT_SEED, addressEncoder.encode(depositor), assetId],
+    });
+}