fix(payments): split Solana subscription init-authority into its own tx

First-time subscribers failed on-chain with STALE_SUBSCRIPTION_AUTHORITY
(custom error 136): buildSubscribeTxUnsignedBase64 bundled init-authority +
subscribe in one transaction and passed expectedInitId = getSlot() captured
at BUILD time, but the program sets the authority's init_id = Clock::slot at
EXECUTION time, so the two never matched. (Earlier script-verified runs only
passed because the authority was pre-created in a separate tx.)

- Add buildInitAuthorityTxUnsignedBase64() — init-only unsigned tx; returns
  null when the authority already exists.
- buildSubscribeTxUnsignedBase64 no longer bundles init; it throws if the
  authority is missing and always reads the stored init_id.
- /api/payments/solana/subscribe-tx is now two-step: returns {step:'init'}
  when the authority is missing, {step:'subscribe'} once it exists. The wallet
  signs + confirms init, then re-requests the subscribe tx.

Verified end-to-end on devnet with a real Phantom wallet: init -> subscribe ->
first pull -> 80/20 split on-chain, subscription active.

Known limitation: the mobile Solana-Pay QR is one-scan/one-tx and can't do the
two-step; first-time subscribers via QR need a desktop/extension path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: guillermoscript

app/api/payments/solana/subscribe-tx/route.ts

@@ -29,6 +29,7 @@ import { getBase58Encoder } from '@solana/kit'
 import {
   ensurePlanOnChain,
   buildSubscribeTxUnsignedBase64,
+  buildInitAuthorityTxUnsignedBase64,
 } from '@/lib/payments/solana-subscriptions'
 
 export const runtime = 'nodejs'
