@agent-fuel/sdk 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -63,7 +63,8 @@ function decodeCreditVault(pubkey, raw) {
     balance: total_deposited - total_withdrawn - total_spent + total_claimed,
     frozen: raw.frozen,
     created_slot: bnToNum(raw.createdSlot),
-    last_active_slot: bnToNum(raw.lastActiveSlot)
+    last_active_slot: bnToNum(raw.lastActiveSlot),
+    pending_count: bnToNum(raw.pendingCount)
   };
 }
 var DEFAULT_PUBKEY = web3_js.PublicKey.default.toBase58();
@@ -1953,6 +1954,200 @@ var credit_vault_default = {
     repository: "https://github.com/TODO/agent_fuel"
   },
   instructions: [
+    {
+      name: "approve_spend",
+      discriminator: [
+        248,
+        201,
+        151,
+        15,
+        28,
+        162,
+        112,
+        90
+      ],
+      accounts: [
+        {
+          name: "owner",
+          writable: true,
+          signer: true,
+          relations: [
+            "vault"
+          ]
+        },
+        {
+          name: "vault",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "owner"
+              },
+              {
+                kind: "account",
+                path: "vault.agent",
+                account: "CreditVault"
+              }
+            ]
+          }
+        },
+        {
+          name: "policy",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  111,
+                  108,
+                  105,
+                  99,
+                  121
+                ]
+              },
+              {
+                kind: "account",
+                path: "vault"
+              }
+            ]
+          }
+        },
+        {
+          name: "pending_spend",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  101,
+                  110,
+                  100,
+                  105,
+                  110,
+                  103
+                ]
+              },
+              {
+                kind: "account",
+                path: "vault"
+              },
+              {
+                kind: "account",
+                path: "pending_spend.nonce",
+                account: "PendingSpend"
+              }
+            ]
+          }
+        },
+        {
+          name: "vault_token_account",
+          writable: true
+        },
+        {
+          name: "service_token_account",
+          writable: true
+        },
+        {
+          name: "token_program",
+          address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        }
+      ],
+      args: []
+    },
+    {
+      name: "cancel_spend",
+      discriminator: [
+        122,
+        254,
+        101,
+        132,
+        241,
+        232,
+        205,
+        179
+      ],
+      accounts: [
+        {
+          name: "owner",
+          writable: true,
+          signer: true,
+          relations: [
+            "vault"
+          ]
+        },
+        {
+          name: "vault",
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "owner"
+              },
+              {
+                kind: "account",
+                path: "vault.agent",
+                account: "CreditVault"
+              }
+            ]
+          }
+        },
+        {
+          name: "pending_spend",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  101,
+                  110,
+                  100,
+                  105,
+                  110,
+                  103
+                ]
+              },
+              {
+                kind: "account",
+                path: "vault"
+              },
+              {
+                kind: "account",
+                path: "pending_spend.nonce",
+                account: "PendingSpend"
+              }
+            ]
+          }
+        }
+      ],
+      args: []
+    },
     {
       name: "claim",
       discriminator: [
@@ -2359,6 +2554,104 @@ var credit_vault_default = {
       ],
       args: []
     },
+    {
+      name: "request_spend",
+      discriminator: [
+        127,
+        12,
+        23,
+        75,
+        137,
+        178,
+        148,
+        71
+      ],
+      accounts: [
+        {
+          name: "agent",
+          writable: true,
+          signer: true,
+          relations: [
+            "vault"
+          ]
+        },
+        {
+          name: "vault",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "vault.owner",
+                account: "CreditVault"
+              },
+              {
+                kind: "account",
+                path: "vault.agent",
+                account: "CreditVault"
+              }
+            ]
+          }
+        },
+        {
+          name: "service_token_account",
+          docs: [
+            "The recipient token account. We only need it for its `owner` field",
+            "(the service pubkey we record in PendingSpend); mint constraint is",
+            "belt-and-suspenders since `approve_spend` re-checks both."
+          ]
+        },
+        {
+          name: "pending_spend",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  101,
+                  110,
+                  100,
+                  105,
+                  110,
+                  103
+                ]
+              },
+              {
+                kind: "account",
+                path: "vault"
+              },
+              {
+                kind: "account",
+                path: "vault.pending_count",
+                account: "CreditVault"
+              }
+            ]
+          }
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "amount_usdc",
+          type: "u64"
+        }
+      ]
+    },
     {
       name: "spend",
       discriminator: [
@@ -2684,6 +2977,19 @@ var credit_vault_default = {
         70
       ]
     },
+    {
+      name: "PendingSpend",
+      discriminator: [
+        193,
+        205,
+        85,
+        66,
+        25,
+        3,
+        67,
+        134
+      ]
+    },
     {
       name: "SpendPolicy",
       discriminator: [
@@ -2738,6 +3044,32 @@ var credit_vault_default = {
         161
       ]
     },
+    {
+      name: "SpendRejected",
+      discriminator: [
+        22,
+        233,
+        208,
+        109,
+        202,
+        231,
+        175,
+        22
+      ]
+    },
+    {
+      name: "SpendRequested",
+      discriminator: [
+        144,
+        207,
+        254,
+        247,
+        81,
+        146,
+        84,
+        87
+      ]
+    },
     {
       name: "Spent",
       discriminator: [
@@ -2854,6 +3186,16 @@ var credit_vault_default = {
       code: 6009,
       name: "PostPayDisabled",
       msg: "Post-pay claims are disabled for this vault"
+    },
+    {
+      code: 6010,
+      name: "PendingSpendVaultMismatch",
+      msg: "Pending spend belongs to a different vault"
+    },
+    {
+      code: 6011,
+      name: "PendingNonceOverflow",
+      msg: "Pending spend counter would overflow"
     }
   ],
   types: [
@@ -2942,12 +3284,22 @@ var credit_vault_default = {
             name: "bump",
             type: "u8"
           },
+          {
+            name: "pending_count",
+            docs: [
+              "Monotonic counter used as a PDA seed for PendingSpend accounts so",
+              "every approval request gets a unique deterministic address.",
+              "Borrowed 8 bytes from the original 64-byte padding so the account",
+              "size stays at `ACCOUNT_SIZE` and existing vaults need no migration."
+            ],
+            type: "u64"
+          },
           {
             name: "_padding",
             type: {
               array: [
                 "u8",
-                64
+                56
               ]
             }
           }
@@ -2982,6 +3334,65 @@ var credit_vault_default = {
         ]
       }
     },
+    {
+      name: "PendingSpend",
+      docs: [
+        "A spend request that exceeded one of the policy's rate limits. The agent",
+        "creates this account by calling `request_spend`; the owner reviews from",
+        "the mobile Alerts tab and either calls `approve_spend` (PDA-signed CPI",
+        "transfer, account closed) or `cancel_spend` (account closed, no transfer).",
+        "",
+        'Seeded by `["pending", vault, nonce_le]` where `nonce` is the value of',
+        "`vault.pending_count` at request time, so each request has a unique",
+        "deterministic address that both the agent and the owner can derive."
+      ],
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "vault",
+            type: "pubkey"
+          },
+          {
+            name: "agent",
+            type: "pubkey"
+          },
+          {
+            name: "service",
+            docs: [
+              "Owner of the destination token account (mirrors how `Spent` records",
+              "service: `service_token_account.owner`)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "amount_usdc",
+            type: "u64"
+          },
+          {
+            name: "requested_slot",
+            type: "u64"
+          },
+          {
+            name: "nonce",
+            type: "u64"
+          },
+          {
+            name: "bump",
+            type: "u8"
+          },
+          {
+            name: "_padding",
+            type: {
+              array: [
+                "u8",
+                31
+              ]
+            }
+          }
+        ]
+      }
+    },
     {
       name: "PolicyUpdated",
       type: {
@@ -3085,6 +3496,70 @@ var credit_vault_default = {
         ]
       }
     },
