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

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>;

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

@@ -0,0 +1,95 @@
+/**
+ * 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 { type Address } from '@solana/kit';
+/** Return shape for every PDA helper: `[pdaAddress, bumpSeed]`. */
+export type Pda = readonly [Address, number];
+/**
+ * Hash a variable-length name for use as PDA seed.
+ * Matches Rust: hash(name.to_lowercase().as_bytes())
+ */
+export declare function hashName(name: string): Buffer;
+export declare function getArioConfigPDA(programId?: Address): Promise<Pda>;
+export declare function getBalancePDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getVaultPDA(owner: Address, vaultId: bigint | number, programId?: Address): Promise<Pda>;
+export declare function getVaultCounterPDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNamePDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNameRequestPDA(initiator: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNameReversePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getGatewayRegistryPDA(programId?: Address): Promise<Pda>;
+export declare function getGarSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getGatewayPDA(operator: Address, programId?: Address): Promise<Pda>;
+export declare function getDelegationPDA(gateway: Address, delegator: Address, programId?: Address): Promise<Pda>;
+export declare function getWithdrawalPDA(owner: Address, withdrawalId: bigint | number, programId?: Address): Promise<Pda>;
+export declare function getWithdrawalCounterPDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getAllowlistPDA(gateway: Address, delegate: Address, programId?: Address): Promise<Pda>;
+export declare function getEpochPDA(epochIndex: number, programId?: Address): Promise<Pda>;
+export declare function getEpochSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getRedelegationRecordPDA(delegator: Address, programId?: Address): Promise<Pda>;
+export declare function getObservationPDA(epochIndex: number, observer: Address, programId?: Address): Promise<Pda>;
+export declare function getObserverLookupPDA(observerAddress: Address, programId?: Address): Promise<Pda>;
+export declare function getArnsRegistryPDA(programId?: Address): Promise<Pda>;
+export declare function getArnsSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getArnsRecordPDA(name: string, programId?: Address): Promise<Pda>;
+/**
+ * Derive ArNS record PDA from a raw 32-byte name hash.
+ * Used when resolving prescribed name hashes from Epoch data.
+ */
+export declare function getArnsRecordPDAFromHash(nameHash: Buffer, programId?: Address): Promise<Pda>;
+export declare function getReservedNamePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getReturnedNamePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getDemandFactorPDA(programId?: Address): Promise<Pda>;
+export declare function getAntConfigPDA(mint: Address, programId?: Address): Promise<Pda>;
+export declare function getAntControllersPDA(mint: Address, programId?: Address): Promise<Pda>;
+export declare function getAntRecordPDA(mint: Address, undername: string, programId?: Address): Promise<Pda>;
+export declare function getAntRecordMetadataPDA(mint: Address, undername: string, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getAclConfigPDA(user: Address, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getAclPagePDA(user: Address, pageIdx: bigint | number, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowAntPDA(antMint: Address, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowTokenPDA(depositor: Address, assetId: Uint8Array, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowVaultPDA(depositor: Address, assetId: Uint8Array, programId?: Address): Promise<Pda>;

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

@@ -0,0 +1,16 @@
+import { type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
+import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
+/**
+ * Build, sign, send, and confirm a transaction in one call.
+ *
+ * The caller supplies the core instructions; a compute-unit-limit instruction
+ * is prepended automatically.
+ */
+export declare function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment, computeUnitLimit, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    instructions: Instruction[];
+    commitment?: Commitment;
+    computeUnitLimit?: number;
+}): Promise<string>;

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

@@ -0,0 +1,130 @@
+/**
+ * Solana implementation of `ANT.spawn`.
+ *
+ * Mints a fresh Metaplex Core asset (the ANT NFT) AND initializes the
+ * `ario-ant` extended state PDAs (`AntConfig`, `AntControllers`, root `@`
+ * record) in a single atomic transaction.
+ *
+ * This is the Solana counterpart to the legacy AO `spawnANT` flow:
+ * - AO: `ao.spawn({ module, scheduler, ... })` → returns AO process id.
+ * - Solana: mint MPL Core asset + initialize ario-ant PDAs → returns the
+ *   asset's pubkey (which serves as the SDK's stable `processId`).
+ *
+ * For the bulk-import flow used by `migration/import` we use a separate
+ * code path that mints to the migration authority and uses the gated
+ * `import_account` instruction — that's intentional and not what this SDK
+ * helper is for.
+ */
+import { type Address, type Commitment, type Instruction, type KeyPairSigner } from '@solana/kit';
+import type { SolanaRpc, SolanaRpcSubscriptions, SolanaSigner } from './types.js';
+/** AR.IO logo Arweave TX — matches the Rust default in `ario_ant::initialize`. */
+export declare const ARIO_LOGO_TX_ID = "AnYvLJTWcG9lr2Ll5MwYWZR2o5uTE39WbpYB0zCxwKM";
+/**
+ * Default Arweave transaction id used when an ANT is spawned without an
+ * explicit `transactionId`. Empty string would fail the on-chain
+ * `is_valid_arweave_id` check, so we fall back to the AR.IO logo TX (which is
+ * a real Arweave id and won't trip validation).
+ */
+export declare const DEFAULT_ANT_TRANSACTION_ID = "AnYvLJTWcG9lr2Ll5MwYWZR2o5uTE39WbpYB0zCxwKM";
+export type SpawnSolanaANTState = {
+    /** ANT display name (1–51 chars). */
+    name: string;
+    /** Optional ticker (defaults to "ANT" on chain). */
+    ticker?: string;
+    /**
+     * Content target for the root `@` record (Arweave TX ID, IPFS CID, etc.).
+     * Defaults to the AR.IO logo TX — callers that want a real pointer should
+     * override this.
+     */
+    transactionId?: string;
+    /**
+     * Storage protocol for the root `@` record target.
+     * 0 = Arweave (default), 1 = IPFS.
+     */
+    targetProtocol?: number;
+    /** Logo TX id (43 chars). Defaults to the AR.IO logo. */
+    logo?: string;
+    /** Description (≤ 512 chars). */
+    description?: string;
+    /** Keywords (≤ 16 entries). */
+    keywords?: string[];
+    /**
+     * Metadata URI baked into the MPL Core asset (`uri` field). Defaults to
+     * `ar://{logo}` — wallets resolve `ar://{txId}` to `https://arweave.net/{txId}`.
+     */
+    uri?: string;
+};
+export type SpawnSolanaANTParams = {
+    /** RPC client used to fetch a recent blockhash + send the spawn transaction. */
+    rpc: SolanaRpc;
+    /** RPC subscriptions client — required to confirm the transaction. */
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    /** Solana signer — pays rent + receives the NFT. */
+    signer: SolanaSigner;
+    /** ANT metadata for the new asset. `name` is the only required field. */
+    state: SpawnSolanaANTState;
+    /** Override the deployed `ario-ant` program id (devnet/localnet only). */
+    antProgramId?: Address;
+    /**
+     * Pre-derived mint signer. Useful for tests that want a deterministic
+     * asset address. When omitted a fresh random keypair signer is generated.
+     */
+    mintSigner?: KeyPairSigner;
+    /** Confirmation commitment for the resulting tx. Defaults to 'confirmed'. */
+    commitment?: Commitment;
+    /** CU limit for the bundled tx. Defaults to 400_000 (matches existing writes). */
+    computeUnitLimit?: number;
+};
+export type SpawnSolanaANTResult = {
+    /**
+     * SDK-canonical ANT identifier on Solana — this is the MPL Core asset's
+     * pubkey (base58). Pass it back into `ANT.init({ backend: 'solana',
+     * processId, ... })` to drive subsequent reads/writes.
+     */
+    processId: string;
+    /** Same value as `processId`, as an `Address` for convenience. */
+    mint: Address;
+    /** Confirmed transaction signature. */
+    signature: string;
+};
+/** A single on-chain `Attributes` plugin entry. */
+export type AntAttribute = {
+    key: string;
+    value: string;
+};
+/**
+ * Public, low-level builder for the `CreateV1` MPL Core instruction with the
+ * AR.IO-standard ANT shape (Attributes plugin pre-installed, Owner authority).
+ *
+ * Delegates to the Codama-generated `getCreateV1Instruction`, but accepts
+ * plain `Address`es (rather than full `TransactionSigner`s) so test fixtures
+ * and devnet validation scripts can byte-pin the wire format without
+ * standing up real keypairs. The signer roles still flow through correctly
+ * because we re-cast under `unknown`.
+ *
+ * Most callers should use `ANT.spawn` / `spawnSolanaANT` instead — that path
+ * also wires up `ario_ant::initialize` so the ANT is fully usable end to end.
+ * Use this raw builder when you need fine-grained control over signing, or
+ * are bundling the mint into a larger compound transaction.
+ *
+ * **Why we always emit an Attributes plugin (even with an empty list):**
+ * `ario_arns::buy_record` and friends CPI into `UpdatePluginV1` to populate
+ * traits at purchase time. If the asset has no Attributes plugin, that CPI
+ * fails. Emitting an empty plugin here keeps every spawned ANT
+ * `purchase`-ready and matches what `migration/import` mints — see ADR-012
+ * and BD-096. Authority is `Owner` so the ANT NFT holder (= asset owner)
+ * can sign their own trait updates.
+ */
+export declare function buildCreateAntInstruction({ mint, authority, payer, name, uri, attributes, }: {
+    mint: Address;
+    authority: Address;
+    payer: Address;
+    name: string;
+    uri: string;
+    attributes?: AntAttribute[];
+}): Instruction;
+/**
+ * Spawn a brand-new ANT on Solana. Returns the asset address, which is the
+ * SDK's stable `processId` for that ANT.
+ */
+export declare function spawnSolanaANT(params: SpawnSolanaANTParams): Promise<SpawnSolanaANTResult>;

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

@@ -0,0 +1,67 @@
+/**
+ * Solana-specific types for the AR.IO SDK.
+ *
+ * These extend the common SDK types with Solana connection and signer config.
+ */
+import { type Address, type Commitment, type Rpc, type RpcSubscriptions, type SolanaRpcApi, type SolanaRpcApiMainnet, type SolanaRpcSubscriptionsApi, type TransactionSigner } from '@solana/kit';
+/**
+ * The Solana RPC client produced by `createSolanaRpc(url)`.
+ *
+ * We accept both the mainnet-safe API (no `requestAirdrop`) and the test-cluster
+ * API (with `requestAirdrop`). kit's `createSolanaRpc` narrows the return type
+ * based on the URL string; this union lets callers pass either shape.
+ */
+export type SolanaRpc = Rpc<SolanaRpcApi> | Rpc<SolanaRpcApiMainnet>;
+/**
+ * The subscriptions client produced by `createSolanaRpcSubscriptions(wsUrl)`.
+ * Required alongside `SolanaRpc` to confirm transactions (via
+ * `sendAndConfirmTransactionFactory`).
+ */
+export type SolanaRpcSubscriptions = RpcSubscriptions<SolanaRpcSubscriptionsApi>;
+/**
+ * A transaction signer in the kit model. Covers keypair-based signers
+ * (`KeyPairSigner`) and any wallet-adapter-compatible signer that implements
+ * the {@link TransactionSigner} interface (partial, modifying, or sending).
+ */
+export type SolanaSigner = TransactionSigner;
+/** Configuration for Solana SDK instances */
+export type SolanaConfig = {
+    rpc: SolanaRpc;
+    /**
+     * Subscriptions client. Required for writeable instances (confirmation).
+     * Optional for readable instances.
+     */
+    rpcSubscriptions?: SolanaRpcSubscriptions;
+    commitment?: Commitment;
+};
+export type SolanaReadConfig = SolanaConfig;
+export type SolanaWriteConfig = SolanaConfig & {
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: SolanaSigner;
+};
+/** Result of a Solana write operation */
+export type SolanaTransactionResult<T = undefined> = {
+    /** Transaction signature (base58) */
+    id: string;
+    result?: T;
+};
+/** Raw account data with metadata */
+export type AccountData<T> = {
+    address: Address;
+    data: T;
+};
+/** Discriminator for Anchor accounts: sha256("account:StructName")[0..8] */
+export type AccountDiscriminator = Uint8Array;
+/**
+ * On Solana, "processId" (AO concept) maps to the ANT's Metaplex Core
+ * asset address. We keep the field name for SDK compatibility.
+ */
+export type SolanaArNSNameData = {
+    processId: string;
+    owner: string;
+    startTimestamp: number;
+    type: 'lease' | 'permabuy';
+    endTimestamp?: number;
+    undernameLimit: number;
+    purchasePrice: number;
+};

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

@@ -21,7 +21,46 @@ export interface AoANTRegistryRead {
         Owned: string[];
         Controlled: string[];
     }>;
+    /**
+     * Alias for `accessControlList` with a clearer name. Returns the ANTs
+     * owned or controlled by the given address. Implemented by both the AO
+     * and Solana backends so consumers can switch backends without renaming
+     * calls.
+     */
+    getAntsForAddress?(params: {
+        address: string;
+    }): Promise<{
+        Owned: string[];
+        Controlled: string[];
+    }>;
 }
+/**
+ * Cross-backend ACL relationship. Both AO and Solana model the same two
+ * roles today (owner / controller); the Solana paginated registry stores
+ * them as a `u8` byte (`ACL_ROLE_*` constants) but the public surface uses
+ * strings so consumers don't have to know the on-chain encoding.
+ */
+export type AclMaintenanceRole = 'owner' | 'controller';
+/**
+ * Mutation we want the on-chain ACL to reflect once the transaction lands.
+ * `user` and `asset` are wallet/process addresses (base58 on Solana, AO
+ * address on AO).
+ *
+ * On the Solana backend this is the input to the registry's internal
+ * preflight planner, surfaced via the workflow helpers
+ * (`bootstrapOwnerOnSpawn`, `bulkRemoveControllerEntries`) — they
+ * translate it into the minimum `register_acl_config` / `add_acl_page`
+ * / `record_acl_*` / `remove_acl_*` instruction set against the
+ * paginated `AclConfig` + `AclPage` layout (see ADR-012). On AO, the
+ * registry process owns its own ACL bookkeeping, so the equivalent is
+ * a no-op.
+ */
+export type AclMaintenanceOp = {
+    action: 'record' | 'remove';
+    role: AclMaintenanceRole;
+    user: string;
+    asset: string;
+};
 export interface AoANTRegistryWrite extends AoANTRegistryRead {
     register(params: {
         processId: string;

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

@@ -33,8 +33,9 @@ export declare const IntegerStringSchema: z.ZodEffects<z.ZodString, string, stri
 export declare const AntDescriptionSchema: z.ZodString;
 export declare const AntKeywordsSchema: z.ZodArray<z.ZodString, "many">;
 export declare const AntRecordSchema: z.ZodObject<{
-    transactionId: z.ZodEffects<z.ZodString, string, string>;
+    transactionId: z.ZodString;
     ttlSeconds: z.ZodNumber;
+    targetProtocol: z.ZodDefault<z.ZodNumber>;
     priority: z.ZodOptional<z.ZodNumber>;
     owner: z.ZodOptional<z.ZodString>;
     displayName: z.ZodOptional<z.ZodString>;
@@ -44,6 +45,7 @@ export declare const AntRecordSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
     ttlSeconds: number;
+    targetProtocol: number;
     description?: string | undefined;
     priority?: number | undefined;
     owner?: string | undefined;
@@ -54,6 +56,7 @@ export declare const AntRecordSchema: z.ZodObject<{
     transactionId: string;
     ttlSeconds: number;
     description?: string | undefined;
+    targetProtocol?: number | undefined;
     priority?: number | undefined;
     owner?: string | undefined;
     displayName?: string | undefined;
@@ -67,8 +70,9 @@ export type SortedANTRecord = AoANTRecord & {
 };
 export type SortedANTRecords = Record<string, SortedANTRecord>;
 export declare const AntRecordsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
-    transactionId: z.ZodEffects<z.ZodString, string, string>;
+    transactionId: z.ZodString;
     ttlSeconds: z.ZodNumber;
+    targetProtocol: z.ZodDefault<z.ZodNumber>;
     priority: z.ZodOptional<z.ZodNumber>;
     owner: z.ZodOptional<z.ZodString>;
     displayName: z.ZodOptional<z.ZodString>;
@@ -78,6 +82,7 @@ export declare const AntRecordsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
     ttlSeconds: number;
+    targetProtocol: number;
     description?: string | undefined;
     priority?: number | undefined;
     owner?: string | undefined;
@@ -88,6 +93,7 @@ export declare const AntRecordsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     transactionId: string;
     ttlSeconds: number;
     description?: string | undefined;
+    targetProtocol?: number | undefined;
     priority?: number | undefined;
     owner?: string | undefined;
     displayName?: string | undefined;
@@ -105,8 +111,9 @@ export declare const AntStateSchema: z.ZodObject<{
     Owner: z.ZodString;
     Controllers: z.ZodArray<z.ZodString, "many">;
     Records: z.ZodRecord<z.ZodString, z.ZodObject<{
-        transactionId: z.ZodEffects<z.ZodString, string, string>;
+        transactionId: z.ZodString;
         ttlSeconds: z.ZodNumber;
+        targetProtocol: z.ZodDefault<z.ZodNumber>;
         priority: z.ZodOptional<z.ZodNumber>;
         owner: z.ZodOptional<z.ZodString>;
         displayName: z.ZodOptional<z.ZodString>;
@@ -116,6 +123,7 @@ export declare const AntStateSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         transactionId: string;
         ttlSeconds: number;
+        targetProtocol: number;
         description?: string | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
@@ -126,6 +134,7 @@ export declare const AntStateSchema: z.ZodObject<{
         transactionId: string;
         ttlSeconds: number;
         description?: string | undefined;
+        targetProtocol?: number | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
         displayName?: string | undefined;
@@ -147,6 +156,7 @@ export declare const AntStateSchema: z.ZodObject<{
     Records: Record<string, {
         transactionId: string;
         ttlSeconds: number;
+        targetProtocol: number;
         description?: string | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
@@ -170,6 +180,7 @@ export declare const AntStateSchema: z.ZodObject<{
         transactionId: string;
         ttlSeconds: number;
         description?: string | undefined;
+        targetProtocol?: number | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
         displayName?: string | undefined;
@@ -207,8 +218,9 @@ export declare const SpawnANTStateSchema: z.ZodObject<{
     owner: z.ZodString;
     controllers: z.ZodArray<z.ZodString, "many">;
     records: z.ZodRecord<z.ZodString, z.ZodObject<{
-        transactionId: z.ZodEffects<z.ZodString, string, string>;
+        transactionId: z.ZodString;
         ttlSeconds: z.ZodNumber;
+        targetProtocol: z.ZodDefault<z.ZodNumber>;
         priority: z.ZodOptional<z.ZodNumber>;
         owner: z.ZodOptional<z.ZodString>;
         displayName: z.ZodOptional<z.ZodString>;
@@ -218,6 +230,7 @@ export declare const SpawnANTStateSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         transactionId: string;
         ttlSeconds: number;
+        targetProtocol: number;
         description?: string | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
@@ -228,6 +241,7 @@ export declare const SpawnANTStateSchema: z.ZodObject<{
         transactionId: string;
         ttlSeconds: number;
         description?: string | undefined;
+        targetProtocol?: number | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
         displayName?: string | undefined;
@@ -247,6 +261,7 @@ export declare const SpawnANTStateSchema: z.ZodObject<{
     records: Record<string, {
         transactionId: string;
         ttlSeconds: number;
+        targetProtocol: number;
         description?: string | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
@@ -267,6 +282,7 @@ export declare const SpawnANTStateSchema: z.ZodObject<{
         transactionId: string;
         ttlSeconds: number;
         description?: string | undefined;
+        targetProtocol?: number | undefined;
         priority?: number | undefined;
         owner?: string | undefined;
         displayName?: string | undefined;
@@ -442,6 +458,8 @@ export interface AoANTWrite extends AoANTRead {
 export type AoANTSetBaseNameRecordParams = {
     transactionId: string;
     ttlSeconds: number;
+    /** Storage protocol: 0 = Arweave, 1 = IPFS. Defaults to 0 (Arweave). */
+    targetProtocol?: number;
     priority?: number;
     owner?: string;
     displayName?: string;

package/lib/types/types/io.d.ts

@@ -312,9 +312,40 @@ export type AoTokenCostParams = {
     quantity?: number;
     fromAddress?: WalletAddress;
 };
-export declare const fundFromOptions: readonly ["balance", "stakes", "any", "turbo"];
+export declare const fundFromOptions: readonly ["balance", "stakes", "withdrawal", "plan", "any", "turbo"];
 export type FundFrom = (typeof fundFromOptions)[number];
 export declare const isValidFundFrom: (fundFrom: string) => fundFrom is FundFrom;
+/**
+ * One entry in a multi-source funding plan. Mirrors the on-chain
+ * `ario_gar::FundingSourceSpec` shape (kind + amount); `gateway` is an
+ * SDK-side hint for explicit (non-discovered) plans so the executor knows
+ * which gateway PDA to slot in for `Delegation` / `OperatorStake` sources.
+ *
+ * Multi-gateway: `Delegation` sources may span up to MAX_DELEGATION_SOURCES
+ * (3) distinct gateways per plan. `Balance` and `Withdrawal` sources are
+ * gateway-independent. Hard cap of MAX_FUNDING_SOURCES (5) total sources
+ * per `pay_from_funding_plan` call.
+ */
+export type FundingSourceKind = 'balance' | 'delegation' | 'operatorStake' | 'withdrawal';
+export type FundingSourceSpec = {
+    kind: FundingSourceKind;
+    /** mARIO amount drawn from this source. Must be > 0. */
+    amount: bigint;
+    /**
+     * Bound gateway (base58). Required for `delegation` / `operatorStake` in
+     * multi-gateway explicit plans; ignored for `balance` / `withdrawal`. When
+     * omitted on stake-locked sources, the executor falls back to
+     * `params.gatewayAddress`.
+     */
+    gateway?: WalletAddress;
+    /**
+     * Withdrawal vault id — required for `kind: 'withdrawal'` in multi-
+     * withdrawal plans. Single-withdrawal plans may omit it and rely on
+     * `params.withdrawalId`. Ignored for non-withdrawal kinds. Client-side
+     * metadata only — does NOT change the on-chain wire format.
+     */
+    withdrawalId?: bigint;
+};
 export type AoGetCostDetailsParams = AoTokenCostParams & {
     fundFrom?: FundFrom;
 };
@@ -348,6 +379,19 @@ export type AoGetVaultParams = {
 };
 export type AoArNSPurchaseParams = AoArNSNameParams & {
     fundFrom?: FundFrom;
+    /** Gateway operator address — required when fundFrom is 'stakes' */
+    gatewayAddress?: WalletAddress;
+    /** If true, fund from operator stake instead of delegation (default: delegation) */
+    fundAsOperator?: boolean;
+    /** Withdrawal vault id — required when fundFrom is 'withdrawal' (Solana only) */
+    withdrawalId?: bigint;
+    /**
+     * Explicit funding plan — when provided AND fundFrom is 'plan' or 'any',
+     * the SDK skips source discovery and uses these sources verbatim. Caller
+     * is responsible for matching `sum(amounts) == cost` and respecting the
+     * single-gateway invariant. Solana only.
+     */
+    sources?: FundingSourceSpec[];
     paidBy?: WalletAddress | WalletAddress[];
     referrer?: string;
 };
@@ -559,6 +603,17 @@ export interface AoARIOWrite extends AoARIORead {
     requestPrimaryName(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult<AoCreatePrimaryNameRequest>>;
     setPrimaryName: AoWriteAction<AoArNSPurchaseParams, AoMessageResult, keyof SetPrimaryNameProgressEvents, SetPrimaryNameProgressEvents[keyof SetPrimaryNameProgressEvents]>;
     redelegateStake: AoWriteAction<AoRedelegateStakeParams>;
+    /**
+     * Reconcile an ANT NFT's on-chain Attributes plugin (`ArNS Name`, `Type`,
+     * `Undername Limit`) with its current `ArnsRecord` state. Permissionless
+     * cache-sync — useful when a `buyRecord`/`reassignName` was performed on
+     * behalf of a different ANT holder, leaving traits unpopulated.
+     *
+     * Solana-only: throws on the AO backend (AO ANTs have no NFT trait surface).
+     */
+    syncAttributes: AoWriteAction<{
+        name: string;
+    }, AoMessageResult>;
 }
 export declare function isProcessConfiguration(config: object | undefined): config is Required<ProcessConfiguration> & Record<string, never>;
 export declare function isProcessIdConfiguration(config: object | undefined): config is Required<ProcessIdConfig> & Record<string, never>;

package/lib/types/version.d.ts

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