@projectsolo/solo-mission-mcp 0.21.14 → 0.22.1

package/src/solana/deployment.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The program id every check hangs off must not come from the API being checked.
+ */
+import { describe, it, expect, afterEach } from 'vitest'
+import { PINNED_DEPLOYMENTS, resolvePinnedProgram, resolveTrustedRpc, solanaRpcUrl } from './deployment'
+
+const DEVNET = '2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a'
+
+afterEach(() => {
+  delete process.env.SOLO_SOLANA_PROGRAM_ID
+  delete process.env.SOLO_SOLANA_RPC_URL
+})
+
+describe('resolvePinnedProgram', () => {
+  it('pins the devnet escrow program', () => {
+    expect(PINNED_DEPLOYMENTS.devnet.program_id).toBe(DEVNET)
+    expect(resolvePinnedProgram({ cluster: 'devnet', program_id: DEVNET })).toEqual({ program_id: DEVNET })
+  })
+
+  it('refuses a program id the API reports for a pinned cluster when it differs', () => {
+    const r = resolvePinnedProgram({ cluster: 'devnet', program_id: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' })
+    expect(r).toEqual({ problem: expect.stringMatching(/but this server pins 2CPC5V63/) })
+  })
+
+  it('refuses a cluster nothing is pinned for', () => {
+    expect(resolvePinnedProgram({ cluster: 'mainnet-beta', program_id: DEVNET })).toEqual({
+      problem: expect.stringMatching(/no escrow program is pinned for cluster "mainnet-beta"/),
+    })
+  })
+
+  it('lets SOLO_SOLANA_PROGRAM_ID pin a program, and still requires the API to agree', () => {
+    process.env.SOLO_SOLANA_PROGRAM_ID = DEVNET
+    expect(resolvePinnedProgram({ cluster: 'localnet', program_id: DEVNET })).toEqual({ program_id: DEVNET })
+    expect(resolvePinnedProgram({ cluster: 'devnet', program_id: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' })).toEqual({
+      problem: expect.stringMatching(/\(SOLO_SOLANA_PROGRAM_ID\)/),
+    })
+  })
+})
+
+describe('resolveTrustedRpc', () => {
+  it('uses SOLO_SOLANA_RPC_URL or the pinned endpoint, never the API', () => {
+    expect(resolveTrustedRpc({ cluster: 'devnet' })).toEqual({ rpc_url: 'https://api.devnet.solana.com' })
+    // Pinning a program for an unknown cluster is not enough: the API's rpc_url could serve a
+    // fake mint or Config.
+    process.env.SOLO_SOLANA_PROGRAM_ID = DEVNET
+    expect(resolveTrustedRpc({ cluster: 'mainnet-beta' })).toEqual({
+      problem: expect.stringMatching(/set SOLO_SOLANA_RPC_URL/),
+    })
+    process.env.SOLO_SOLANA_RPC_URL = 'https://my.rpc'
+    expect(resolveTrustedRpc({ cluster: 'mainnet-beta' })).toEqual({ rpc_url: 'https://my.rpc' })
+  })
+})
+
+describe('solanaRpcUrl (display-only reads)', () => {
+  it('prefers SOLO_SOLANA_RPC_URL, then the pinned endpoint, then the API', () => {
+    expect(solanaRpcUrl({ cluster: 'devnet', rpc_url: 'https://api.example' })).toBe('https://api.devnet.solana.com')
+    expect(solanaRpcUrl({ cluster: 'localnet', rpc_url: 'http://127.0.0.1:8899' })).toBe('http://127.0.0.1:8899')
+    process.env.SOLO_SOLANA_RPC_URL = 'https://my.rpc'
+    expect(solanaRpcUrl({ cluster: 'devnet', rpc_url: 'https://api.example' })).toBe('https://my.rpc')
+  })
+})

package/src/solana/deployment.ts

@@ -0,0 +1,89 @@
+/**
+ * The escrow deployments this package trusts, pinned in code.
+ *
+ * `/agent/solana/config` comes from the same backend that builds the transaction the agent is asked
+ * to sign. If the program id came from there too, a backend could name a program of its own —
+ * with its own Config and its own "Operator" — and every derived address, the co-signer check and
+ * the "pinned" program check would agree with it. The API's program id is therefore only accepted
+ * when it equals the one pinned here for the cluster it reports.
+ *
+ * A deployment this version does not know (localnet, or a new mainnet program before this package
+ * is updated) needs `SOLO_SOLANA_PROGRAM_ID` set to the program id the operator of this server
+ * trusts. Until then, funding and refunds are refused rather than signed on the API's word.
+ *
+ * The same goes for the RPC endpoint the checked reads use (mint decimals, the escrow Config): it
+ * is `SOLO_SOLANA_RPC_URL` or the pinned cluster's public endpoint, never the API's `rpc_url`. A
+ * backend-chosen RPC could serve a fake mint with other decimals and scale the budget the agent
+ * approves.
+ */
+
+export interface PinnedDeployment {
+  cluster: string;
+  program_id: string;
+  /** Public RPC endpoint for reads the server checks itself (overridable). */
+  rpc_url: string;
+}
+
+export const PINNED_DEPLOYMENTS: Readonly<Record<string, PinnedDeployment>> = {
+  // solo-escrow-solana u1.1.0 on devnet (the live private beta).
+  devnet: {
+    cluster: 'devnet',
+    program_id: '2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a',
+    rpc_url: 'https://api.devnet.solana.com',
+  },
+};
+
+/**
+ * The program id to verify against: `SOLO_SOLANA_PROGRAM_ID` if set, else the pinned id for the
+ * reported cluster. The API's `program_id` must equal it.
+ */
+export function resolvePinnedProgram(cfg: {
+  cluster?: string;
+  program_id: string;
+}): { program_id: string } | { problem: string } {
+  const override = (process.env.SOLO_SOLANA_PROGRAM_ID ?? '').trim();
+  const pinned = override || PINNED_DEPLOYMENTS[cfg.cluster ?? '']?.program_id;
+  if (!pinned) {
+    return {
+      problem:
+        `no escrow program is pinned for cluster ${JSON.stringify(cfg.cluster)} — set ` +
+        'SOLO_SOLANA_PROGRAM_ID to the program id you trust, or use a version of this package ' +
+        'that pins it',
+    };
+  }
+  if (cfg.program_id !== pinned) {
+    return {
+      problem:
+        `the API reports escrow program ${cfg.program_id} for cluster ${JSON.stringify(cfg.cluster)}, ` +
+        `but this server pins ${pinned}${override ? ' (SOLO_SOLANA_PROGRAM_ID)' : ''} — refusing to ` +
+        'sign for a program it does not trust',
+    };
+  }
+  return { program_id: pinned };
+}
+
+/**
+ * The RPC endpoint for reads that feed a signing decision — mint decimals and the escrow Config:
+ * `SOLO_SOLANA_RPC_URL` if set, else the pinned cluster's public endpoint. Never the API's
+ * `rpc_url`, so an unpinned cluster needs `SOLO_SOLANA_RPC_URL`.
+ */
+export function resolveTrustedRpc(cfg: { cluster?: string }): { rpc_url: string } | { problem: string } {
+  const rpc = (process.env.SOLO_SOLANA_RPC_URL ?? '').trim() || PINNED_DEPLOYMENTS[cfg.cluster ?? '']?.rpc_url;
+  if (!rpc) {
+    return {
+      problem:
+        `no RPC endpoint is pinned for cluster ${JSON.stringify(cfg.cluster)} — set SOLO_SOLANA_RPC_URL ` +
+        'to an endpoint you trust; the API-reported rpc_url is not used for reads that decide what to sign',
+    };
+  }
+  return { rpc_url: rpc };
+}
+
+/**
+ * The RPC endpoint for display-only reads (get_solana_wallet balances): the trusted one when there
+ * is one, else the `rpc_url` the API reports.
+ */
+export function solanaRpcUrl(cfg: { cluster?: string; rpc_url: string }): string {
+  const trusted = resolveTrustedRpc(cfg);
+  return 'rpc_url' in trusted ? trusted.rpc_url : cfg.rpc_url;
+}

package/src/solana/escrowErrors.ts

@@ -0,0 +1,78 @@
+/**
+ * The escrow program errors an agent can hit while funding or refunding, named and explained.
+ *
+ * A failed submission surfaces as `custom program error: 0x17ed` (or, in the program logs, as
+ * `Error Code: TooLateToCancel. Error Number: 6125.`), which tells an agent nothing about what to
+ * do next. Codes are from solo-escrow-solana u1.1.0 `idl/solo_escrow.json` and are checked against
+ * the vendored IDL excerpt in `verify.test.ts`.
+ */
+
+export interface EscrowErrorInfo {
+  code: number;
+  name: string;
+  what_to_do: string;
+}
+
+export const ESCROW_ERRORS: Record<number, Omit<EscrowErrorInfo, 'code'>> = {
+  6012: {
+    name: 'SettlementWindowTooShort',
+    what_to_do:
+      'settlement_deadline must be at least qualify_deadline + min_review_window + the finalize ' +
+      'grace. Create a new mission with a longer work_duration_hours.',
+  },
+  6016: {
+    name: 'TooEarlyForEmergencyRefund',
+    what_to_do: 'emergency_refund opens only once settlement_deadline has passed. Retry after it.',
+  },
+  6026: {
+    name: 'RefundAlreadyClaimed',
+    what_to_do: 'the refundable amount was already claimed — nothing is left to refund.',
+  },
+  6027: { name: 'NothingToRefund', what_to_do: 'the task holds nothing refundable.' },
+  6124: {
+    name: 'LotteryRequiresOperator',
+    what_to_do:
+      'a lottery create_task needs the platform Operator\'s co-signature over the exact message. ' +
+      'Request a fresh funding transaction and sign it unchanged.',
+  },
+  6125: {
+    name: 'TooLateToCancel',
+    what_to_do:
+      'cancel is refused on chain from qualify_deadline on. Let the mission settle, or use ' +
+      'emergency_refund once settlement_deadline has passed without a settlement.',
+  },
+  6132: {
+    name: 'FeeAboveSponsorMax',
+    what_to_do:
+      'the program\'s fee rose above the max_fee_bps you were quoted, so the escrow refused to ' +
+      'charge more. Cancel the mission (cancel_mission) and create a new one for a fresh quote.',
+  },
+  6133: {
+    name: 'QualifyDeadlineTooFar',
+    what_to_do: 'qualify_deadline may be at most 180 days ahead. Create a new mission with a shorter hiring window.',
+  },
+  6134: {
+    name: 'SettlementDeadlineTooFar',
+    what_to_do:
+      'settlement_deadline may be at most 90 days after qualify_deadline. Create a new mission with a ' +
+      'shorter work window.',
+  },
+};
+
+/** Finds a known escrow error in an RPC, backend or program-log message. */
+export function escrowErrorFromMessage(message: string | undefined | null): EscrowErrorInfo | null {
+  if (!message) return null;
+  const candidates: number[] = [];
+  for (const m of message.matchAll(/custom program error: 0x([0-9a-f]+)/gi)) {
+    candidates.push(parseInt(m[1], 16));
+  }
+  for (const m of message.matchAll(/Error Number: (\d+)/g)) candidates.push(Number(m[1]));
+  for (const code of candidates) {
+    const info = ESCROW_ERRORS[code];
+    if (info) return { code, ...info };
+  }
+  for (const [code, info] of Object.entries(ESCROW_ERRORS)) {
+    if (new RegExp(`\\b${info.name}\\b`).test(message)) return { code: Number(code), ...info };
+  }
+  return null;
+}

package/src/solana/fixtures/config-account.json

@@ -0,0 +1,6 @@
+{
+  "note": "Snapshot of the devnet escrow Config account (getAccountInfo, base64) taken when the v2 fixtures were built.",
+  "address": "7HXi3y1i3p4LVV3WGV6R4CM7waxNAXrjCX6SRSUcjEca",
+  "owner": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+  "data_base64": "mwyq4B76zIKW202tPDdOkYY2QQSUHVPaQPTp1RCoPYDbrYr3viyq6AZ/1+SgwJ+6qgP06ONyeuY1+/CpwGlQo1QkW8/pmAQoBn/X5KDAn7qqA/To43J65jX78KnAaVCjVCRbz+mYBCgGf9fkoMCfuqoD9OjjcnrmNfvwqcBpUKNUJFvP6ZgEKAAACgAAAAAAAAAADgQAAAAAAAD+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+}

package/src/solana/fixtures/funding-transaction-v2-lottery.json

@@ -0,0 +1,49 @@
+{
+  "note": "Real v2 lottery (Operator co-signed) funding response, built on devnet by solo_firebase main 358df1e's own builders (describeFundingTransactionV2 + buildOperatorCoSignedTransaction) for the never-funded test sponsor in test-keypair.pubkey. Never submitted.",
+  "response": {
+    "task_id": "1038",
+    "accounts": {
+      "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+      "config": "7HXi3y1i3p4LVV3WGV6R4CM7waxNAXrjCX6SRSUcjEca",
+      "task": "HxGz9PPRknrjYMpEZBJFygbTsabyBJMJ5V7ieUz38WE5",
+      "vault": "Eg8Hj4oTRoy7xtA4vXpCRPyhvbBY3jCuM8otWsE5GSDN",
+      "whitelist": "97xTnhyGDmJkZsoNtcm7gjV48yfaBstijFDqiUFru7Jr",
+      "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E",
+      "sponsor": "GXkK4gbmGPGFmB7vobHeY82ktbAw9VPnHZJits1P2Qjw",
+      "sponsor_token_account": "BT5mmmDkqBDkm1LzhA9NaiEg8iLeVnyVoQztYVwNn51V"
+    },
+    "declared": {
+      "budget": "10000",
+      "base_pool": "5000",
+      "lottery_winner_count": 1,
+      "lottery_prize_per_winner": "2000",
+      "qualify_deadline": "1790746898",
+      "settlement_deadline": "1790754098",
+      "seed_commit": "011d2003d45b7077279624af04893449e3c9b9ca7af24f0b66392a51d436818d",
+      "max_fee_bps": 0,
+      "operator_cosigned": true
+    },
+    "transaction_base64": "AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA+UiU+WXJ0VjmtoyW2tOvlwe7hgrpcUWRt9cqkEtbxwbKD5pDAVWMZY/sZJfM85vFSRPplFA0JKr+VFvOou6QLAgEGDOa/s1hzUJIzu8ouno08w0xOKRpCxclFPd0LvIgaV/R+Bn/X5KDAn7qqA/To43J65jX78KnAaVCjVCRbz+mYBChdYiLKQxJO7f2wf2Zen2PiT6lZjCsYDNgDlIVDr9MRw5tDXa3ipzH/EOFvMWR2jqvY2kMEzBeqGI0KGtvR061Eyy3SlIlwIvFkjG6ewkxG4v6P+I3ZdywRzup40Q+5ZQn75AKI8/MlPZYADjzBWvE1+rf2jG+psyfR2BHLVNJUIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEcYq0VKhiU4ktY09qsij+rs+4b6Yt6VTnLfH9HKPyLcmlwpi3dEh8irDXYuBeelr9ra81Js5JF779Op1Y4ebznilsPINlCy+dlo0+WnBLgmlHMRNxcGJTTgj45SCbOkTxBwQrSJibjN7eiWjtGYLfQwfBf0s2Q6KtbBFFOSJw2EG3fbh12Whk9nL4UbO63msHLSF7V9bN5E6jPWFfv8AqTR8me0KWjNV4HmGCSl7Z0eutyD9g5zgRFJDnDscS0FNAQcMAAIJCgUEAwsGAQgHVsJQBrTofzCrECcAAAAAAACIEwAAAAAAAAEAAADQBwAAAAAAABKhvGoAAAAAMr28agAAAAABHSAD1FtwdyeWJK8EiTRJ48m5ynryTwtmOSpR1DaBjQAA",
+    "blockhash": "4XtQ6pTDn6ypSdgmL9CYSj5AogBV8JkDMGPoCwMf8YXn",
+    "valid_until_slot": 493031885,
+    "message_sha256": "307bc3325cdb063f6e4ae32dd56831784029b71c4d202bc10ee35437c97ec8ff",
+    "escrow_interface": "v2",
+    "note": "co-signed by the platform Operator (required for a lottery): add your signature and submit exactly these bytes through confirm-funding — any change invalidates the co-signature. The blockhash expires in about 60-90 seconds; request a fresh transaction if signing takes longer"
+  },
+  "mission": {
+    "token_address": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E",
+    "onchain_status": "pending_funding",
+    "budget_raw": "10000",
+    "reward_per_human_raw": "1000",
+    "max_humans": 5,
+    "lottery_winner_count": 1,
+    "lottery_prize_per_winner_raw": "2000",
+    "qualify_deadline": 1790746898,
+    "settlement_deadline": 1790754098,
+    "seed_commit": "0x011d2003d45b7077279624af04893449e3c9b9ca7af24f0b66392a51d436818d",
+    "solana_quoted_fee_bps": 0
+  },
+  "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+  "sponsor": "GXkK4gbmGPGFmB7vobHeY82ktbAw9VPnHZJits1P2Qjw",
+  "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E"
+}

package/src/solana/fixtures/funding-transaction-v2-plain.json

@@ -0,0 +1,46 @@
+{
+  "note": "Real v2 non-lottery funding response, built on devnet by solo_firebase main 358df1e's own builders (describeFundingTransactionV2 + buildUnsignedTransaction) for the never-funded test sponsor in test-keypair.pubkey. Never submitted.",
+  "response": {
+    "task_id": "1038",
+    "accounts": {
+      "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+      "config": "7HXi3y1i3p4LVV3WGV6R4CM7waxNAXrjCX6SRSUcjEca",
+      "task": "HxGz9PPRknrjYMpEZBJFygbTsabyBJMJ5V7ieUz38WE5",
+      "vault": "Eg8Hj4oTRoy7xtA4vXpCRPyhvbBY3jCuM8otWsE5GSDN",
+      "whitelist": "97xTnhyGDmJkZsoNtcm7gjV48yfaBstijFDqiUFru7Jr",
+      "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E",
+      "sponsor": "GXkK4gbmGPGFmB7vobHeY82ktbAw9VPnHZJits1P2Qjw",
+      "sponsor_token_account": "BT5mmmDkqBDkm1LzhA9NaiEg8iLeVnyVoQztYVwNn51V"
+    },
+    "declared": {
+      "budget": "10000",
+      "base_pool": "10000",
+      "lottery_winner_count": 0,
+      "lottery_prize_per_winner": "0",
+      "qualify_deadline": "1790746899",
+      "settlement_deadline": "1790754099",
+      "seed_commit": "86b1c32bea6da1cb166282d19ff55af7001d941c28f05a31cdfc540a4a791741",
+      "max_fee_bps": 0,
+      "operator_cosigned": false
+    },
+    "transaction_base64": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAYL5r+zWHNQkjO7yi6ejTzDTE4pGkLFyUU93Qu8iBpX9H5dYiLKQxJO7f2wf2Zen2PiT6lZjCsYDNgDlIVDr9MRw5tDXa3ipzH/EOFvMWR2jqvY2kMEzBeqGI0KGtvR061Eyy3SlIlwIvFkjG6ewkxG4v6P+I3ZdywRzup40Q+5ZQn75AKI8/MlPZYADjzBWvE1+rf2jG+psyfR2BHLVNJUIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEcYq0VKhiU4ktY09qsij+rs+4b6Yt6VTnLfH9HKPyLcmlwpi3dEh8irDXYuBeelr9ra81Js5JF779Op1Y4ebznilsPINlCy+dlo0+WnBLgmlHMRNxcGJTTgj45SCbOkTxBwQrSJibjN7eiWjtGYLfQwfBf0s2Q6KtbBFFOSJw2EG3fbh12Whk9nL4UbO63msHLSF7V9bN5E6jPWFfv8AqTR8me0KWjNV4HmGCSl7Z0eutyD9g5zgRFJDnDscS0FNAQYMAAEICQQDAgoFBgcGVsJQBrTofzCrECcAAAAAAAAQJwAAAAAAAAAAAAAAAAAAAAAAABOhvGoAAAAAM728agAAAACGscMr6m2hyxZigtGf9Vr3AB2UHCjwWjHN/FQKSnkXQQAA",
+    "blockhash": "4XtQ6pTDn6ypSdgmL9CYSj5AogBV8JkDMGPoCwMf8YXn",
+    "valid_until_slot": 493031885,
+    "escrow_interface": "v2",
+    "note": "blockhash expires in about 60-90 seconds; request a fresh transaction if signing takes longer"
+  },
+  "mission": {
+    "token_address": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E",
+    "onchain_status": "pending_funding",
+    "budget_raw": "10000",
+    "reward_per_human_raw": "2000",
+    "max_humans": 5,
+    "qualify_deadline": 1790746899,
+    "settlement_deadline": 1790754099,
+    "seed_commit": "0x86b1c32bea6da1cb166282d19ff55af7001d941c28f05a31cdfc540a4a791741",
+    "solana_quoted_fee_bps": 0
+  },
+  "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+  "sponsor": "GXkK4gbmGPGFmB7vobHeY82ktbAw9VPnHZJits1P2Qjw",
+  "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E"
+}