+    {
+      name: "SpendRejected",
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "vault",
+            type: "pubkey"
+          },
+          {
+            name: "owner",
+            type: "pubkey"
+          },
+          {
+            name: "pending_spend",
+            type: "pubkey"
+          },
+          {
+            name: "nonce",
+            type: "u64"
+          },
+          {
+            name: "slot",
+            type: "u64"
+          }
+        ]
+      }
+    },
+    {
+      name: "SpendRequested",
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "vault",
+            type: "pubkey"
+          },
+          {
+            name: "agent",
+            type: "pubkey"
+          },
+          {
+            name: "service",
+            type: "pubkey"
+          },
+          {
+            name: "pending_spend",
+            type: "pubkey"
+          },
+          {
+            name: "amount_usdc",
+            type: "u64"
+          },
+          {
+            name: "nonce",
+            type: "u64"
+          },
+          {
+            name: "slot",
+            type: "u64"
+          }
+        ]
+      }
+    },
     {
       name: "Spent",
       type: {
@@ -3269,6 +3744,15 @@ function agentServiceLinkPda(agentProfile, serviceRegistry) {
   );
   return pda;
 }
+function pendingSpendPda(vault, nonce) {
+  const nonceBuf = Buffer.alloc(8);
+  nonceBuf.writeBigUInt64LE(typeof nonce === "bigint" ? nonce : BigInt(nonce));
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [Buffer.from("pending"), toPubkey(vault).toBuffer(), nonceBuf],
+    PROGRAM_IDS.creditVault
+  );
+  return pda;
+}
 function receiptUsedPda(receiptHash) {
   if (receiptHash.length !== 32) {
     throw new Error(`receiptUsedPda expects a 32-byte hash, got ${receiptHash.length}`);
@@ -3289,6 +3773,207 @@ function reputationProgram(provider) {
   return new anchor.Program(reputation_default, provider);
 }
 
+// src/pay.ts
+async function pay(args) {
+  const { agent, service, connection, amountUsdc } = args;
+  const owner = toPubkey(args.owner);
+  if (amountUsdc <= 0) {
+    throw new ZeroAmountError();
+  }
+  if (args.receiptHash.length !== 32) {
+    throw new Error(
+      `pay: receiptHash must be 32 bytes, got ${args.receiptHash.length}`
+    );
+  }
+  const vaultAddr = vaultPda(owner, agent.publicKey);
+  const policyAddr = policyPda(vaultAddr);
+  const provider = buildProvider(connection, agent);
+  const cv = creditVaultProgram(provider);
+  const rep = reputationProgram(provider);
+  const [rawVault, rawPolicy, currentSlot] = await Promise.all([
+    cv.account.creditVault.fetchNullable(vaultAddr),
+    cv.account.spendPolicy.fetchNullable(policyAddr),
+    connection.getSlot()
+  ]);
+  if (!rawVault) throw new AccountNotFoundError(vaultAddr.toBase58());
+  if (!rawPolicy) throw new AccountNotFoundError(policyAddr.toBase58());
+  const vault = decodeCreditVault(vaultAddr, rawVault);
+  const policy = decodeSpendPolicy(policyAddr, rawPolicy);
+  guardSpend({
+    vault,
+    policy,
+    service: service.publicKey,
+    amountUsdc,
+    currentSlot
+  });
+  const serviceTokenAccount = getAssociatedTokenAddress(
+    vault.usdc_mint,
+    service.publicKey
+  );
+  const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
+    agent.publicKey,
+    serviceTokenAccount,
+    service.publicKey,
+    vault.usdc_mint
+  );
+  const agentProfile = agentProfilePda(agent.publicKey);
+  const serviceRegistry = serviceRegistryPda(service.publicKey);
+  const link = agentServiceLinkPda(agentProfile, serviceRegistry);
+  const receipt = receiptUsedPda(args.receiptHash);
+  const spendBuilder = cv.methods.spend(new anchor.BN(amountUsdc)).accounts({
+    agent: agent.publicKey,
+    vault: vaultAddr,
+    policy: policyAddr,
+    vaultTokenAccount: vault.vault_token_account,
+    serviceTokenAccount,
+    tokenProgram: TOKEN_PROGRAM_ID
+  });
+  const recordBuilder = rep.methods.recordPayment(new anchor.BN(amountUsdc), args.receiptHash).accounts({
+    service: service.publicKey,
+    agentProfile,
+    serviceRegistry,
+    agentServiceLink: link,
+    receiptUsed: receipt,
+    systemProgram: web3_js.SystemProgram.programId
+  });
+  const spendIx = await spendBuilder.instruction();
+  const recordIx = await recordBuilder.instruction();
+  const tx = new web3_js.Transaction().add(createAtaIx, spendIx, recordIx);
+  try {
+    const signature = await web3_js.sendAndConfirmTransaction(
+      connection,
+      tx,
+      [agent, service],
+      { commitment: "confirmed" }
+    );
+    return { signature };
+  } catch (err) {
+    throw mapPayError(err, {
+      service: service.publicKey,
+      amountUsdc,
+      vault,
+      policy,
+      receiptHash: args.receiptHash
+    });
+  }
+}
+function mapPayError(err, ctx) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (/already in use/i.test(message)) {
+    return new ReceiptAlreadyRecordedError(ctx.receiptHash);
+  }
+  if (!(err instanceof anchor.AnchorError)) return err;
+  switch (err.error.errorCode.number) {
+    case 6001:
+      return new ZeroAmountError();
+    case 6002:
+      return new VaultFrozenError();
+    case 6003:
+      return new NotWhitelistedError(ctx.service.toBase58());
+    case 6004:
+      return new PerTxLimitExceededError(ctx.amountUsdc, ctx.policy.per_tx_limit_usdc);
+    case 6005:
+      return new HourlyLimitExceededError(
+        ctx.amountUsdc,
+        ctx.policy.hourly_window_spent_usdc,
+        ctx.policy.hourly_limit_usdc
+      );
+    case 6006:
+      return new LifetimeLimitExceededError(
+        ctx.amountUsdc,
+        ctx.vault.total_spent,
+        ctx.policy.lifetime_limit_usdc
+      );
+    // Reputation errors:
+    case 6e3:
+      return new RecordPaymentError("counter overflow on chain");
+    case 6011:
+      return new ServiceInactiveError(ctx.service.toBase58());
+    default:
+      return err;
+  }
+}
+async function requestSpend(args) {
+  const { agent, connection, amountUsdc } = args;
+  const owner = toPubkey(args.owner);
+  const service = toPubkey(args.service);
+  if (amountUsdc <= 0) {
+    throw new Error("requestSpend: amountUsdc must be > 0");
+  }
+  const vaultAddr = vaultPda(owner, agent.publicKey);
+  const provider = buildProvider(connection, agent);
+  const cv = creditVaultProgram(provider);
+  const rawVault = await cv.account.creditVault.fetchNullable(vaultAddr);
+  if (!rawVault) throw new AccountNotFoundError(vaultAddr.toBase58());
+  const vault = decodeCreditVault(vaultAddr, rawVault);
+  const nonce = vault.pending_count;
+  const pendingSpend = pendingSpendPda(vaultAddr, nonce);
+  const serviceTokenAccount = getAssociatedTokenAddress(
+    vault.usdc_mint,
+    service
+  );
+  const signature = await cv.methods.requestSpend(new anchor.BN(amountUsdc)).accounts({
+    agent: agent.publicKey,
+    vault: vaultAddr,
+    serviceTokenAccount,
+    pendingSpend,
+    systemProgram: web3_js.SystemProgram.programId
+  }).signers([agent]).rpc();
+  return { signature, pendingSpend, nonce };
+}
+var NAME_BYTES = 32;
+var URI_BYTES = 128;
+async function registerService(args) {
+  const { sponsor, service, connection } = args;
+  if (args.name.length === 0) {
+    throw new Error("registerService: name must not be empty");
+  }
+  if (Buffer.byteLength(args.name, "utf8") > NAME_BYTES) {
+    throw new Error(
+      `registerService: name exceeds ${NAME_BYTES} bytes (got ${Buffer.byteLength(args.name, "utf8")})`
+    );
+  }
+  const uri = args.serviceUri ?? "";
+  if (Buffer.byteLength(uri, "utf8") > URI_BYTES) {
+    throw new Error(
+      `registerService: serviceUri exceeds ${URI_BYTES} bytes (got ${Buffer.byteLength(uri, "utf8")})`
+    );
+  }
+  const registry = serviceRegistryPda(service.publicKey);
+  const provider = buildProvider(connection, sponsor);
+  const rep = reputationProgram(provider);
+  const signature = await rep.methods.registerService(
+    packFixed(args.name, NAME_BYTES),
+    categoryArg(args.category),
+    packFixed(uri, URI_BYTES)
+  ).accounts({
+    sponsor: sponsor.publicKey,
+    service: service.publicKey,
+    serviceRegistry: registry,
+    systemProgram: web3_js.SystemProgram.programId
+  }).signers([sponsor, service]).rpc();
+  return { signature };
+}
+function packFixed(s, length) {
+  const buf = Buffer.alloc(length);
+  buf.write(s, 0, "utf8");
+  return Array.from(buf);
+}
+function categoryArg(c) {
+  switch (c) {
+    case "DataFeed":
+      return { dataFeed: {} };
+    case "Compute":
+      return { compute: {} };
+    case "Swap":
+      return { swap: {} };
+    case "Rpc":
+      return { rpc: {} };
+    case "Other":
+      return { other: {} };
+  }
+}
+
 // src/client.ts
 var DEFAULT_API_BASE = "http://localhost:8080";
 var AgentFuel = class {
@@ -3387,6 +4072,38 @@ var AgentFuel = class {
       throw mapSpendError(err, { service, amountUsdc, vault, policy });
     }
   }
