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

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

@@ -0,0 +1,430 @@
+/**
+ * Solana implementation of AoARIOWrite interface.
+ *
+ * Extends SolanaARIOReadable with write operations that build and send
+ * Solana transactions via Codama-generated instruction builders.
+ *
+ * All instruction encoding (discriminators, account ordering, Borsh codecs,
+ * default value resolution for token/system programs) is delegated to the
+ * generated builders in `./generated/{core,gar,arns}/instructions/`. The
+ * builders are derived from the on-chain IDL and stay in sync via codegen.
+ *
+ * This file's job is just to:
+ *   1. Translate the AO-style SDK params into the builder's input shape.
+ *   2. Pre-derive the PDAs that the *Async builders can't infer (the ones
+ *      whose seeds depend on runtime state — e.g. the next withdrawal id
+ *      from the on-chain counter, or the buyer's ATA from a runtime mint).
+ *   3. Append remaining_accounts (gateway PDAs, name registry) for the
+ *      epoch crank instructions, since Codama doesn't generate a typed
+ *      surface for them.
+ */
+import { type Address, type Instruction } from '@solana/kit';
+import type { ILogger } from '../common/logger.js';
+import type { AoMessageResult, WriteOptions } from '../types/common.js';
+import type { AoArNSPurchaseParams, AoBuyRecordParams, AoCreateVaultParams, AoDelegateStakeParams, AoExtendLeaseParams, AoExtendVaultParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoRedelegateStakeParams, AoRevokeVaultParams, AoUpdateGatewaySettingsParams, AoVaultedTransferParams } from '../types/io.js';
+import type { mARIOToken } from '../types/token.js';
+import { SolanaARIOReadable } from './io-readable.js';
+import type { SolanaRpcSubscriptions, SolanaSigner, SolanaWriteConfig } from './types.js';
+/**
+ * Split a primary name into its undername + base parts using the same rule
+ * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:
+ * everything before the first '_' is the undername, the rest is the base.
+ *
+ * Exposed as a top-level helper so it can be unit-tested without spinning up
+ * an `SolanaARIOWriteable`. Lowercases the input to match contract behavior.
+ */
+export declare function splitPrimaryName(name: string): {
+    isUndername: boolean;
+    baseName: string;
+    undername: string | null;
+};
+/**
+ * Solana-backed read-write client for the AR.IO protocol.
+ *
+ * Usage:
+ * ```ts
+ * import {
+ *   createSolanaRpc,
+ *   createSolanaRpcSubscriptions,
+ *   generateKeyPairSigner,
+ * } from '@solana/kit';
+ * import { SolanaARIOWriteable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const rpcSubscriptions = createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com');
+ * const signer = await generateKeyPairSigner();
+ * const ario = new SolanaARIOWriteable({ rpc, rpcSubscriptions, signer });
+ *
+ * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
+ * ```
+ */
+export declare class SolanaARIOWriteable extends SolanaARIOReadable {
+    protected readonly signer: SolanaSigner;
+    protected readonly rpcSubscriptions: SolanaRpcSubscriptions;
+    constructor(config: SolanaWriteConfig & {
+        logger?: ILogger;
+        coreProgramId?: Address;
+        garProgramId?: Address;
+        arnsProgramId?: Address;
+        antProgramId?: Address;
+    });
+    /** The signer's on-chain address. */
+    protected get signerAddress(): Address;
+    protected sendTransaction(instructions: Instruction[], computeUnitLimit?: number): Promise<string>;
+    /** Helper to get the ARIO mint and treasury from ArioConfig */
+    private getCoreConfig;
+    private getMint;
+    /** Helper to get ArNS config fields (mint and treasury) */
+    private getArnsConfig;
+    /** Helper to get GAR config fields (mint, stake pool, protocol pool) */
+    private getGarConfig;
+    /**
+     * Inject ARNS default PDAs (config, demandFactor, nameRegistry).
+     *
+     * Extra fields not consumed by a given builder are harmlessly ignored
+     * (codama only reads the named keys from `input`).
+     */
+    private withArnsDefaults;
+    /** Inject ARIO core default PDAs (config). */
+    private withCoreDefaults;
+    /** Inject GAR default PDAs (settings, epochSettings, registry). */
+    private withGarDefaults;
+    /** Read WithdrawalCounter's next_id (returns 0n if not yet created) */
+    private getNextWithdrawalId;
+    transfer(params: {
+        target: string;
+        qty: number | mARIOToken;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    vaultedTransfer(params: AoVaultedTransferParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    createVault(params: AoCreateVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Read VaultCounter's next_id (returns 0n if not yet created). */
+    private getNextVaultId;
+    extendVault(params: AoExtendVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    increaseVault(params: AoIncreaseVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    revokeVault(params: AoRevokeVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    joinNetwork(params: AoJoinNetworkParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    leaveNetwork(_options?: WriteOptions): Promise<AoMessageResult>;
+    updateGatewaySettings(params: AoUpdateGatewaySettingsParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    increaseOperatorStake(params: {
+        increaseQty: number | mARIOToken;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    decreaseOperatorStake(params: {
+        decreaseQty: number | mARIOToken;
+        instant?: boolean;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    delegateStake(params: AoDelegateStakeParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    decreaseDelegateStake(params: {
+        target: string;
+        decreaseQty: number | mARIOToken;
+        instant?: boolean;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    instantWithdrawal(params: {
+        gatewayAddress?: string;
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    cancelWithdrawal(params: {
+        gatewayAddress?: string;
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    saveObservations(params: {
+        reportTxId: string;
+        failedGateways: string[];
+        epochIndex?: number;
+        /** Raw 256-byte gateway results bitfield (if provided, overrides failedGateways) */
+        gatewayResults?: Uint8Array;
+        gatewayCount?: number;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    redelegateStake(params: AoRedelegateStakeParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    buyRecord(params: AoBuyRecordParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Resolve a `FundingPlan` for a fee-paying ArNS ix. When `params.sources`
+     * is set, use it verbatim (caller-supplied plan); otherwise discover the
+     * user's sources and build a plan via the Lua-faithful planner.
+     *
+     * Throws `InsufficientFundingError` (as a thrown Error with the structured
+     * payload as `cause`) when no plan covers `amountNeeded`.
+     */
+    private _resolveFundingPlan;
+    /**
+     * Build a `buy_name_from_funding_plan` ix using the funding-plan module.
+     * Resolves per-source PDAs (Delegation, Withdrawal) and the residue-vault
+     * PDA prediction in one shot.
+     */
+    private _buildBuyNameFromFundingPlanIx;
+    /**
+     * For an explicit caller-supplied plan, detect which Delegation sources
+     * will trigger an on-chain residue auto-vault. Reads each (Delegation,
+     * Gateway) pair in parallel; computes post-drain; flags `(0, min)`.
+     *
+     * Hard-fails on RPC error or missing PDA — silently skipping would let
+     * the on-chain handler reject the tx with `MissingResidueVault` and
+     * burn fees. The error message points at remediation.
+     */
+    private _detectResidueIndexes;
+    /**
+     * Materialize a `FundingPlan` into the on-chain ix's per-source remaining
+     * accounts, residue-vault PDAs, and the withdrawal_counter slot. Shared
+     * across all 5 ArNS funding-plan ix dispatches and the 2 ario-core
+     * primary-name funding-plan dispatches.
+     *
+     * Throws when the plan has Withdrawal sources whose ids cannot be
+     * resolved from either `spec.withdrawalId` (preferred) or
+     * `params.withdrawalId` (single-withdrawal back-compat).
+     */
+    private _materializeFundingPlan;
+    /**
+     * Best-effort cost estimation for `buy_name`. Reads the live DemandFactor
+     * + ArnsConfig and applies the on-chain pricing math. Used by the funding-
+     * plan path so callers don't have to compute cost client-side.
+     *
+     * The estimate may be 1-2 mARIO higher than the actual on-chain cost when a
+     * demand-factor period rolls during the tx; the on-chain handler reads the
+     * live demand-factor and verifies sum(sources) == cost, so an overestimate
+     * fails fast with `FundingPlanAmountMismatch`. Callers should retry with a
+     * fresh estimate on that error.
+     */
+    private _estimateBuyNameCost;
+    private arnsConfigPda;
+    private demandFactorPda;
+    private nameRegistryPda;
+    upgradeRecord(params: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    syncAttributes(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Build a `sync_attributes` instruction for `name` IFF the signer is
+     * the current MPL Core asset owner. Returns `null` otherwise.
+     *
+     * Sprint 4 / ADR-016: bundle helper for `buyRecord`, `upgradeRecord`,
+     * `increaseUndernameLimit`, `reassignName`, and `buyReturnedName`.
+     * Returning `null` lets the caller send the arns ix alone — preserves
+     * BD-095 (non-holder ArNS lease management) and BD-096 (deferred
+     * trait sync for non-holder buyers). The actual ANT owner reconciles
+     * state later via the public `syncAttributes()`.
+     *
+     * `extendLease` is NOT a caller of this helper — extend_lease changes
+     * only `end_timestamp`, which isn't mirrored in any Attributes-plugin
+     * trait (BD-095 last row). `releaseName` is also excluded — release_name
+     * closes the ArnsRecord PDA, so a follow-up `sync_attributes` would
+     * fail the PDA-existence check.
+     *
+     * `assetOverride` MUST be set when the bundling ix mutates
+     * `record.ant` mid-tx (i.e. `reassign_name`). The on-chain record
+     * still points at the OLD asset at SDK build time, so without the
+     * override the bundled sync would target the wrong asset and fail
+     * the post-reassign `record.ant == asset.key()` check. The owner
+     * check runs against the supplied asset (= new ANT for reassign),
+     * matching the pre-reshape "new owner reconciles later" semantic.
+     */
+    private _buildSyncAttributesIxIfOwner;
+    /**
+     * Build a `sync_attributes` instruction unconditionally (no owner
+     * check). Used by the public `syncAttributes()` method, where the
+     * caller is asking explicitly — if they aren't the owner the chain
+     * returns NotNftHolder.
+     */
+    private _buildSyncAttributesIxUnconditional;
+    /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
+    private _buildSyncAttributesIxFor;
+    extendLease(params: AoExtendLeaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Shared dispatch helper for the 3 manage variants (upgrade / extend /
+     * increaseUndername). They share the same account shape per the
+     * `manage_from_delegation_accounts!` / `manage_from_operator_stake_accounts!`
+     * macros in `programs/ario-arns/src/instructions/manage_from_stake.rs`.
+     * Only the operation-specific extra args differ (years for extend,
+     * quantity for increaseUndername).
+     */
+    private _buildManageStakeIx;
+    /**
+     * Cost estimate for manage operations (upgrade / extend / increaseUndername).
+     * Reads the live DemandFactor account + applies the on-chain pricing math.
+     */
+    private _estimateManageStakeCost;
+    /**
+     * Build the `remaining_accounts` slice + the `antProgramId` arg the
+     * four ario-core primary-name instructions consume. Sprint 2/5
+     * reshape (ADR-016): ario-core no longer reads MPL Core asset bytes.
+     * Authorization is "caller is the AntRecord.owner for this name" via
+     * PDA-seed-pinned lookup.
+     *
+     * Layouts the on-chain handlers expect:
+     *   request_primary_name:               [arnsRecord, demandFactor]
+     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord]
+     *   approve_primary_name:               [arnsRecord, antRecord]
+     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@)]
+     *
+     * `antRecord` keys off the undername part for undernames (e.g.
+     * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
+     * for base names. `removeForBaseName` is special — it always uses "@"
+     * regardless of whether the primary name being removed is an undername,
+     * since the *base* name owner is the one revoking it.
+     *
+     * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
+     * `ANT Program` Attributes-plugin trait selects which program owns the
+     * AntRecord PDA. Absent / unparseable → canonical fallback. Both the
+     * PDA derivation here and the `ant_program_id` arg the caller passes
+     * to the on-chain ix MUST agree (the handler re-derives and rejects
+     * mismatches).
+     */
+    private _buildPrimaryNameValidationAccounts;
+    requestPrimaryName(params: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    setPrimaryName(params: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Build a `request_primary_name_from_funding_plan` or
+     * `request_and_set_primary_name_from_funding_plan` ix. Forwards both:
+     *   - validation accounts (ArnsRecord + DemandFactor [+ ant_asset
+     *     [+ AntRecord]]) — passed via remaining_accounts at indices
+     *     [0..validation_account_count)
+     *   - per-source PDAs from the funding plan — passed at indices
+     *     [validation_account_count..)
+     *
+     * The on-chain handler (programs/ario-core/src/instructions/primary_name.rs)
+     * splits remaining_accounts at `validation_account_count` and forwards the
+     * funding-source slice to ario-gar's pay_from_funding_plan via CPI.
+     */
+    private _buildPrimaryNameFromFundingPlanIx;
+    private _coreConfigPda;
+    /**
+     * Approve a previously-created primary name request. The signer must be
+     * the AntRecord.owner for the requested name (undername part for
+     * undernames, "@" for base names) — Sprint 2 / ADR-016 reshape.
+     *
+     * Mirrors the on-chain `approve_primary_name` instruction
+     * (`programs/ario-core/src/instructions/primary_name.rs`).
+     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     */
+    approvePrimaryName(params: {
+        initiator: Address;
+        name: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Release tokens from an unlocked vault back to the owner. */
+    releaseVault(params: {
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Close an expired primary name request (permissionless — anyone can call). */
+    closeExpiredRequest(params: {
+        initiator: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Claim tokens from a completed withdrawal (after lock period). */
+    claimWithdrawal(params: {
+        withdrawalId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Claim delegated stake from a gateway that is leaving the network. */
+    claimDelegateFromLeavingGateway(params: {
+        gatewayAddress: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Add an address to the gateway's delegation allowlist. */
+    allowDelegate(params: {
+        delegate: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Remove an address from the gateway's delegation allowlist. */
+    disallowDelegate(params: {
+        delegate: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Enable or disable the delegation allowlist for the gateway. */
+    setAllowlistEnabled(params: {
+        enabled: boolean;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Buy a name from the returned name auction (Dutch auction with premium).
+     *
+     * Phase 4: now dispatches on `params.fundFrom`. Note that for
+     * `buyReturnedName`, only the protocol share funds from the chosen source;
+     * the initiator share is always a direct buyer-ATA → initiator-ATA SPL
+     * transfer (matches the on-chain `_from_*` variant behavior).
+     */
+    buyReturnedName(params: {
+        name: string;
+        type: 'lease' | 'permabuy';
+        years?: number;
+        processId: string;
+    } & Partial<AoArNSPurchaseParams>, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Reassign an ArNS name to a different ANT. */
+    reassignName(params: {
+        name: string;
+        processId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /** Release a permabuy name back to the registry (creates a returned name auction). */
+    releaseName(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Create a new epoch. Permissionless — anyone can call when the next
+     * epoch's start time has arrived.
+     */
+    createEpoch(_options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Tally weights for a batch of gateways. Permissionless — call repeatedly
+     * until all gateways are processed. Pass gateway PDAs as
+     * `gatewayAccounts`; they're appended as `remaining_accounts`.
+     */
+    tallyWeights(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Prescribe observers and names for an epoch. Permissionless — call after
+     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
+     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * prescription leg.
+     */
+    prescribeEpoch(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+        /** Optional NameRegistry account — pass to enable name prescription */
+        nameRegistryAccount?: Address;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Distribute rewards for a completed epoch in batches. Permissionless —
+     * call after epoch ends. Gateway PDAs appended as `remaining_accounts`.
+     */
+    distributeEpoch(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Close an old epoch account and reclaim rent. Permissionless — call after
+     * the epoch is distributed and at least 7 epochs have passed.
+     */
+    closeEpoch(params: {
+        epochIndex: number;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Get gateway PDAs for a batch starting at registryIndex.
+     * Reads the GatewayRegistry and derives PDAs for the next `batchSize`
+     * active gateways.
+     */
+    getRegistryGatewayPDAs(startIndex: number, batchSize: number): Promise<Address[]>;
+    /** Get ALL active gateway PDAs from the registry. */
+    getAllRegistryGatewayPDAs(): Promise<Address[]>;
+    /**
+     * Read the raw epoch account data for cranker state inspection.
+     * Returns null if the epoch account doesn't exist yet.
+     */
+    getEpochRaw(epochIndex: number): Promise<{
+        tallyIndex: number;
+        distributionIndex: number;
+        weightsTallied: number;
+        prescriptionsDone: number;
+        rewardsDistributed: number;
+        activeGatewayCount: number;
+        endTimestamp: number;
+    } | null>;
+    /**
+     * Parse raw epoch account data for cranker-relevant fields.
+     * Offsets match the Rust Epoch zero-copy struct (repr(C)).
+     *
+     * Layout after 8-byte discriminator:
+     *   [8 epoch_index][8 start_ts][8 end_ts][8 total_eligible][8 per_gw]
+     *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
+     *   [4 active_gw_count][4 dist_idx][4 tally_idx]
+     *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 _pad1]
+     *   [6000 failure_counts][1600 prescribed_observers]
+     *   [1600 prescribed_observer_gateways][64 prescribed_names]
+     *   [7 has_observed][5 _pad2]
+     */
+    private fetchEpochRawFields;
+}

package/lib/types/solana/json-rpc.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { type Address } from '@solana/kit';
+import type { SolanaRpc } from './types.js';
+/** Raw account layout used by SDK readers (matches legacy web3 `AccountInfo` fields). */
+export type SolanaAccountInfo = {
+    data: Buffer;
+    owner: Address;
+    lamports: number;
+    executable: boolean;
+    rentEpoch: number;
+};
+/**
+ * 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 declare function getAccountInfoLegacy(rpc: SolanaRpc, pda: Address, commitment: string | undefined): Promise<SolanaAccountInfo | null>;
+/**
+ * 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 declare function getMultipleAccountsInfoLegacy(rpc: SolanaRpc, pdas: Address[], commitment: string | undefined): Promise<(SolanaAccountInfo | null)[]>;

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

@@ -0,0 +1,69 @@
+/**
+ * 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`.
+ */
+export { ARIO_LOGO_TX_ID, AR_IO_PROTOCOL as AR_PROTOCOL, } from '../constants.js';
+/** Metaplex-standard JSON metadata shape. */
+export interface NftMetadataJson {
+    name: string;
+    symbol: string;
+    description: string;
+    image: string;
+    external_url?: string;
+    properties?: {
+        files?: Array<{
+            uri: string;
+            type: string;
+        }>;
+        /** Metaplex standard categories: image | video | audio | vr | html. */
+        category?: string;
+    };
+}
+/** Inputs to `buildAntMetadata`. */
+export interface AntMetadataParams {
+    /** Display name for the NFT — usually the ArNS name when one is set. */
+    name: string;
+    /** ArNS name this ANT controls (if any). When set, becomes the JSON
+     *  `name` and is also used in `external_url`. */
+    arnsName?: string;
+    /** Ticker / symbol. Defaults to "ANT". */
+    ticker?: string;
+    /** Description. Auto-generated from arnsName when omitted. */
+    description?: string;
+    /** Logo TX id (43-char Arweave id). Defaults to the AR.IO logo. */
+    logoTxId?: string;
+    /**
+     * Optional gateway hostname (e.g. `"turbo-gateway.com"` or `"arweave.net"`).
+     * When provided, all Arweave references in the JSON resolve to
+     * `https://${gateway}/raw/${txid}` instead of `ar://${txid}`. Useful when
+     * you need consumers (like Helius DAS or the Metaplex Core explorer) to
+     * fetch the JSON immediately without waiting for Wayfinder-aware
+     * resolution; ADR-012's canonical scheme is still `ar://`.
+     */
+    gateway?: string;
+}
+/**
+ * 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 declare function buildAntMetadata(params: AntMetadataParams): NftMetadataJson;

package/lib/types/solana/mpl-core.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 { type Address, type FetchAccountConfig, type ReadonlyUint8Array, fetchEncodedAccount } from '@solana/kit';
+/**
+ * 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 declare const TRAIT_KEY_ARNS_NAME: "ArNS Name";
+export declare const TRAIT_KEY_TYPE: "Type";
+export declare const TRAIT_KEY_UNDERNAME_LIMIT: "Undername Limit";
+export declare 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 declare function readAttribute(data: Uint8Array | ReadonlyUint8Array, key: string): string | 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 declare function fetchAntProgramFromAsset(rpc: Parameters<typeof fetchEncodedAccount>[0], mint: Address, config?: FetchAccountConfig): Promise<Address | null>;
+/**
+ * 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 declare function fetchMplCoreOwner(rpc: Parameters<typeof fetchEncodedAccount>[0], mint: Address, config?: FetchAccountConfig): Promise<Address | null>;