@agent-fuel/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `@agent-fuel/sdk` are documented here. Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-05-31
+
+### Added
+
+- `pay({ agent, service, owner, amountUsdc, receiptHash, connection })` — atomic `spend` + `record_payment` in one tx, mirroring `Spender::pay()` in the Rust runtime. Vault burn and reputation accrual now land together or not at all; no half-states where USDC moved but the agent ↔ service link never updated.
+- `requestSpend({ agent, owner, service, amountUsdc, connection })` — agent-initiated half of the over-limit approval flow. Returns the `pendingSpend` PDA so callers can poll for resolution.
+- `registerService({ sponsor, service, name, category, serviceUri?, connection })` — register a new service on chain. Two-signer (sponsor pays rent, service is the long-lived identity).
+- `pendingSpendPda(vault, nonce)` PDA helper.
+- `PendingSpendAccount` type + decoder.
+- Convenience wrappers on `AgentFuel`: `fuel.pay()`, `fuel.requestSpend()`, `fuel.registerService()` — same surface as the standalone functions, with the connection and agent supplied by the instance.
+
+### Changed
+
+- Re-vendored IDLs against the latest on-chain deploys so the SDK sees `request_spend`, `approve_spend`, `cancel_spend`, `register_service`, and the new `pending_count` field on `CreditVault`.
+- `CreditVaultAccount` now includes `pending_count: number` — the nonce burned by the next `request_spend`.
+
+## [0.1.1] — 2026-05-29
+
+### Changed
+
+- Moved `@coral-xyz/anchor` and `@solana/spl-token` from `peerDependencies` to `dependencies`. Host apps no longer need to provide compatible versions; the SDK ships its own and isolates from version skew (notably anchor 0.29 vs 0.31, which caused `BN.init` assertions when consumed from Solana Agent Kit).
+
 ## [0.1.0] — 2026-05-27
 
 First public release. Six-method surface for AI agents to read reputation, pay services from a credit vault, and stream live events — plus an x402 fetch wrapper.

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for [Agent Fuel](https://github.com/TODO/agent_fuel) — credit vault + reputation primitives for AI agents on Solana.
 
-> **Status:** `0.1.0-alpha.0`. Full read/write/stream surface live. Publishing to npm lands in the next slice ([phases.md](../../docs/phases.md)).
+> **Status:** `0.1.0`. Full read/write/stream surface live, published to npm with provenance.
 
 ## The six functions
 
@@ -38,7 +38,7 @@ const fuel = new AgentFuel({
   owner: new PublicKey("..."),      // the wallet that funded your vault
   cluster: "devnet",
   rpc: "https://api.devnet.solana.com",
-  apiBase: "http://localhost:8080", // your Agent Fuel backend
+  apiBase: "https://api.agentfuel.online", // your Agent Fuel backend
 });
 ```
 
@@ -167,6 +167,19 @@ npm run lint
 npm run build        # emits dist/ (ESM + CJS + .d.ts) via tsup
 ```
 
+### Bootstrapping a devnet sandbox
+
+`npm run devnet:bootstrap` provisions a complete devnet environment in one command: deploys a test USDC mint, mints initial supply to the owner, registers a service, initializes an agent profile, creates + funds a vault, and verifies the whole graph by reading it back through the SDK.
+
+```bash
+npm run build           # bootstrap imports from dist/
+npm run devnet:bootstrap
+```
+
+Defaults to the Solana CLI keypair at `~/.config/solana/id.json` as the owner-agent identity (needs ~0.05 SOL on devnet — `solana airdrop 1 --url devnet` if low). Generates the service + mint keypairs under `~/.config/agent-fuel/`, idempotently — reruns after a partial failure are safe.
+
+The script writes a `devnet-config.json` manifest with every pubkey + path, and prints the exact env-var block to copy into the [x402-quickstart](./examples/x402-quickstart/) example for a real end-to-end `spend()` against devnet.
+
 ### Refreshing the IDLs
 
 The IDLs under `src/idl/` are committed copies — the SDK build, CI, and downstream consumers never depend on `anchor build`. When the Anchor programs change, re-vendor manually and commit:

package/dist/idl/credit-vault.cjs

@@ -11,6 +11,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: [
@@ -417,6 +611,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: [
@@ -742,6 +1034,19 @@ var credit_vault_default = {
         70
       ]
     },
+    {
+      name: "PendingSpend",
+      discriminator: [
+        193,
+        205,
+        85,
+        66,
+        25,
+        3,
+        67,
+        134
+      ]
+    },
     {
       name: "SpendPolicy",
       discriminator: [
@@ -796,6 +1101,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: [
@@ -912,6 +1243,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: [
@@ -1000,12 +1341,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
               ]
             }
           }
@@ -1040,6 +1391,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: {
@@ -1143,6 +1553,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: {