@@ -68,7 +69,7 @@ export async function POST(req: NextRequest) {
     }
     // Validate the subscriber pubkey.
     try {
-      // eslint-disable-next-line no-new
+       
       new PublicKey(account)
     } catch {
       return NextResponse.json({ error: 'Invalid account' }, { status: 400 })
@@ -149,7 +150,30 @@ export async function POST(req: NextRequest) {
       .eq('transaction_id', tx.transaction_id)
       .is('provider_metadata', null)
 
-    // 1. Ensure the on-chain plan exists (idempotent; puller = merchant/owner).
+    const appName = process.env.NEXT_PUBLIC_APP_NAME || 'LMS'
+
+    // STEP 1 (first-time subscribers only): the SubscriptionAuthority must be
+    // created in its OWN confirmed transaction before subscribe — a bundled
+    // init+subscribe always fails with STALE_SUBSCRIPTION_AUTHORITY (136),
+    // because the authority's init_id is the execution slot and subscribe can't
+    // pass a matching value at build time. If the authority is missing, return
+    // the init tx; the wallet signs + confirms it, then calls again for subscribe.
+    const initTx = await buildInitAuthorityTxUnsignedBase64({
+      rpcUrl,
+      subscriber: account,
+      mint,
+    })
+    if (initTx) {
+      return NextResponse.json({
+        transaction: initTx,
+        step: 'init',
+        message: `${appName} — initialize subscription wallet`,
+      })
+    }
+
+    // STEP 2: authority exists. Ensure the on-chain plan exists (idempotent;
+    // puller = merchant/owner), then build the unsigned SUBSCRIBE tx carrying
+    // our reference pubkey so findReference can locate it.
     await ensurePlanOnChain({
       rpcUrl,
       pullerSecretKeyBase58: pullerSecret,
@@ -161,8 +185,6 @@ export async function POST(req: NextRequest) {
       pullers: [merchant],
     })
 
-    // 2. Build the unsigned SUBSCRIBE tx (init authority + subscribe), with our
-    //    reference pubkey attached so findReference can locate it.
     const transaction = await buildSubscribeTxUnsignedBase64({
       rpcUrl,
       subscriber: account,
@@ -172,9 +194,9 @@ export async function POST(req: NextRequest) {
       reference: referencePubkey,
     })
 
-    const appName = process.env.NEXT_PUBLIC_APP_NAME || 'LMS'
     return NextResponse.json({
       transaction,
+      step: 'subscribe',
       message: `${appName} — subscribe ${tx.transaction_id}`,
     })
   } catch (error) {

lib/payments/solana-subscriptions.ts

@@ -578,54 +578,18 @@ export async function buildSubscribeTxUnsignedBase64(p: {
   //   expected_subscription_authority_init_id == authority.init_id
   // (else SUBSCRIPTIONS_ERROR__STALE_SUBSCRIPTION_AUTHORITY = 136).
   //
-  // - If the authority already exists, read its stored init_id.
-  // - If we bundle init + subscribe in this same tx, the init instruction will
-  //   set init_id to the slot in which the tx executes, so the matching value
-  //   is the current slot. Query it from the RPC (constant within a slot).
-  let expectedInitId: bigint;
-
+  // init_id therefore equals the slot in which the init tx EXECUTES, which we
+  // cannot predict at build time. Bundling init + subscribe in one tx is thus
+  // impossible: the build-time slot we'd pass never matches the execution slot,
+  // so subscribe fails with 136. The authority MUST be created in its own,
+  // already-confirmed transaction (buildInitAuthorityTxUnsignedBase64) before
+  // this runs; we then read its stored init_id.
   if (!maybeAuthority.exists) {
-    let ataAddr: string;
-    if (p.userAta) {
-      ataAddr = p.userAta;
-    } else {
-      const spl = await import("@solana/spl-token").catch(() => null);
-      const web3 = await import("@solana/web3.js").catch(() => null);
-      if (spl && web3 && "getAssociatedTokenAddressSync" in spl) {
-        const { getAssociatedTokenAddressSync } =
-          spl as typeof import("@solana/spl-token");
-        const { PublicKey } = web3 as typeof import("@solana/web3.js");
-        ataAddr = getAssociatedTokenAddressSync(
-          new PublicKey(p.mint),
-          new PublicKey(p.subscriber)
-        ).toBase58();
-      } else {
-        throw new Error(
-          "buildSubscribeTxUnsignedBase64: userAta is required when @solana/spl-token v1 is unavailable"
-        );
-      }
-    }
-
-    const SPL_TOKEN_PROGRAM_ADDR =
-      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-    const initIx = getInitSubscriptionAuthorityInstruction({
-      owner: subscriberSigner,
-      subscriptionAuthority: subAuthorityPda,
-      tokenMint: addr(p.mint) as Address,
-      userAta: addr(ataAddr) as Address,
-      tokenProgram: addr(
-        p.tokenProgram ?? SPL_TOKEN_PROGRAM_ADDR
-      ) as Address,
-    });
-    instructions.push(initIx);
-
-    // init_id will equal Clock::slot at execution → use the current slot.
-    const currentSlot = await rpc.getSlot().send();
-    expectedInitId = BigInt(currentSlot);
-  } else {
-    // Authority already exists — match its stored init_id exactly.
-    expectedInitId = maybeAuthority.data.initId;
+    throw new Error(
+      "buildSubscribeTxUnsignedBase64: SubscriptionAuthority does not exist for this subscriber+mint — initialize it first in a separate, confirmed transaction"
+    );
   }
+  const expectedInitId: bigint = maybeAuthority.data.initId;
 
   const subscribeData: SubscribeDataArgs = {
     planId: p.planId,
@@ -683,6 +647,81 @@ export async function buildSubscribeTxUnsignedBase64(p: {
   return getBase64EncodedWireTransaction(compiledTx) as string;
 }
 
+/**
+ * Builds the unsigned, init-SubscriptionAuthority transaction for a subscriber.
+ *
+ * This MUST be a separate transaction from subscribe (see the 136 note in
+ * buildSubscribeTxUnsignedBase64): the authority's init_id is the execution
+ * slot, so subscribe can only pass a matching init_id once the authority is
+ * already on-chain. The wallet signs + submits this, waits for confirmation,
+ * then requests the subscribe tx.
+ *
+ * Returns `null` if the authority already exists (nothing to do).
+ */
+export async function buildInitAuthorityTxUnsignedBase64(p: {
+  rpcUrl: string;
+  /** Subscriber's base58 public key — NOT a secret key. */
+  subscriber: string;
+  mint: string;
+  tokenProgram?: string;
+  /** Optional: subscriber's ATA for the mint. */
+  userAta?: string;
+}): Promise<string | null> {
+  const rpc = makeRpc(p.rpcUrl);
+  const subscriberAddr = addr(p.subscriber) as Address;
+  const subscriberSigner = createNoopSigner(subscriberAddr);
+
+  const maybeAuthority = await fetchMaybeSubscriptionAuthorityFromSeeds(rpc, {
+    user: subscriberAddr,
+    tokenMint: addr(p.mint) as Address,
+  });
+  if (maybeAuthority.exists) return null; // already initialized — skip
+
+  const [subAuthorityPda] = await findSubscriptionAuthorityPda({
+    user: subscriberAddr,
+    tokenMint: addr(p.mint) as Address,
+  });
+
+  let ataAddr: string;
+  if (p.userAta) {
+    ataAddr = p.userAta;
+  } else {
+    const spl = await import("@solana/spl-token").catch(() => null);
+    const web3 = await import("@solana/web3.js").catch(() => null);
+    if (spl && web3 && "getAssociatedTokenAddressSync" in spl) {
+      const { getAssociatedTokenAddressSync } =
+        spl as typeof import("@solana/spl-token");
+      const { PublicKey } = web3 as typeof import("@solana/web3.js");
+      ataAddr = getAssociatedTokenAddressSync(
+        new PublicKey(p.mint),
+        new PublicKey(p.subscriber)
+      ).toBase58();
+    } else {
+      throw new Error(
+        "buildInitAuthorityTxUnsignedBase64: userAta is required when @solana/spl-token v1 is unavailable"
+      );
+    }
+  }
+
+  const SPL_TOKEN_PROGRAM_ADDR = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+  const initIx = getInitSubscriptionAuthorityInstruction({
+    owner: subscriberSigner,
+    subscriptionAuthority: subAuthorityPda,
+    tokenMint: addr(p.mint) as Address,
+    userAta: addr(ataAddr) as Address,
+    tokenProgram: addr(p.tokenProgram ?? SPL_TOKEN_PROGRAM_ADDR) as Address,
+  });
+
+  const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let msg: any = createTransactionMessage({ version: 0 });
+  msg = setTransactionMessageFeePayer(subscriberAddr, msg);
+  msg = setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg);
+  msg = appendTransactionMessageInstruction(initIx as never, msg);
+  const compiledTx = compileTransaction(msg);
+  return getBase64EncodedWireTransaction(compiledTx) as string;
+}
+
 /**
  * Idempotent: ensures a plan exists on-chain.
  *

scripts/devnet-fund-wallet.mjs

@@ -0,0 +1,64 @@
+/**
+ * Fund an arbitrary devnet wallet for the real-wallet subscription test:
+ *   - transfers a little SOL (fees + account rent) from the funder, and
+ *   - creates the wallet's token account + mints test "USDC" tokens to it.
+ *
+ * Avoids the public faucet (rate-limited) by using the already-funded funder
+ * keypair (scripts/.devnet-payer.json) and the test mint's authority.
+ *
+ * Usage:  node scripts/devnet-fund-wallet.mjs <wallet_address> [tokens] [sol]
+ *   tokens default 5, sol default 0.05
+ */
+
+import {
+  Connection, Keypair, LAMPORTS_PER_SOL, SystemProgram, Transaction,
+  sendAndConfirmTransaction, PublicKey,
+} from '@solana/web3.js'
+import { getOrCreateAssociatedTokenAccount, mintTo } from '@solana/spl-token'
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const RPC = process.env.SOLANA_RPC_URL || 'https://api.devnet.solana.com'
+const here = dirname(fileURLToPath(import.meta.url))
+const p = (f) => join(here, f)
+
+const dest = process.argv[2]
+const tokens = Number(process.argv[3] || '5')
+const sol = Number(process.argv[4] || '0.05')
+if (!dest) { console.error('usage: node scripts/devnet-fund-wallet.mjs <wallet_address> [tokens] [sol]'); process.exit(1) }
+
+let destPk
+try { destPk = new PublicKey(dest) } catch { console.error('invalid wallet address:', dest); process.exit(1) }
+
+if (!existsSync(p('.devnet-payer.json'))) { console.error('scripts/.devnet-payer.json not found'); process.exit(1) }
+if (!existsSync(p('.devnet-mint.json'))) { console.error('scripts/.devnet-mint.json not found — run devnet-subs-setup.mjs first'); process.exit(1) }
+
+const conn = new Connection(RPC, 'confirmed')
+const funder = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(readFileSync(p('.devnet-payer.json'), 'utf8'))))
+const mint = new PublicKey(JSON.parse(readFileSync(p('.devnet-mint.json'), 'utf8')).mint)
+
+console.log('funder:', funder.publicKey.toBase58())
+console.log('mint  :', mint.toBase58())
+console.log('dest  :', destPk.toBase58())
+
+// 1. SOL for fees + rent.
+const need = Math.round(sol * LAMPORTS_PER_SOL)
+const have = await conn.getBalance(destPk)
+if (have < need) {
+  const tx = new Transaction().add(
+    SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: destPk, lamports: need - have }),
+  )
+  const sig = await sendAndConfirmTransaction(conn, tx, [funder])
+  console.log(`sent ${(need - have) / LAMPORTS_PER_SOL} SOL ✓ (${sig})`)
+} else {
+  console.log('already has >= requested SOL, skipping transfer')
+}
+
+// 2. Token account + mint test tokens (6 decimals).
+const ata = await getOrCreateAssociatedTokenAccount(conn, funder, mint, destPk)
+await mintTo(conn, funder, mint, ata.address, funder, Math.round(tokens * 1_000_000))
+const bal = await conn.getTokenAccountBalance(ata.address)
+console.log(`token ATA: ${ata.address.toBase58()}`)
+console.log(`minted ${tokens} tokens ✓ — balance now ${bal.value.uiAmountString}`)
+console.log('\nWallet funded ✓ — open the desktop test page and subscribe.')