@ar.io/sdk 3.24.0 → 4.0.0-alpha.2

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

@@ -0,0 +1,145 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 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,82 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 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

@@ -13,17 +13,56 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AoMessageResult } from './common.js';
-export interface AoANTRegistryRead {
+import { MessageResult } from './common.js';
+export interface ANTRegistryRead {
     accessControlList(params: {
         address: string;
     }): Promise<{
         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[];
+    }>;
 }
-export interface AoANTRegistryWrite extends AoANTRegistryRead {
+/**
+ * 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 ANTRegistryWrite extends ANTRegistryRead {
     register(params: {
         processId: string;
-    }): Promise<AoMessageResult>;
+    }): Promise<MessageResult>;
 }