@projectsolo/solo-mission-mcp 0.21.13 → 0.22.0

package/src/tools/solana.test.ts

@@ -0,0 +1,356 @@
+/**
+ * The Solana tool handlers, with the API mocked and the RPC stubbed, driven by the real v2
+ * funding responses in `src/solana/fixtures`. What matters here is the flow around the verifier:
+ * which quote max_fee_bps is held to, that nothing is signed or submitted on a refusal, that a
+ * lottery's co-signature survives signing, and that a refused refund says who refused it and why.
+ */
+import { describe, it, expect, vi, beforeAll, beforeEach, afterAll, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js'
+
+const apiPost = vi.fn()
+const apiGet = vi.fn()
+vi.mock('../api/client.js', () => ({
+  apiPost: (...a: unknown[]) => apiPost(...a),
+  apiGet: (...a: unknown[]) => apiGet(...a),
+}))
+
+import { handleSolanaTool } from './solana.js'
+import { decryptOpenSslAes256CbcPbkdf2 } from '../solana/wallet.js'
+import { ed25519Verify, parseWireTransaction } from '../solana/wire.js'
+import { DISCRIMINATORS } from '../solana/verify.js'
+
+const FIX = join(__dirname, '..', 'solana', 'fixtures')
+const load = (f: string) => JSON.parse(readFileSync(join(FIX, f), 'utf8'))
+const lottery = load('funding-transaction-v2-lottery.json')
+const plain = load('funding-transaction-v2-plain.json')
+const configFx = load('config-account.json')
+const PROGRAM_ID: string = lottery.program_id
+const MINT: string = lottery.mint
+
+const apiError = (status: number, data: Record<string, unknown>) =>
+  Object.assign(new Error(String(data.message)), { status, data })
+
+let dir: string
+let savedPath: string | undefined
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), 'solo-solana-tools-'))
+  const keyfile = join(dir, 'id.json')
+  writeFileSync(
+    keyfile,
+    decryptOpenSslAes256CbcPbkdf2(readFileSync(join(FIX, 'test-keypair.json.enc')), 'test-only-fixture-passphrase'),
+  )
+  savedPath = process.env.SOLO_SOLANA_KEYPAIR_PATH
+  process.env.SOLO_SOLANA_KEYPAIR_PATH = keyfile
+})
+afterAll(() => {
+  if (savedPath === undefined) delete process.env.SOLO_SOLANA_KEYPAIR_PATH
+  else process.env.SOLO_SOLANA_KEYPAIR_PATH = savedPath
+  rmSync(dir, { recursive: true, force: true })
+})
+
+let config: Record<string, unknown>
+let mission: Record<string, unknown>
+let rpcFails: boolean
+// An initialized 6-decimal SPL mint account (82 bytes: decimals at 44, is_initialized at 45).
+const mintData = (() => { const b = Buffer.alloc(82); b[44] = 6; b[45] = 1; return b.toString('base64') })()
+beforeEach(() => {
+  apiGet.mockReset()
+  apiPost.mockReset()
+  rpcFails = false
+  config = {
+    cluster: 'devnet',
+    program_id: PROGRAM_ID,
+    rpc_url: 'https://rpc.example',
+    mints: { TEST_USDC: MINT },
+    decimals: { TEST_USDC: 6 },
+    escrow_interface: 'v2',
+  }
+  apiGet.mockImplementation(async (path: string) => {
+    if (path === '/agent/solana/config') return config
+    if (path.startsWith('/agent/missions/')) return { success: true, mission }
+    throw new Error(`unexpected GET ${path}`)
+  })
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (_url: string, init: { body: string }) => {
+      const { method, params } = JSON.parse(init.body)
+      if (rpcFails) throw new Error('fetch failed')
+      if (method !== 'getAccountInfo') throw new Error(`unexpected RPC ${method}`)
+      if (params[0] !== configFx.address) {
+        return { json: async () => ({ result: { value: { owner: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', data: [mintData, 'base64'] } } }) }
+      }
+      return {
+        json: async () => ({
+          result: { value: { owner: configFx.owner, data: [configFx.data_base64, 'base64'] } },
+        }),
+      }
+    }),
+  )
+})
+afterEach(() => vi.unstubAllGlobals())
+
+describe('fund_solana_mission', () => {
+  const serve = (fx: any, response = fx.response) => {
+    mission = { ...fx.mission }
+    apiPost.mockImplementation(async (path: string, body: any) => {
+      if (path.endsWith('/funding-transaction')) return structuredClone(response)
+      if (path.endsWith('/confirm-funding')) return { task_id: body.task_id, status: 'active', signature: 'sig' }
+      throw new Error(`unexpected POST ${path}`)
+    })
+  }
+  const submitted = () => apiPost.mock.calls.filter(([p]) => String(p).endsWith('/confirm-funding'))
+
+  it('verifies, signs and submits a co-signed lottery, keeping the Operator signature', async () => {
+    serve(lottery)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r).toMatchObject({ funded: true, verified: true, lottery: true, operator_cosigned: true, max_fee_bps: 0 })
+    const signed = parseWireTransaction(Buffer.from(submitted()[0][1].signed_transaction, 'base64'))
+    const original = parseWireTransaction(Buffer.from(lottery.response.transaction_base64, 'base64'))
+    expect(signed.message.equals(original.message)).toBe(true)
+    expect(signed.signatures[1].equals(original.signatures[1])).toBe(true)
+    expect(ed25519Verify(signed.signatures[0], signed.message, lottery.sponsor)).toBe(true)
+    expect(ed25519Verify(signed.signatures[1], signed.message, signed.accountKeys[1])).toBe(true)
+  })
+
+  it('funds a non-lottery mission', async () => {
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r).toMatchObject({ funded: true, lottery: false, operator_cosigned: false })
+  })
+
+  it("defaults the expected mint to the mission's own, not the first mint the config lists", async () => {
+    config.mints = { USDC: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU', TEST_USDC: MINT }
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, dry_run: true })
+    expect(r).toMatchObject({ verified: true, would_escrow: `0.01 (10000 raw) of ${MINT}` })
+    const fundingCall = apiPost.mock.calls.find(([p]) => String(p).endsWith('/funding-transaction'))!
+    expect(fundingCall[1].sponsor_token_account).toBe(plain.response.accounts.sponsor_token_account)
+  })
+
+  it('still refuses when expected_mint names a different mint than the transaction uses', async () => {
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', {
+      mission_id: 'm1', expected_budget: 0.01, expected_mint: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU', dry_run: true,
+    })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems.join(' ')).toMatch(/account #3 \(mint\) is ECXjKm8n/)
+  })
+
+  it('refuses before building anything when the deployment is not on the v2 interface', async () => {
+    config.escrow_interface = 'v1'
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01 })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems[0]).toMatch(/verifies only 'v2'/)
+    expect(apiPost).not.toHaveBeenCalled()
+  })
+
+  it('refuses a tampered lottery transaction and never signs or submits it', async () => {
+    const bytes = Buffer.from(lottery.response.transaction_base64, 'base64')
+    bytes[bytes.length - 3] ^= 0xff // inside the seed commitment
+    serve(lottery, { ...lottery.response, transaction_base64: bytes.toString('base64') })
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems.join(' ')).toMatch(/Operator signature does not verify/)
+    expect(submitted()).toHaveLength(0)
+  })
+
+  it('holds max_fee_bps to the fee create_mission quoted (mission.solana_quoted_fee_bps)', async () => {
+    serve(plain)
+    mission.solana_quoted_fee_bps = 25
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.fee_quote_source).toMatch(/solana_quoted_fee_bps/)
+    expect(r.problems.join(' ')).toMatch(/expected the quoted fee rate 25/)
+    expect(submitted()).toHaveLength(0)
+  })
+
+  it('lets expected_max_fee_bps state the quote explicitly', async () => {
+    serve(plain)
+    mission.solana_quoted_fee_bps = 25
+    const r: any = await handleSolanaTool('fund_solana_mission', {
+      mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT, expected_max_fee_bps: 0, dry_run: true,
+    })
+    expect(r).toMatchObject({ dry_run: true, verified: true, fee_quote_source: 'expected_max_fee_bps argument' })
+  })
+
+  it('falls back to the on-chain fee for a mission with no recorded quote', async () => {
+    serve(plain)
+    delete mission.solana_quoted_fee_bps
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT, dry_run: true })
+    expect(r).toMatchObject({ verified: true })
+    expect(r.fee_quote_source).toMatch(/on-chain Config\.fee_bps/)
+  })
+
+  it('refuses a lottery when Config cannot be read from the cluster', async () => {
+    serve(lottery)
+    const real = globalThis.fetch as any
+    vi.stubGlobal('fetch', vi.fn(async (url: string, init: { body: string }) =>
+      JSON.parse(init.body).params[0] === MINT ? real(url, init) : Promise.reject(new Error('fetch failed'))))
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems.join(' ')).toMatch(/Config\.operator could not be read/)
+    expect(submitted()).toHaveLength(0)
+  })
+
+  it('refuses, before building anything, a program id the API reports but this server does not pin', async () => {
+    config.program_id = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems[0]).toMatch(/but this server pins 2CPC5V63/)
+    expect(apiPost).not.toHaveBeenCalled()
+  })
+
+  it('refuses an unpinned cluster unless both the program and the RPC are pinned locally', async () => {
+    config.cluster = 'localnet'
+    serve(plain)
+    const args = { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT, dry_run: true }
+    const r: any = await handleSolanaTool('fund_solana_mission', args)
+    expect(r.problems.join(' ')).toMatch(/no escrow program is pinned for cluster "localnet"/)
+    process.env.SOLO_SOLANA_PROGRAM_ID = PROGRAM_ID
+    try {
+      // The API's rpc_url could serve a fake mint with other decimals: not used.
+      const noRpc: any = await handleSolanaTool('fund_solana_mission', args)
+      expect(noRpc.problems).toEqual([expect.stringMatching(/set SOLO_SOLANA_RPC_URL/)])
+      expect(apiPost).not.toHaveBeenCalled()
+      process.env.SOLO_SOLANA_RPC_URL = 'https://my.rpc'
+      const ok: any = await handleSolanaTool('fund_solana_mission', args)
+      expect(ok).toMatchObject({ dry_run: true, verified: true })
+      expect((globalThis.fetch as any).mock.calls.every(([url]: [string]) => url === 'https://my.rpc')).toBe(true)
+    } finally {
+      delete process.env.SOLO_SOLANA_PROGRAM_ID
+      delete process.env.SOLO_SOLANA_RPC_URL
+    }
+  })
+
+  it('scales expected_budget by the decimals on chain, not the ones the API reports', async () => {
+    // The API claims 9 decimals: trusting it would turn "0.01" into 10,000,000 raw units and
+    // refuse the genuine 10,000-unit transaction (or accept a 1000x larger one).
+    config.decimals = { TEST_USDC: 9 }
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT, dry_run: true })
+    expect(r).toMatchObject({ verified: true, would_escrow: `0.01 (10000 raw) of ${MINT}` })
+  })
+
+  it('refuses when the mint decimals cannot be read', async () => {
+    rpcFails = true
+    serve(plain)
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems[0]).toMatch(/cannot read mint .* decimals from chain/)
+    expect(apiPost).not.toHaveBeenCalled()
+  })
+
+  it('names the program error when the chain rejects the funding', async () => {
+    serve(plain)
+    apiPost.mockImplementation(async (path: string) => {
+      if (path.endsWith('/funding-transaction')) return structuredClone(plain.response)
+      throw apiError(400, { message: 'funding transaction failed: ... custom program error: 0x17f4' })
+    })
+    const r: any = await handleSolanaTool('fund_solana_mission', { mission_id: 'm1', expected_budget: 0.01, expected_mint: MINT })
+    expect(r).toMatchObject({ funded: false, signed: true, program_error: { code: 6132, name: 'FeeAboveSponsorMax' } })
+  })
+})
+
+describe('refund_solana_mission', () => {
+  const now = Math.floor(Date.now() / 1000)
+  const sponsor = new PublicKey(lottery.sponsor)
+  const refundTx = (disc: readonly number[]) => {
+    const ata = PublicKey.findProgramAddressSync(
+      [sponsor.toBuffer(), new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA').toBuffer(), new PublicKey(MINT).toBuffer()],
+      new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'),
+    )[0]
+    const program = new PublicKey(PROGRAM_ID)
+    const k = (pubkey: PublicKey, isSigner = false, isWritable = false) => ({ pubkey, isSigner, isWritable })
+    const pda = (s: string) => PublicKey.findProgramAddressSync([Buffer.from(s)], program)[0]
+    const t = new Transaction({ feePayer: sponsor, recentBlockhash: Transaction.from(Buffer.from(plain.response.transaction_base64, 'base64')).recentBlockhash! })
+    t.add(new TransactionInstruction({
+      programId: program,
+      keys: [k(sponsor, true), k(pda('config')), k(pda('task-x'), false, true), k(pda('vault-x'), false, true), k(ata, false, true),
+        k(new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')), k(pda('__event_authority')), k(program)],
+      data: Buffer.from(disc),
+    }))
+    return t.serialize({ requireAllSignatures: false, verifySignatures: false }).toString('base64')
+  }
+  const refundPosts = () => apiPost.mock.calls.filter(([p]) => String(p).endsWith('/refund-transaction'))
+
+  beforeEach(() => {
+    mission = { token_address: MINT, onchain_status: 'funded', qualify_deadline: now + 3600, settlement_deadline: now + 7200 }
+  })
+
+  it('refuses a cancel from qualify_deadline on without building or signing it', async () => {
+    mission.qualify_deadline = now - 1
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'cancel' })
+    expect(r).toMatchObject({ refunded: false, rejected_by: 'client', action: 'cancel' })
+    expect(r.message).toMatch(/TooLateToCancel/)
+    expect(r.what_to_do).toMatch(/emergency_refund/)
+    expect(refundPosts()).toHaveLength(0)
+  })
+
+  it('surfaces a backend refusal with the actions that remain', async () => {
+    apiPost.mockRejectedValue(apiError(409, {
+      message: 'the qualify deadline has passed — cancel is no longer available',
+      available_actions: ['emergency_refund'],
+    }))
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'cancel' })
+    expect(r).toMatchObject({ rejected_by: 'backend', status: 409, available_actions: ['emergency_refund'] })
+    expect(r.cancel_cutoff).toBe(new Date((now + 3600) * 1000).toISOString())
+  })
+
+  it('surfaces an on-chain TooLateToCancel from confirm-refund', async () => {
+    apiPost.mockImplementation(async (path: string) => {
+      if (path.endsWith('/refund-transaction')) return { action: 'cancel', task_id: '7', transaction_base64: refundTx(DISCRIMINATORS.cancel_task) }
+      throw apiError(409, {
+        message: "the escrow program rejects cancel from qualify_deadline on (TooLateToCancel). The mission settles normally, or use action: 'emergency_refund' after settlement_deadline.",
+        available_actions: ['emergency_refund'],
+      })
+    })
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'cancel' })
+    expect(r).toMatchObject({
+      refunded: false,
+      rejected_by: 'chain',
+      program_error: { code: 6125, name: 'TooLateToCancel' },
+      available_actions: ['emergency_refund'],
+    })
+  })
+
+  it('names an early emergency_refund rejected on chain', async () => {
+    apiPost.mockImplementation(async (path: string) => {
+      if (path.endsWith('/refund-transaction')) return { action: 'emergency_refund', task_id: '7', transaction_base64: refundTx(DISCRIMINATORS.emergency_refund) }
+      throw apiError(400, { message: 'refund transaction failed: Error processing Instruction 0: custom program error: 0x1780' })
+    })
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'emergency_refund' })
+    expect(r).toMatchObject({ rejected_by: 'chain', program_error: { name: 'TooEarlyForEmergencyRefund' } })
+    expect(r.what_to_do).toMatch(/settlement_deadline has passed/)
+  })
+
+  it('signs and confirms a verified refund', async () => {
+    apiPost.mockImplementation(async (path: string, body: any) => {
+      if (path.endsWith('/refund-transaction')) return { action: 'cancel', task_id: '7', transaction_base64: refundTx(DISCRIMINATORS.cancel_task) }
+      const t = parseWireTransaction(Buffer.from(body.signed_transaction, 'base64'))
+      expect(ed25519Verify(t.signatures[0], t.message, lottery.sponsor)).toBe(true)
+      return { action: 'cancel', signature: 'sig', onchain_status: 'cancelled' }
+    })
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'cancel' })
+    expect(r).toMatchObject({ refunded: true, verified: true, onchain_status: 'cancelled' })
+  })
+
+  it('refuses a refund for a program the API reports but this server does not pin, before building it', async () => {
+    config.program_id = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1', action: 'cancel' })
+    expect(r.refused_to_sign).toBe(true)
+    expect(r.problems.join(' ')).toMatch(/this server pins/)
+    expect(refundPosts()).toHaveLength(0)
+  })
+
+  it('explains the cancel cut-off when asked what is available', async () => {
+    apiPost.mockRejectedValue(apiError(409, { message: "claim refund requires onchain_status 'refundable'", available_actions: ['cancel'] }))
+    const r: any = await handleSolanaTool('refund_solana_mission', { mission_id: 'm1' })
+    expect(r.available_actions).toEqual(['cancel'])
+    expect(r.note).toMatch(/refused on chain from qualify_deadline on/)
+  })
+})