+  /// Atomic spend + record_payment in one transaction. Use this instead
+  /// of `spend()` + `recordPayment()` when you want the vault burn and
+  /// the reputation accrual to be all-or-nothing. The service keypair
+  /// co-signs.
+  async pay(args) {
+    return pay({
+      agent: this.agent,
+      owner: this.resolveOwner(args.owner),
+      service: args.service,
+      amountUsdc: args.amountUsdc,
+      receiptHash: args.receiptHash,
+      connection: this.connection
+    });
+  }
+  /// Submit an over-limit spend request the owner can approve from the
+  /// mobile app. Returns the `pendingSpend` PDA so the bot can poll for
+  /// resolution.
+  async requestSpend(args) {
+    return requestSpend({
+      agent: this.agent,
+      owner: this.resolveOwner(args.owner),
+      service: args.service,
+      amountUsdc: args.amountUsdc,
+      connection: this.connection
+    });
+  }
+  /// Register a service on chain. The `sponsor` (typically `this.agent`'s
+  /// owner wallet) pays rent; the `service` keypair is the long-lived
+  /// identity that will co-sign every future `record_payment`.
+  async registerService(args) {
+    return registerService({ ...args, connection: this.connection });
+  }
   /// Triggers an on-chain recomputation of the agent's reputation score.
   /// Permissionless — any signer can call it; we use the agent itself since
   /// the SDK already has its keypair available and it already pays tx fees
@@ -3606,10 +4323,14 @@ exports.agentProfilePda = agentProfilePda;
 exports.agentServiceLinkPda = agentServiceLinkPda;
 exports.createAssociatedTokenAccountIdempotentInstruction = createAssociatedTokenAccountIdempotentInstruction;
 exports.getAssociatedTokenAddress = getAssociatedTokenAddress;
+exports.pay = pay;
 exports.paymentRequired = paymentRequired;
+exports.pendingSpendPda = pendingSpendPda;
 exports.policyPda = policyPda;
 exports.receiptUsedPda = receiptUsedPda;
 exports.recordPayment = recordPayment;
+exports.registerService = registerService;
+exports.requestSpend = requestSpend;
 exports.serviceRegistryPda = serviceRegistryPda;
 exports.subscribeService = subscribeService;
 exports.subscribeVault = subscribeVault;