@projectsolo/solo-mission-mcp 0.19.3 → 0.20.1

package/src/solana/verify.test.ts

@@ -0,0 +1,179 @@
+/**
+ * The verifier is the one thing standing between an agent and signing bytes it cannot read, so it
+ * is tested against a REAL transaction built by the deployed program's own backend rather than a
+ * synthetic one. A hand-built fixture would encode my assumptions about the layout twice and agree
+ * with itself.
+ *
+ * `fixtures/funding-transaction.json` is captured from a devnet funding run.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import {
+  verifyFundingTransaction,
+  type VerifyInput,
+  type ExpectedFunding,
+  type FundingAccounts,
+} from './verify'
+import { toRawAmount } from '../tools/solana'
+
+const fx = JSON.parse(
+  readFileSync(join(__dirname, 'fixtures', 'funding-transaction.json'), 'utf8'),
+) as {
+  transaction_base64: string
+  declared: ExpectedFunding
+  accounts: FundingAccounts
+  program_id: string
+  sponsor: string
+  mint: string
+}
+
+const baseInput = (): VerifyInput => ({
+  transaction_base64: fx.transaction_base64,
+  declared: fx.declared,
+  accounts: fx.accounts,
+  expected: {
+    budget_raw: String(fx.declared.budget),
+    base_pool_raw: String(fx.declared.base_pool),
+    lottery_winner_count: Number(fx.declared.lottery_winner_count),
+    lottery_prize_per_winner_raw: String(fx.declared.lottery_prize_per_winner),
+    qualify_deadline: Number(fx.declared.qualify_deadline),
+    settlement_deadline: Number(fx.declared.settlement_deadline),
+    mint: fx.mint,
+    sponsor: fx.sponsor,
+  },
+  expected_program_id: fx.program_id,
+})
+
+describe('accepts a genuine transaction', () => {
+  it('passes with no problems', async () => {
+    const r = await verifyFundingTransaction(baseInput())
+    expect(r.problems).toEqual([])
+    expect(r.ok).toBe(true)
+  })
+
+  it('reports what it actually saw, for logging even on success', async () => {
+    const r = await verifyFundingTransaction(baseInput())
+    expect(r.summary.program_id).toBe(fx.program_id)
+    expect(r.summary.instruction_count).toBe(1)
+    expect(r.summary.signers).toEqual([fx.sponsor])
+  })
+})
+
+describe('refuses when the agent expected something else', () => {
+  it('catches an altered budget', async () => {
+    const input = baseInput()
+    input.expected.budget_raw = '999999999'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/budget/)
+  })
+
+  it('catches a substituted mint', async () => {
+    const input = baseInput()
+    input.expected.mint = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/mint/)
+  })
+
+  it('catches a different program, even when every parameter matches', async () => {
+    const input = baseInput()
+    input.expected_program_id = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/program/)
+  })
+
+  it('catches a sponsor who is not the signer', async () => {
+    const input = baseInput()
+    input.expected.sponsor = '4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/signer|fee payer/i)
+  })
+
+  it('reports every problem, not just the first', async () => {
+    // An agent debugging this wants the whole list, not one at a time.
+    const input = baseInput()
+    input.expected.budget_raw = '1'
+    input.expected.mint = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'
+    const r = await verifyFundingTransaction(input)
+    expect(r.problems.length).toBeGreaterThan(1)
+  })
+})
+
+describe('refuses when the backend quoted one thing and built another', () => {
+  it('catches a declared budget that disagrees with the encoded bytes', async () => {
+    // The strongest check: everything else compares the backend's JSON against the agent's
+    // expectations, which a lying backend controls both halves of. This compares the JSON against
+    // the instruction data actually being signed.
+    const input = baseInput()
+    input.declared = { ...fx.declared, budget: '1' }
+    input.expected.budget_raw = '1'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/described one thing and built another/)
+  })
+
+  it('catches a declared deadline that disagrees with the bytes', async () => {
+    const input = baseInput()
+    input.declared = { ...fx.declared, settlement_deadline: '1' }
+    input.expected.settlement_deadline = 1
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/described one thing and built another/)
+  })
+})
+
+describe('structural refusals', () => {
+  it('catches a vault equal to the sponsor token account', async () => {
+    // Would mean the budget never leaves the sponsor's control — funded on paper, not escrowed.
+    const input = baseInput()
+    input.accounts = { ...fx.accounts, vault: fx.accounts.sponsor_token_account }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/not be escrowed/)
+  })
+
+  it('catches a vault that is not a program-derived address', async () => {
+    // An on-curve "vault" is a wallet somebody holds the key to.
+    const input = baseInput()
+    input.accounts = { ...fx.accounts, vault: fx.sponsor }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/program-derived|holds its key/)
+  })
+
+  it('catches a malformed seed commit', async () => {
+    const input = baseInput()
+    input.declared = { ...fx.declared, seed_commit: 'nope' }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/seed_commit/)
+  })
+})
+
+describe('toRawAmount avoids the float trap', () => {
+  it('converts whole and fractional amounts exactly', () => {
+    expect(toRawAmount(10, 6)).toBe('10000000')
+    expect(toRawAmount(10.5, 6)).toBe('10500000')
+    expect(toRawAmount(0.5, 6)).toBe('500000')
+  })
+
+  it('handles the amount that float multiplication gets wrong', () => {
+    // 0.07 * 1e6 is 70000.00000000001 in IEEE 754 and truncates to 69999 — a silent one-unit
+    // shortfall whose on-chain rejection names neither the amount nor the cause.
+    expect(toRawAmount(0.07, 6)).toBe('70000')
+    expect(toRawAmount(0.29, 6)).toBe('290000')
+    expect(toRawAmount(1.005, 6)).toBe('1005000')
+  })
+
+  it('rejects more precision than the mint has', () => {
+    expect(() => toRawAmount(1.0000001, 6)).toThrow(/decimal places/)
+  })
+
+  it('rejects a negative amount', () => {
+    expect(() => toRawAmount(-1, 6)).toThrow()
+  })
+})

package/src/solana/verify.ts

@@ -0,0 +1,257 @@
+/**
+ * Decodes a funding transaction and checks it against what the agent asked for.
+ *
+ * WHY THIS IS MANDATORY, NOT DEFENSIVE. On Base an agent builds `createTask` itself from published
+ * parameters, so it can verify every field against the API response and the contract ABI before
+ * signing. Solana funding uses partial signing — the backend builds, the agent signs, the backend
+ * submits — which removes a whole class of integration breakage but hands the agent an opaque
+ * base64 blob.
+ *
+ * A human signing in Phantom gets that blob decoded for free by their wallet UI. **An agent has no
+ * wallet UI.** So without this, "the agent authorises exactly what it signs" is technically true and
+ * practically meaningless: it would be authorising bytes it cannot read. The design freeze calls
+ * this the least settled decision in the whole plan and makes the verifier a requirement of the
+ * flow, not an optional extra.
+ *
+ * WHAT THIS DOES AND DOES NOT PROVE. It re-encodes the instruction data from the agent's own
+ * parameters and compares bytes, and it checks the accounts the transaction touches. So it catches a
+ * backend that quoted one budget and built another, a substituted mint, a redirected vault, or a
+ * different program entirely. It does NOT prove the backend will submit the transaction it showed
+ * you — but it cannot usefully alter one afterwards either, because any change invalidates the
+ * signature.
+ *
+ * This reintroduces a dependency on the instruction layout, which partial signing was meant to
+ * remove. The difference is where that dependency lives: inside a package we version and ship,
+ * rather than as a contract every third party reimplements. That is the whole point, and it is
+ * honest to say the shape dependency is reduced rather than eliminated.
+ */
+
+/** What the agent believes it is funding. Every field is compared. */
+export interface ExpectedFunding {
+  /** Smallest-unit strings, as the API returns them. Compared as bigints so "10" and "10.0" or a
+   *  leading zero cannot slip past a string equality check. */
+  budget: string;
+  base_pool: string;
+  lottery_winner_count: number;
+  lottery_prize_per_winner: string;
+  qualify_deadline: string;
+  settlement_deadline: string;
+  /** 64 hex chars, no 0x. */
+  seed_commit: string;
+}
+
+export interface FundingAccounts {
+  program_id: string;
+  config: string;
+  task: string;
+  vault: string;
+  whitelist: string;
+  mint: string;
+  sponsor: string;
+  sponsor_token_account: string;
+}
+
+export interface VerifyInput {
+  transaction_base64: string;
+  declared: ExpectedFunding;
+  accounts: FundingAccounts;
+  /** What the agent asked for, independent of what the backend replied. */
+  expected: {
+    budget_raw: string;
+    base_pool_raw: string;
+    lottery_winner_count: number;
+    lottery_prize_per_winner_raw: string;
+    qualify_deadline: number;
+    settlement_deadline: number;
+    mint: string;
+    sponsor: string;
+  };
+  /** The program the agent expects. Pinned so a transaction pointed at a different program is
+   *  rejected even if every parameter matches. */
+  expected_program_id: string;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** Every discrepancy found, not just the first — an agent debugging this wants the whole list. */
+  problems: string[];
+  /** What the transaction actually contains, for logging even on success. */
+  summary: {
+    program_id: string;
+    instruction_count: number;
+    signers: string[];
+    budget: string;
+    mint: string;
+    task: string;
+  };
+}
+
+const eqAmount = (a: string, b: string): boolean => {
+  try {
+    return BigInt(a) === BigInt(b);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Verifies a funding transaction. Returns every problem rather than throwing on the first.
+ *
+ * REFUSE TO SIGN when `ok` is false. The caller must treat this as a hard stop — a mismatch means
+ * the backend built something other than what was quoted, and signing it authorises that difference.
+ */
+export async function verifyFundingTransaction(input: VerifyInput): Promise<VerifyResult> {
+  const { Transaction, PublicKey } = await import('@solana/web3.js');
+  const problems: string[] = [];
+
+  const tx = Transaction.from(Buffer.from(input.transaction_base64, 'base64'));
+
+  // ---- structure ------------------------------------------------------------------------------
+  // Exactly one instruction. An extra one is the cheapest way to hide something — a token transfer
+  // appended after create_task would be signed by the same signature.
+  if (tx.instructions.length !== 1) {
+    problems.push(
+      `expected exactly 1 instruction, found ${tx.instructions.length} — ` +
+        'additional instructions would be authorised by the same signature',
+    );
+  }
+
+  const ix = tx.instructions[0];
+  const programId = ix?.programId?.toBase58() ?? '(none)';
+  if (programId !== input.expected_program_id) {
+    problems.push(`program is ${programId}, expected ${input.expected_program_id}`);
+  }
+  if (programId !== input.accounts.program_id) {
+    problems.push(
+      `transaction program ${programId} disagrees with the quoted accounts.program_id ` +
+        `${input.accounts.program_id}`,
+    );
+  }
+
+  // ---- the only signer must be us --------------------------------------------------------------
+  const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
+  if (signers.length !== 1 || signers[0] !== input.expected.sponsor) {
+    problems.push(
+      `expected the sponsor ${input.expected.sponsor} to be the only signer, found [${signers.join(', ')}]`,
+    );
+  }
+  if (tx.feePayer?.toBase58() !== input.expected.sponsor) {
+    problems.push(
+      `fee payer is ${tx.feePayer?.toBase58() ?? '(unset)'}, expected ${input.expected.sponsor}`,
+    );
+  }
+
+  // ---- the accounts the money moves between ----------------------------------------------------
+  const keyList = (ix?.keys ?? []).map((k) => k.pubkey.toBase58());
+  for (const [label, expected] of [
+    ['mint', input.expected.mint],
+    ['sponsor', input.expected.sponsor],
+  ] as const) {
+    if (!keyList.includes(expected)) {
+      problems.push(`${label} ${expected} does not appear in the transaction's accounts`);
+    }
+  }
+  if (input.accounts.mint !== input.expected.mint) {
+    problems.push(`quoted mint ${input.accounts.mint}, expected ${input.expected.mint}`);
+  }
+  // The task and its vault are PDAs the program derives; they cannot be verified without repeating
+  // the derivation, but they MUST be distinct and must both be present. A vault equal to the
+  // sponsor's own token account would mean the budget never leaves their control.
+  if (input.accounts.vault === input.accounts.sponsor_token_account) {
+    problems.push('escrow vault equals the sponsor token account — the budget would not be escrowed');
+  }
+  try {
+    // Both must be off-curve, i.e. genuine PDAs with no private key. An on-curve "vault" is a
+    // wallet somebody holds the key to.
+    for (const [label, addr] of [
+      ['task', input.accounts.task],
+      ['vault', input.accounts.vault],
+    ] as const) {
+      if (PublicKey.isOnCurve(new PublicKey(addr).toBytes())) {
+        problems.push(`${label} ${addr} is not a program-derived address — someone holds its key`);
+      }
+    }
+  } catch {
+    problems.push('task or vault is not a valid address');
+  }
+
+  // ---- the parameters --------------------------------------------------------------------------
+  const d = input.declared;
+  const e = input.expected;
+  if (!eqAmount(d.budget, e.budget_raw)) {
+    problems.push(`budget is ${d.budget}, expected ${e.budget_raw}`);
+  }
+  if (!eqAmount(d.base_pool, e.base_pool_raw)) {
+    problems.push(`base_pool is ${d.base_pool}, expected ${e.base_pool_raw}`);
+  }
+  if (d.lottery_winner_count !== e.lottery_winner_count) {
+    problems.push(
+      `lottery_winner_count is ${d.lottery_winner_count}, expected ${e.lottery_winner_count}`,
+    );
+  }
+  if (!eqAmount(d.lottery_prize_per_winner, e.lottery_prize_per_winner_raw)) {
+    problems.push(
+      `lottery_prize_per_winner is ${d.lottery_prize_per_winner}, expected ${e.lottery_prize_per_winner_raw}`,
+    );
+  }
+  if (!eqAmount(d.qualify_deadline, String(e.qualify_deadline))) {
+    problems.push(`qualify_deadline is ${d.qualify_deadline}, expected ${e.qualify_deadline}`);
+  }
+  if (!eqAmount(d.settlement_deadline, String(e.settlement_deadline))) {
+    problems.push(
+      `settlement_deadline is ${d.settlement_deadline}, expected ${e.settlement_deadline}`,
+    );
+  }
+  if (!/^[0-9a-f]{64}$/i.test(d.seed_commit)) {
+    problems.push(`seed_commit is not 32 bytes of hex: ${d.seed_commit}`);
+  }
+
+  // ---- the declared parameters must match the bytes actually being signed ----------------------
+  // The strongest check here. Everything above compares the backend's own JSON description against
+  // the agent's expectations; this compares that description against the instruction data itself, so
+  // a backend cannot quote correct parameters and encode different ones.
+  const data = ix?.data ?? Buffer.alloc(0);
+  if (data.length !== 8 + 8 + 8 + 4 + 8 + 8 + 8 + 32) {
+    problems.push(
+      `instruction data is ${data.length} bytes, expected 84 for create_task — ` +
+        'this is not the instruction it claims to be',
+    );
+  } else {
+    const encoded = {
+      budget: data.readBigUInt64LE(8).toString(),
+      base_pool: data.readBigUInt64LE(16).toString(),
+      lottery_winner_count: data.readUInt32LE(24),
+      lottery_prize_per_winner: data.readBigUInt64LE(28).toString(),
+      qualify_deadline: data.readBigInt64LE(36).toString(),
+      settlement_deadline: data.readBigInt64LE(44).toString(),
+      seed_commit: data.subarray(52, 84).toString('hex'),
+    };
+    for (const key of Object.keys(encoded) as Array<keyof typeof encoded>) {
+      const inBytes = String(encoded[key]);
+      const quoted = String((d as unknown as Record<string, unknown>)[key]);
+      const same =
+        key === 'seed_commit' || key === 'lottery_winner_count'
+          ? inBytes.toLowerCase() === quoted.toLowerCase()
+          : eqAmount(inBytes, quoted);
+      if (!same) {
+        problems.push(
+          `the transaction encodes ${key}=${inBytes} but the response quoted ${quoted} — ` +
+            'the backend described one thing and built another',
+        );
+      }
+    }
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    summary: {
+      program_id: programId,
+      instruction_count: tx.instructions.length,
+      signers,
+      budget: d.budget,
+      mint: input.accounts.mint,
+      task: input.accounts.task,
+    },
+  };
+}

package/src/solana/wallet.ts

@@ -0,0 +1,142 @@
+/**
+ * The agent's Solana wallet.
+ *
+ * An agent needs SOL as well as USDC to sponsor a Solana mission, and that is new — on Base it
+ * needed only ETH for gas and USDC for the budget. The rent line has no EVM analogue:
+ *
+ *   Task account rent      ~0.00374 SOL   ($0.374)  — partly recovered on close_task
+ *   TaskVault token account ~0.00204 SOL   ($0.204)  — recovered in full on close_task
+ *   transaction fees        ~0.00004 SOL   ($0.004)
+ *   ---------------------------------------------------------------------
+ *   locked during a mission ~0.00582 SOL   (~$0.58)
+ *   permanent cost          ~0.00239 SOL   (~$0.24)  — the on-chain archive, kept on purpose
+ *
+ * That ~$0.24 never comes back, and it buys the on-chain evidence that makes the escrow and the
+ * frozen participant list checkable by anyone. On a $10 mission that is 2.4%; on a $1,000 mission,
+ * 0.024%.
+ *
+ * KEY HANDLING. The keypair stays in this process and is used to sign locally. It is never sent to
+ * the Solo API — the backend builds transactions and submits them, but only the agent can authorise
+ * one. That is the whole point of the partial-signing flow: a compromised backend cannot move a
+ * sponsor's funds, because it never holds the signing key.
+ */
+
+import { readFileSync } from 'fs';
+
+export interface SolanaWallet {
+  publicKey: string;
+  /** 64-byte ed25519 secret. Kept in-process; never transmitted. */
+  secretKey: Uint8Array;
+}
+
+export class SolanaWalletUnavailable extends Error {
+  constructor(reason: string) {
+    super(
+      `Solana wallet unavailable: ${reason}\n\n` +
+        'Set one of:\n' +
+        '  SOLO_SOLANA_KEYPAIR       - JSON byte array, as `solana-keygen` writes it\n' +
+        '  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json)\n\n' +
+        'The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a\n' +
+        'refundable deposit, not a fee: most of it returns when the task is closed.',
+    );
+    this.name = 'SolanaWalletUnavailable';
+  }
+}
+
+function parseKeypairBytes(raw: string): Uint8Array {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('[')) {
+    throw new SolanaWalletUnavailable(
+      'value is not a JSON byte array — this is the format `solana-keygen new` writes',
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new SolanaWalletUnavailable('value looks like a JSON array but does not parse');
+  }
+  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === 'number')) {
+    throw new SolanaWalletUnavailable('JSON array must contain only numbers');
+  }
+  const bytes = Uint8Array.from(parsed as number[]);
+  // 64 bytes = 32 seed + 32 public. A 32-byte value is the seed alone, which signs but yields a
+  // different address — surfacing later as "wrong sponsor" rather than as a key problem.
+  if (bytes.length !== 64) {
+    throw new SolanaWalletUnavailable(
+      `expected 64 bytes, got ${bytes.length}` +
+        (bytes.length === 32 ? ' — this is the seed alone, not the full keypair' : ''),
+    );
+  }
+  return bytes;
+}
+
+/**
+ * Loads the agent's wallet.
+ *
+ * Read at call time, not at module load, so a tool that never touches Solana works in a process
+ * with no wallet configured at all — an agent running Base missions should not need one.
+ */
+export async function loadSolanaWallet(): Promise<SolanaWallet> {
+  const inline = process.env.SOLO_SOLANA_KEYPAIR;
+  const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
+
+  let raw: string;
+  if (inline && inline.trim() !== '') {
+    raw = inline;
+  } else if (path && path.trim() !== '') {
+    try {
+      raw = readFileSync(path.replace(/^~/, process.env.HOME ?? '~'), 'utf8');
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${path}: ${(e as Error).message}`);
+    }
+  } else {
+    throw new SolanaWalletUnavailable('neither SOLO_SOLANA_KEYPAIR nor SOLO_SOLANA_KEYPAIR_PATH is set');
+  }
+
+  const secretKey = parseKeypairBytes(raw);
+  const { Keypair } = await import('@solana/web3.js');
+  const kp = Keypair.fromSecretKey(secretKey);
+  return { publicKey: kp.publicKey.toBase58(), secretKey };
+}
+
+/** Whether a Solana wallet is configured, without throwing. */
+export function hasSolanaWallet(): boolean {
+  return Boolean(
+    (process.env.SOLO_SOLANA_KEYPAIR ?? '').trim() ||
+      (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? '').trim(),
+  );
+}
+
+/**
+ * The associated token account for a mint — where the wallet's USDC actually lives.
+ *
+ * An agent commonly has SOL but no token account, because one is only created when tokens first
+ * arrive. `create_task` reads the sponsor's token account, so funding fails if it does not exist —
+ * and the error names the account, not the missing balance, which is confusing enough to be worth
+ * checking for explicitly.
+ */
+export async function associatedTokenAddress(mint: string, owner: string): Promise<string> {
+  const { PublicKey } = await import('@solana/web3.js');
+  const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+  const [address] = PublicKey.findProgramAddressSync(
+    [new PublicKey(owner).toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), new PublicKey(mint).toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+  );
+  return address.toBase58();
+}
+
+/** Signs a base64 transaction built by the backend, returning it base64-encoded. */
+export async function signTransaction(
+  transactionBase64: string,
+  wallet: SolanaWallet,
+): Promise<string> {
+  const { Keypair, Transaction } = await import('@solana/web3.js');
+  const kp = Keypair.fromSecretKey(wallet.secretKey);
+  const tx = Transaction.from(Buffer.from(transactionBase64, 'base64'));
+  // partialSign, not sign: the transaction may carry other signature slots, and `sign` would
+  // discard them.
+  tx.partialSign(kp);
+  return tx.serialize().toString('base64');
+}