Merge pull request #721 from ar-io/feat/spawn-ant-owner-distinct-from-payer

feat(solana): allow a spawned ANT's owner to differ from the payer

Author: vilenarios

src/solana/index.ts

@@ -142,13 +142,26 @@ export type {
   EscrowNetwork,
 } from './canonical-message.js';
 
-// ANT spawn (mint MPL Core asset + initialize ario-ant state in one tx)
+// ANT spawn (mint MPL Core asset + initialize ario-ant state in one tx).
+//
+// `buildSpawnAntInstructions` / `buildCreateAntInstruction` are exported for
+// callers who need to bundle a spawn into a larger transaction rather than send
+// it — notably a SPONSORED spawn, where one wallet pays and another owns. Both
+// were already public within the module and documented as such; without the
+// re-export, a consumer wanting that shape has to hand-copy the `CreateV1`
+// builder, and a copy silently drifts from the Attributes-plugin/ADR-028
+// authority shape that `ario_arns::buy_name` depends on (a mismatch surfaces
+// only later, as MPL Core 0x4 "Plugin not found", at purchase time).
 export {
   spawnSolanaANT,
+  buildSpawnAntInstructions,
+  buildCreateAntInstruction,
   ARIO_LOGO_TX_ID,
   DEFAULT_ANT_TRANSACTION_ID,
 } from './spawn-ant.js';
 export type {
+  AntAttribute,
+  SpawnAntInstructions,
   SpawnSolanaANTParams,
   SpawnSolanaANTResult,
   SpawnSolanaANTState,
@@ -272,6 +285,10 @@ export {
   estimatePriorityFeeMicroLamports,
   estimateQuotePriorityFeeMicroLamports,
   estimateWalletPriorityFeeMicroLamports,
+  // Consumers assembling their own instruction bundles (see
+  // `buildSpawnAntInstructions`) need the same send path the SDK uses
+  // internally, including its compute-budget and wallet-rewrite handling.
+  sendAndConfirm,
 } from './send.js';
 export {
   ACL_BOOTSTRAP_ACCOUNT_BYTES,

src/solana/spawn-ant-owner.test.ts

@@ -0,0 +1,106 @@
+/**
+ * A spawned ANT's OWNER may differ from the wallet that pays for it.
+ *
+ * `buildSpawnAntInstructions({ owner })` separates the two roles the spawn
+ * really has: `signer` funds the MPL Core asset's rent and signs `CreateV1`,
+ * while `owner` receives the NFT and signs `ario_ant::initialize`. That is what
+ * a sponsored spawn needs — a service pays, the end user owns — and the chain
+ * already supports it (`CreateV1` takes `payer` and `owner` as separate
+ * accounts, and `owner` is not a signer there).
+ *
+ * These tests pin the ACCOUNT ROLES rather than the byte layout, which
+ * `spawn-ant.test.ts` already covers: the failure mode this guards against is a
+ * silent swap of payer and owner, which would hand custody to the wrong wallet
+ * while still producing a perfectly well-formed transaction.
+ */
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+
+import {
+  type Address,
+  address,
+  createNoopSigner,
+  generateKeyPairSigner,
+} from '@solana/kit';
+
+import { buildSpawnAntInstructions } from './spawn-ant.js';
+
+const OWNER: Address = address('11111111111111111111111111111113');
+
+/** MPL Core `CreateV1` account order: asset, collection, authority, payer, owner. */
+const CREATE_V1_PAYER_INDEX = 3;
+const CREATE_V1_OWNER_INDEX = 4;
+
+async function build(withOwner: boolean) {
+  const signer = await generateKeyPairSigner();
+  const { instructions } = await buildSpawnAntInstructions({
+    signer,
+    state: { name: 'sponsored-name' },
+    ...(withOwner ? { owner: createNoopSigner(OWNER) } : {}),
+  });
+  const [createIx, initIx] = instructions;
+  assert.ok(createIx.accounts, 'CreateV1 must carry accounts');
+  assert.ok(initIx.accounts, 'initialize must carry accounts');
+  return { signer, createIx, initIx };
+}
+
+describe('buildSpawnAntInstructions owner/payer separation', () => {
+  it('defaults the owner to the signer, unchanged from before', async () => {
+    const { signer, createIx, initIx } = await build(false);
+    const accounts = createIx.accounts as readonly { address: Address }[];
+
+    assert.equal(accounts[CREATE_V1_PAYER_INDEX].address, signer.address);
+    assert.equal(accounts[CREATE_V1_OWNER_INDEX].address, signer.address);
+    assert.ok(
+      (initIx.accounts as readonly { address: Address }[]).some(
+        (a) => a.address === signer.address,
+      ),
+      'initialize must be signed by the signer when no owner is given',
+    );
+  });
+
+  it('mints to `owner` while `signer` still pays', async () => {
+    const { signer, createIx } = await build(true);
+    const accounts = createIx.accounts as readonly { address: Address }[];
+
+    assert.equal(
+      accounts[CREATE_V1_PAYER_INDEX].address,
+      signer.address,
+      'the sponsor must remain the payer',
+    );
+    assert.equal(
+      accounts[CREATE_V1_OWNER_INDEX].address,
+      OWNER,
+      'the ANT must be minted to the supplied owner, not the payer',
+    );
+    assert.notEqual(
+      accounts[CREATE_V1_OWNER_INDEX].address,
+      signer.address,
+      'payer and owner must not collapse — that silently hands over custody',
+    );
+  });
+
+  // `ario_ant::initialize` declares `owner: Signer` and creates AntConfig,
+  // AntControllers and the root AntRecord with `payer = owner`. Signing it with
+  // the sponsor would both fail on chain and charge the wrong account.
+  it('signs `initialize` as the OWNER, not the payer', async () => {
+    const { signer, initIx } = await build(true);
+    const addresses = (initIx.accounts as readonly { address: Address }[]).map(
+      (a) => a.address,
+    );
+
+    assert.ok(addresses.includes(OWNER), 'initialize must reference the owner');
+    assert.ok(
+      !addresses.includes(signer.address),
+      'initialize must NOT reference the sponsor — it pins payer = owner',
+    );
+  });
+
+  it('accepts a noop signer, so a sponsor can build for a remote owner', async () => {
+    const { createIx } = await build(true);
+    const accounts = createIx.accounts as readonly { address: Address }[];
+    // The point of a noop signer: the sponsor assembles and partially signs the
+    // transaction without holding the owner's key, and the owner adds theirs.
+    assert.equal(accounts[CREATE_V1_OWNER_INDEX].address, OWNER);
+  });
+});

src/solana/spawn-ant.ts

@@ -361,11 +361,33 @@ export async function buildSpawnAntInstructions(params: {
   state: SpawnSolanaANTState;
   antProgramId?: Address;
   mintSigner?: KeyPairSigner;
+  /**
+   * Wallet that will OWN the new ANT. Defaults to `signer`, which is the
+   * existing behaviour — omitting it changes nothing.
+   *
+   * Supplying a different signer separates the two roles the spawn actually
+   * has: `signer` stays the fee payer and `CreateV1` authority (it funds the
+   * MPL Core asset's rent), while `owner` receives the NFT and signs
+   * `ario_ant::initialize`. That split is what a sponsored spawn needs — a
+   * service pays, the end user owns — and it is available on chain today:
+   * `CreateV1` takes `payer` and `owner` as separate accounts and `owner` is
+   * not a signer there.
+   *
+   * `owner` must still be a signer, because `ario_ant::initialize` declares
+   * `owner: Signer` and pins `payer = owner` for the three PDAs it creates
+   * (`AntConfig`, `AntControllers`, the root `AntRecord`). A sponsor
+   * therefore also has to fund those lamports on the owner's account — most
+   * simply with a `SystemTransfer` earlier in the same transaction. Callers
+   * assembling a partially-signed transaction for a remote owner can pass
+   * `createNoopSigner(ownerAddress)` and let the owner add the signature.
+   */
+  owner?: SolanaSigner;
 }): Promise<SpawnAntInstructions> {
   if (!params.state?.name || params.state.name.length === 0) {
     throw new Error('buildSpawnAntInstructions: state.name is required');
   }
   const { signer, state, antProgramId = ARIO_ANT_PROGRAM_ID } = params;
+  const owner = params.owner ?? signer;
   const mintSigner = params.mintSigner ?? (await generateKeyPairSigner());
   const mint = mintSigner.address;
 
@@ -392,18 +414,18 @@ export async function buildSpawnAntInstructions(params: {
   //
   // ADR-028: the asset's UpdateAuthority is the per-asset `ant_authority` PDA
   // and the Attributes plugin authority is `UpdateAuthority` (→ that PDA), so
-  // all MPL Core updates route through the ario-ant program. The owner (the
-  // spawning signer) keeps custody of the NFT.
+  // all MPL Core updates route through the ario-ant program. The owner keeps
+  // custody of the NFT — by default the spawning signer, or `params.owner`
+  // when a sponsor is paying on someone else's behalf.
   const [antAuthority] = await getAntAuthorityPDA(mint, antProgramId);
   const createIx = getCreateV1Instruction({
     asset: mintSigner,
     payer: signer,
     authority: signer,
     // `owner` MUST be explicit. MPL Core defaults owner to updateAuthority when
     // omitted, so with updateAuthority = the ant_authority PDA an omitted owner
-    // would make the PROGRAM PDA the NFT owner (user loses custody). Pin it to
-    // the spawning wallet.
-    owner: signer.address,
+    // would make the PROGRAM PDA the NFT owner (user loses custody).
+    owner: owner.address,
     updateAuthority: antAuthority,
     dataState: DataState.AccountState,
     name: state.name,
@@ -428,7 +450,9 @@ export async function buildSpawnAntInstructions(params: {
   const initIx = await buildInitializeAntIx({
     programId: antProgramId,
     mint,
-    signer,
+    // `ario_ant::initialize` declares `owner: Signer` and creates its PDAs with
+    // `payer = owner`, so this must be the OWNER, not the fee payer.
+    signer: owner,
     state,
   });