Merge branch 'alpha' into ar-io-ant-update-auth

Author: vilenarios

CHANGELOG.md

@@ -1,3 +1,18 @@
+# [4.1.0-alpha.6](https://github.com/ar-io/ar-io-sdk/compare/v4.1.0-alpha.5...v4.1.0-alpha.6) (2026-07-18)
+
+
+### Bug Fixes
+
+* **solana:** don't let sync_attributes revert the spawned-ANT ACL records ([ba3cd1e](https://github.com/ar-io/ar-io-sdk/commit/ba3cd1e415d0ff712a569e52a9a36765349d21cf))
+* **solana:** route oversized atomic spawn-and-buy through a lookup table ([a929556](https://github.com/ar-io/ar-io-sdk/commit/a92955603d9b34951b5073f25b35aaa3aaf47040))
+
+# [4.1.0-alpha.5](https://github.com/ar-io/ar-io-sdk/compare/v4.1.0-alpha.4...v4.1.0-alpha.5) (2026-07-17)
+
+
+### Features
+
+* **solana:** atomically spawn an ANT during buyRecord when no processId ([35b3dea](https://github.com/ar-io/ar-io-sdk/commit/35b3dea306b6bc3461a25122581f4c13eca07ff0))
+
 # [4.1.0-alpha.4](https://github.com/ar-io/ar-io-sdk/compare/v4.1.0-alpha.3...v4.1.0-alpha.4) (2026-07-02)
 
 

README.md

@@ -1296,7 +1296,7 @@ const delegates = await ario.getAllDelegates({
 
 </details>
 
-### Arweave Name System (ArNS)
+### ar.io Name System (ArNS)
 
 #### `resolveArNSName({ name })`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.1.0-alpha.4",
+  "version": "4.1.0-alpha.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"

src/solana/io-writeable.localnet.test.ts

@@ -41,9 +41,11 @@ import {
 
 import { ANT } from '../common/ant.js';
 import { ARIO } from '../common/io.js';
+import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 import { getAssociatedTokenAddressKit } from './ata.js';
 import { deserializeWithdrawal } from './deserialize.js';
 import { SolanaARIOWriteable } from './io-writeable.js';
+import { fetchMplCoreOwner } from './mpl-core.js';
 import {
   getArioConfigPDA,
   getPrimaryNamePDA,
@@ -342,6 +344,62 @@ describe(
       );
     });
 
+    it('buyRecord without processId spawns a fresh ANT and assigns the name in one tx', async () => {
+      // Hermetic fresh buyer: spawn-and-buy mints a new asset (rent) + pays the
+      // ArNS price, so fund SOL + ARIO up front.
+      const buyer = await freshSigner(scratch, 'spawn-buy');
+      await airdrop(buyer.keypairPath, 5);
+      mintArio(buyer.signer.address, 100_000_000_000n); // 100k ARIO
+
+      const buyerArio = buildArio(buyer.signer, RPC_URL!, WS_URL!);
+      const name = 'spawnbuy' + Date.now().toString(36).slice(-6);
+
+      // No `processId` → the SDK spawns an ANT and assigns the name atomically
+      // in a single [CreateV1, initialize, buy_name] transaction.
+      const result = await buyerArio.buyRecord({
+        name,
+        type: 'lease',
+        years: 1,
+      });
+      assert.ok(result.id, 'spawn-and-buy buyRecord must return a tx id');
+      const spawnedProcessId = result.result?.processId as string | undefined;
+      assert.ok(
+        spawnedProcessId,
+        'buyRecord must surface the spawned ANT processId',
+      );
+
+      // The record points at the freshly-minted ANT — NOT the "no ANT" sentinel.
+      const record = await buyerArio.getArNSRecord({ name });
+      assert.equal(record.processId, spawnedProcessId);
+      assert.notEqual(record.processId, '11111111111111111111111111111111');
+      assert.equal(record.type, 'lease');
+      assert.ok(record.purchasePrice > 0, 'purchasePrice must be > 0');
+
+      // The spawned asset is a real MPL Core NFT owned by the buyer.
+      const rpc = createSolanaRpc(RPC_URL!);
+      const owner = await fetchMplCoreOwner(rpc, address(spawnedProcessId!), {
+        commitment: 'confirmed',
+      });
+      assert.equal(owner?.toLowerCase(), buyer.signer.address.toLowerCase());
+
+      // The deferred follow-up tx bootstrapped the buyer's ACL (owner + controller).
+      const registry = new SolanaANTRegistryReadable({
+        rpc,
+        antProgramId: address(ANT_ID!),
+      });
+      const acl = await registry.accessControlList({
+        address: buyer.signer.address as string,
+      });
+      assert.ok(
+        acl.Owned.includes(spawnedProcessId!),
+        'spawned ANT must appear in the owner ACL after the follow-up tx',
+      );
+      assert.ok(
+        acl.Controlled.includes(spawnedProcessId!),
+        'spawned ANT must appear in the controller ACL after the follow-up tx',
+      );
+    });
+
     it('buyRecord({ fundFrom: "stakes", fundAsOperator: false }) deducts from delegation', async () => {
       // Fresh delegator signer
       const delegator = await freshSigner(scratch, 'delegator');

src/solana/io-writeable.ts

@@ -38,6 +38,7 @@ import {
   AccountRole,
   type Address,
   type Instruction,
+  type KeyPairSigner,
   address,
   appendTransactionMessageInstructions,
   compileTransaction,
@@ -204,6 +205,7 @@ import {
   getUpdateObserverAddressInstructionAsync,
 } from '@ar.io/solana-contracts/gar';
 import { getTransferCheckedInstruction } from '@solana-program/token';
+import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import {
@@ -239,10 +241,13 @@ import {
 } from './predict-prescribed-observers.js';
 import {
   DEFAULT_COMPUTE_UNIT_LIMIT,
+  MAX_TX_SIZE_BYTES,
+  estimateCompiledTxSize,
   reclaimLookupTablesForSigner,
   sendAndConfirm,
   sendWithEphemeralLookupTable,
 } from './send.js';
+import { buildSpawnAntInstructions } from './spawn-ant.js';
 import type {
   SolanaRpcSubscriptions,
   SolanaSigner,
@@ -430,6 +435,47 @@ export function encodeReportTxId(reportTxId: string | undefined): Buffer {
  * `compound-crank.test.ts` asserts this invariant against the live constant.
  */
 export const MAX_COMPOUND_BATCH = 6;
+/**
+ * CU ceiling for the atomic spawn-and-buy tx (`[CreateV1, initialize,
+ * buy_name]`). buy_name CPIs into MPL Core `UpdatePluginV1` on top of the MPL
+ * Core mint + ario-ant initialize, so it needs more headroom than a plain
+ * buy (`DEFAULT_COMPUTE_UNIT_LIMIT`). Keypair signers auto-size below this from
+ * a pre-send simulation; message-modifying wallets keep this generous ceiling.
+ */
+const SPAWN_AND_BUY_COMPUTE_UNIT_LIMIT = 800_000;
+/**
+ * Collect the account addresses in `instructions` that are safe to serve from
+ * an Address Lookup Table: every account meta EXCEPT signers (which must remain
+ * in the static keys) and the invoked top-level program ids (a program invoked
+ * by an instruction cannot be loaded from an ALT). `alwaysInline` pins extra
+ * addresses static — the fee payer and any bundled mint signer. CPI-target
+ * programs that appear only as account metas (e.g. system, token) ARE eligible.
+ * Deduped; order-independent.
+ */
+function altEligibleAddresses(
+  instructions: Instruction[],
+  alwaysInline: Address[],
+): Address[] {
+  const inline = new Set<string>(alwaysInline as string[]);
+  for (const ix of instructions) {
+    inline.add(ix.programAddress);
+    for (const acc of ix.accounts ?? []) {
+      if (
+        acc.role === AccountRole.READONLY_SIGNER ||
+        acc.role === AccountRole.WRITABLE_SIGNER
+      ) {
+        inline.add(acc.address);
+      }
+    }
+  }
+  const eligible = new Set<Address>();
+  for (const ix of instructions) {
+    for (const acc of ix.accounts ?? []) {
+      if (!inline.has(acc.address)) eligible.add(acc.address);
+    }
+  }
+  return [...eligible];
+}
 /** Observation PDAs closed per tx before close_epoch (each ix carries Epoch +
  *  Observation + payer + system accounts — keep well under the tx account cap). */
 const MAX_CLOSE_OBSERVATION_BATCH = 8;
@@ -579,6 +625,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
   protected async sendTransaction(
     instructions: Instruction[],
     computeUnitLimit = DEFAULT_COMPUTE_UNIT_LIMIT,
+    extraSigners: KeyPairSigner[] = [],
   ): Promise<string> {
     return sendAndConfirm({
       rpc: this.rpc,
@@ -587,6 +634,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
       instructions,
       commitment: this.commitment,
       computeUnitLimit,
+      extraSigners,
     });
   }
 
@@ -1449,9 +1497,31 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
       arnsConfig.mint,
       this.signer.address,
     );
-    const antPubkey = address(
-      params.processId ?? ('11111111111111111111111111111111' as Address),
-    );
+
+    // When no ANT (`processId`) is supplied, atomically spawn a fresh ANT and
+    // assign the name to it in the SAME transaction. `buy_name` CPIs into the
+    // new asset's Attributes plugin to write the ArNS traits — instructions
+    // execute in order, so the asset (minted by the prepended `CreateV1`)
+    // exists by the time `buy_name` runs. The owner's ACL registry bootstrap +
+    // trait sync are deferred to a follow-up tx to keep this one under the
+    // 1232-byte transaction-size limit (neither needs to be atomic with the
+    // purchase). See `_bootstrapSpawnedAntAcl`.
+    let spawnIxs: Instruction[] = [];
+    let mintSigner: KeyPairSigner | undefined;
+    let antPubkey: Address;
+    if (params.processId === undefined) {
+      const spawn = await buildSpawnAntInstructions({
+        signer: this.signer,
+        state: { name: params.name },
+        antProgramId: this.antProgram,
+      });
+      spawnIxs = spawn.instructions;
+      mintSigner = spawn.mintSigner;
+      antPubkey = spawn.mint;
+    } else {
+      antPubkey = address(params.processId);
+    }
+
     const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
     const [reservedNameCheck] = await getReservedNamePDA(
       params.name,
@@ -1583,6 +1653,56 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
       );
     }
 
+    // Spawn-and-buy: prepend `[CreateV1, initialize]` and attach the mint
+    // signer. We DON'T bundle `sync_attributes` here — the asset doesn't exist
+    // on-chain at SDK build time (it's minted in THIS tx), so the owner check
+    // in `_buildSyncAttributesIxIfOwner` would 404. The ACL bootstrap + trait
+    // sync run in a separate follow-up tx (`buy_name` already populated the
+    // asset's traits via CPI, so the deferred sync just mirrors them into the
+    // ANT's on-chain record).
+    if (mintSigner !== undefined) {
+      const spawnAndBuyIxs = [...spawnIxs, ix];
+      // Balance/credit-funded spawn-and-buy fits inline (~1.1 KB) and lands in
+      // ONE signature. But a multi-source funding plan appends per-source
+      // remaining accounts to `buy_name` (~33 bytes each) and can blow past
+      // Solana's 1232-byte limit. When that happens, route the whole
+      // spawn-and-buy through an ephemeral Address Lookup Table (create →
+      // extend → compressed v0 tx), compressing every non-signer,
+      // non-invoked-program account. The mint stays inline (it's a signer).
+      const inlineSize = estimateCompiledTxSize({
+        signer: this.signer,
+        instructions: spawnAndBuyIxs,
+        extraSigners: [mintSigner],
+        computeUnitLimit: SPAWN_AND_BUY_COMPUTE_UNIT_LIMIT,
+      });
+      let sig: string;
+      if (inlineSize <= MAX_TX_SIZE_BYTES) {
+        sig = await this.sendTransaction(
+          spawnAndBuyIxs,
+          SPAWN_AND_BUY_COMPUTE_UNIT_LIMIT,
+          [mintSigner],
+        );
+      } else {
+        sig = await sendWithEphemeralLookupTable({
+          rpc: this.rpc,
+          rpcSubscriptions: this.rpcSubscriptions,
+          signer: this.signer,
+          instructions: spawnAndBuyIxs,
+          lookupAddresses: altEligibleAddresses(spawnAndBuyIxs, [
+            this.signer.address,
+            mintSigner.address,
+          ]),
+          commitment: this.commitment,
+          computeUnitLimit: SPAWN_AND_BUY_COMPUTE_UNIT_LIMIT,
+          extraSigners: [mintSigner],
+        });
+      }
+      await this._bootstrapSpawnedAntAcl(antPubkey, params.name);
+      // Surface the freshly-minted ANT's id so callers don't have to re-fetch
+      // the record to discover which asset the name was assigned to.
+      return { id: sig, result: { processId: antPubkey as string } };
+    }
+
     // Sprint 4 / ADR-016: bundle `ant.sync_attributes` IFF the buyer
     // owns the ANT (preserves BD-096 — non-holder buys defer the trait
     // sync to a later `syncAttributes()` call by the actual owner).
@@ -1597,6 +1717,74 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     return { id: sig };
   }
 
+  /**
+   * Post-spawn housekeeping for the atomic spawn-and-buy path: bootstrap the
+   * new owner's paginated ACL registry entries (so "ANTs I own / control"
+   * lookups resolve) and sync the ANT's on-chain record from the asset's
+   * Attributes plugin (which `buy_name` populated via CPI). Sent as a SEPARATE
+   * transaction because bundling it with `[create, initialize, buy_name]`
+   * would overflow the 1232-byte transaction-size limit — and neither step
+   * needs to be atomic with the purchase.
+   *
+   * Best-effort: the name purchase + ANT mint already confirmed in the prior
+   * tx, so a failure here is logged rather than thrown. The owner can reconcile
+   * later via the sync-ACL API and `syncAttributes()`.
+   */
+  private async _bootstrapSpawnedAntAcl(
+    asset: Address,
+    name: string,
+  ): Promise<void> {
+    // Record the owner/controller ACL entries FIRST, in their OWN transaction.
+    // This is the ownership-critical step — the app-side drift detection treats
+    // a missing ACL owner entry as "needs ownership sync". It must NOT be
+    // bundled with `sync_attributes`: if that instruction reverts (e.g. an ANT
+    // program build whose `sync_attributes` enforces an `ant_authority` PDA the
+    // client doesn't yet derive), an atomic bundle would roll the ACL records
+    // back too, silently un-recording ownership.
+    try {
+      const registry = new SolanaANTRegistryWriteable({
+        rpc: this.rpc,
+        signer: this.signer,
+        commitment: this.commitment,
+        antProgramId: this.antProgram,
+        logger: this.logger,
+      });
+      const aclIxs = await registry.bootstrapOwnerOnSpawn({
+        owner: this.signer.address,
+        asset,
+      });
+      if (aclIxs.length > 0) {
+        await this.sendTransaction(aclIxs);
+      }
+    } catch (err) {
+      this.logger.warn(
+        `[buyRecord] spawned ANT ${asset} for "${name}" but ACL owner/controller ` +
+          `bootstrap failed; reconcile via the sync-ACL API. Purchase + mint ` +
+          `already confirmed.`,
+        err,
+      );
+    }
+
+    // Mirror the asset's Attributes plugin (populated by `buy_name`'s CPI) into
+    // the ANT's on-chain record. Best-effort and INDEPENDENT of the ACL step
+    // above — a failure here (e.g. a program/client version skew on
+    // `sync_attributes`) must not undo the ownership records. Reconcilable later
+    // via the public `syncAttributes()`.
+    try {
+      const syncIx = await this._buildSyncAttributesIxIfOwner(name, asset);
+      if (syncIx) {
+        await this.sendTransaction([syncIx]);
+      }
+    } catch (err) {
+      this.logger.warn(
+        `[buyRecord] spawned ANT ${asset} for "${name}": ACL recorded, but ` +
+          `sync_attributes failed; ANT record traits will reconcile on a later ` +
+          `syncAttributes() call.`,
+        err,
+      );
+    }
+  }
+
   /**
    * Resolve a `FundingPlan` for a fee-paying ArNS ix. When `params.sources`
    * is set, use it verbatim (caller-supplied plan); otherwise discover the
@@ -3810,7 +3998,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         rpc: this.rpc,
         rpcSubscriptions: this.rpcSubscriptions,
         signer: this.signer,
-        instruction: fullIx,
+        instructions: [fullIx],
         lookupAddresses: remaining.map((a) => a.address),
         commitment: this.commitment,
         computeUnitLimit: 1_000_000,