@agent-fuel/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -15,6 +15,16 @@ type CreditVaultAccount = {
     frozen: boolean;
     created_slot: number;
     last_active_slot: number;
+    pending_count: number;
+};
+type PendingSpendAccount = {
+    pubkey: PublicKey;
+    vault: PublicKey;
+    agent: PublicKey;
+    service: PublicKey;
+    amount_usdc: number;
+    nonce: number;
+    requested_slot: number;
 };
 type SpendPolicyAccount = {
     pubkey: PublicKey;
@@ -66,6 +76,70 @@ type ReputationLookup = {
     updated_at: string;
 };
 
+type PayArgs = {
+    /** Agent keypair — spends from the vault and pays tx fees. */
+    agent: Keypair;
+    /** Service keypair — co-signs the reputation half. Its pubkey must
+     *  match the service registered on chain. */
+    service: Keypair;
+    /** Vault owner. */
+    owner: Pubkeyish;
+    /** Amount in micro-USDC. */
+    amountUsdc: number;
+    /** 32-byte receipt hash. Common: `sha256(agent|service|tick|...)`. */
+    receiptHash: Uint8Array;
+    connection: Connection;
+};
+type PayResult = {
+    signature: string;
+};
+/**
+ * Atomic spend + record_payment. The vault burn and reputation accrual
+ * happen in one transaction — without this, a service could mirror only
+ * payments it actually received, but the agent's score wouldn't reflect
+ * its own spending. Both sides of the SDK need this primitive to keep
+ * reputation honest.
+ */
+declare function pay(args: PayArgs): Promise<PayResult>;
+
+type RequestSpendArgs = {
+    agent: Keypair;
+    owner: Pubkeyish;
+    service: Pubkeyish;
+    amountUsdc: number;
+    connection: Connection;
+};
+type RequestSpendResult = {
+    signature: string;
+    /** The PendingSpend account the owner approves / cancels and the bot
+     *  polls for resolution. */
+    pendingSpend: PublicKey;
+    /** Vault nonce burned by this request. */
+    nonce: number;
+};
+declare function requestSpend(args: RequestSpendArgs): Promise<RequestSpendResult>;
+
+type RegisterServiceArgs = {
+    /** Pays rent for the registry PDA and submits the tx. Typically the
+     *  same wallet that owns the service brand. */
+    sponsor: Keypair;
+    /** Long-lived service identity. Co-signs registration to prevent
+     *  someone else from squatting on the keypair. Must hold ~0.05 SOL
+     *  for downstream `record_payment` receipt PDAs to be fundable from
+     *  the service side. */
+    service: Keypair;
+    name: string;
+    category: ServiceCategory;
+    /** Off-chain metadata URI (pricing, docs, endpoint). Empty string is
+     *  allowed; chain just stores zero-padded bytes. */
+    serviceUri?: string;
+    connection: Connection;
+};
+type RegisterServiceResult = {
+    signature: string;
+};
+declare function registerService(args: RegisterServiceArgs): Promise<RegisterServiceResult>;
+
 type Cluster = "mainnet-beta" | "devnet" | "testnet" | "localnet";
 type AgentFuelOptions = {
     agent: Keypair;
@@ -108,6 +182,16 @@ declare class AgentFuel {
     getPolicy(ref?: VaultRef): Promise<SpendPolicyAccount>;
     checkService(serviceAuthority: Pubkeyish): Promise<ServiceRegistryAccount>;
     spend(args: SpendArgs): Promise<SpendResult>;
+    pay(args: Omit<PayArgs, "connection" | "agent" | "owner"> & {
+        owner?: Pubkeyish;
+    }): Promise<PayResult>;
+    requestSpend(args: Omit<RequestSpendArgs, "connection" | "agent" | "owner"> & {
+        owner?: Pubkeyish;
+    }): Promise<RequestSpendResult>;
+    registerService(args: Omit<RegisterServiceArgs, "connection">): Promise<RegisterServiceResult>;
+    computeScore(): Promise<{
+        signature: string;
+    }>;
     onEvent(callback: (frame: LiveEventFrame) => void, options?: OnEventOptions): Subscription;
 }
 
@@ -125,6 +209,21 @@ declare function createAssociatedTokenAccountIdempotentInstruction(payer: Public
 declare function vaultPda(owner: Pubkeyish, agent: Pubkeyish): PublicKey;
 declare function policyPda(vault: Pubkeyish): PublicKey;
 declare function serviceRegistryPda(serviceAuthority: Pubkeyish): PublicKey;
+declare function agentProfilePda(agent: Pubkeyish): PublicKey;
+/** PDA used by `record_payment` to track the agent ↔ service pair. The seeds
+ *  are the *PDAs* of the agent profile and service registry, not the raw
+ *  authority pubkeys — match the on-chain Anchor account constraint. */
+declare function agentServiceLinkPda(agentProfile: Pubkeyish, serviceRegistry: Pubkeyish): PublicKey;
+/** PendingSpend PDA — created by `request_spend`, consumed (and closed) by
+ *  either `approve_spend` (CPIs into `spend`, transfers USDC) or
+ *  `cancel_spend` (closes without transfer). Nonce is the vault's
+ *  `pending_count` at request time, so every request gets a fresh PDA. */
+declare function pendingSpendPda(vault: Pubkeyish, nonce: number | bigint): PublicKey;
+/** Existence-as-signal: a `ReceiptUsed` PDA at `[b"receipt", hash]` proves
+ *  the receipt has been recorded. `record_payment`'s `init` constraint (not
+ *  `init_if_needed`) means a duplicate hash fails with `AccountAlreadyInUse`,
+ *  which is the chain-side replay defence. */
+declare function receiptUsedPda(receiptHash: Uint8Array): PublicKey;
 
 declare class AgentFuelError extends Error {
     constructor(message: string);
@@ -172,6 +271,44 @@ declare class NotWhitelistedError extends SpendPolicyError {
     readonly service: string;
     constructor(service: string);
 }
+declare class RecordPaymentError extends AgentFuelError {
+    constructor(message: string);
+}
+declare class ReceiptAlreadyRecordedError extends RecordPaymentError {
+    readonly receiptHash: Uint8Array;
+    constructor(receiptHash: Uint8Array);
+}
+declare class ServiceInactiveError extends RecordPaymentError {
+    readonly service: string;
+    constructor(service: string);
+}
+
+type RecordPaymentArgs = {
+    /** Service authority keypair. Signs the tx and pays the fee. Must match
+     *  the same keypair that was registered on chain as the service authority. */
+    service: Keypair;
+    /** Agent identity pubkey (NOT the AgentProfile PDA — we derive that). */
+    agent: Pubkeyish;
+    /** Amount in micro-USDC (1_000_000 = 1 USDC). */
+    amountUsdc: number;
+    /** 32-byte hash that uniquely identifies this payment. Common choice:
+     *  `sha256(spendTxSignature)` — the spend signature is unique on chain,
+     *  so its hash is too. The chain enforces single-use via `init` on the
+     *  ReceiptUsed PDA; resubmitting the same hash fails with AccountAlreadyInUse. */
+    receiptHash: Uint8Array;
+    connection: Connection;
+};
+type RecordPaymentResult = {
+    signature: string;
+};
+declare function recordPayment(args: RecordPaymentArgs): Promise<RecordPaymentResult>;
+
+type SubscribeOptions = {
+    onFrame: (frame: LiveEventFrame) => void;
+    onStatus?: (status: LiveStatus) => void;
+};
+declare function subscribeService(apiBase: string, servicePubkey: string, opts: SubscribeOptions): Subscription;
+declare function subscribeVault(apiBase: string, vaultPubkey: string, opts: SubscribeOptions): Subscription;
 
 type PaymentRequirement = {
     recipient: string;
@@ -190,4 +327,4 @@ declare class PaymentParseError extends AgentFuelError {
 }
 declare function paymentRequired(fuel: AgentFuel, opts?: PaymentRequiredOptions): FetchLike;
 
-export { ASSOCIATED_TOKEN_PROGRAM_ID, AccountNotFoundError, AgentFuel, AgentFuelError, type AgentFuelOptions, type Cluster, type CreditVaultAccount, type FetchLike, HourlyLimitExceededError, HttpError, LifetimeLimitExceededError, type LiveEventFrame, type LiveStatus, NotWhitelistedError, type OnEventOptions, OwnerNotConfiguredError, PROGRAM_IDS, PaymentParseError, type PaymentRequiredOptions, type PaymentRequirement, PerTxLimitExceededError, type Pubkeyish, type ReputationLookup, SLOTS_PER_HOUR, type ServiceCategory, type ServiceRegistryAccount, type SpendArgs, type SpendPolicyAccount, SpendPolicyError, type SpendResult, type Subscription, TOKEN_PROGRAM_ID, VaultFrozenError, type VaultRef, ZeroAmountError, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddress, paymentRequired, policyPda, serviceRegistryPda, vaultPda };
+export { ASSOCIATED_TOKEN_PROGRAM_ID, AccountNotFoundError, AgentFuel, AgentFuelError, type AgentFuelOptions, type Cluster, type CreditVaultAccount, type FetchLike, HourlyLimitExceededError, HttpError, LifetimeLimitExceededError, type LiveEventFrame, type LiveStatus, NotWhitelistedError, type OnEventOptions, OwnerNotConfiguredError, PROGRAM_IDS, type PayArgs, type PayResult, PaymentParseError, type PaymentRequiredOptions, type PaymentRequirement, type PendingSpendAccount, PerTxLimitExceededError, type Pubkeyish, ReceiptAlreadyRecordedError, type RecordPaymentArgs, RecordPaymentError, type RecordPaymentResult, type RegisterServiceArgs, type RegisterServiceResult, type ReputationLookup, type RequestSpendArgs, type RequestSpendResult, SLOTS_PER_HOUR, type ServiceCategory, ServiceInactiveError, type ServiceRegistryAccount, type SpendArgs, type SpendPolicyAccount, SpendPolicyError, type SpendResult, type SubscribeOptions, type Subscription, TOKEN_PROGRAM_ID, VaultFrozenError, type VaultRef, ZeroAmountError, agentProfilePda, agentServiceLinkPda, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddress, pay, paymentRequired, pendingSpendPda, policyPda, receiptUsedPda, recordPayment, registerService, requestSpend, serviceRegistryPda, subscribeService, subscribeVault, vaultPda };

package/dist/index.d.ts

@@ -15,6 +15,16 @@ type CreditVaultAccount = {
     frozen: boolean;
     created_slot: number;
     last_active_slot: number;
+    pending_count: number;
+};
+type PendingSpendAccount = {
+    pubkey: PublicKey;
+    vault: PublicKey;
+    agent: PublicKey;
+    service: PublicKey;
+    amount_usdc: number;
+    nonce: number;
+    requested_slot: number;
 };
 type SpendPolicyAccount = {
     pubkey: PublicKey;
@@ -66,6 +76,70 @@ type ReputationLookup = {
     updated_at: string;
 };
 
+type PayArgs = {
+    /** Agent keypair — spends from the vault and pays tx fees. */
+    agent: Keypair;
+    /** Service keypair — co-signs the reputation half. Its pubkey must
+     *  match the service registered on chain. */
+    service: Keypair;
+    /** Vault owner. */
+    owner: Pubkeyish;
+    /** Amount in micro-USDC. */
+    amountUsdc: number;
+    /** 32-byte receipt hash. Common: `sha256(agent|service|tick|...)`. */
+    receiptHash: Uint8Array;
+    connection: Connection;
+};
+type PayResult = {
+    signature: string;
+};
+/**
+ * Atomic spend + record_payment. The vault burn and reputation accrual
+ * happen in one transaction — without this, a service could mirror only
+ * payments it actually received, but the agent's score wouldn't reflect
+ * its own spending. Both sides of the SDK need this primitive to keep
+ * reputation honest.
+ */
+declare function pay(args: PayArgs): Promise<PayResult>;
+
+type RequestSpendArgs = {
+    agent: Keypair;
+    owner: Pubkeyish;
+    service: Pubkeyish;
+    amountUsdc: number;
+    connection: Connection;
+};
+type RequestSpendResult = {
+    signature: string;
+    /** The PendingSpend account the owner approves / cancels and the bot
+     *  polls for resolution. */
+    pendingSpend: PublicKey;
+    /** Vault nonce burned by this request. */
+    nonce: number;
+};
+declare function requestSpend(args: RequestSpendArgs): Promise<RequestSpendResult>;
+
+type RegisterServiceArgs = {
+    /** Pays rent for the registry PDA and submits the tx. Typically the
+     *  same wallet that owns the service brand. */
+    sponsor: Keypair;
+    /** Long-lived service identity. Co-signs registration to prevent
+     *  someone else from squatting on the keypair. Must hold ~0.05 SOL
+     *  for downstream `record_payment` receipt PDAs to be fundable from
+     *  the service side. */
+    service: Keypair;
+    name: string;
+    category: ServiceCategory;
+    /** Off-chain metadata URI (pricing, docs, endpoint). Empty string is
+     *  allowed; chain just stores zero-padded bytes. */
+    serviceUri?: string;
+    connection: Connection;
+};
+type RegisterServiceResult = {
+    signature: string;
+};
+declare function registerService(args: RegisterServiceArgs): Promise<RegisterServiceResult>;
+
 type Cluster = "mainnet-beta" | "devnet" | "testnet" | "localnet";
 type AgentFuelOptions = {
     agent: Keypair;
@@ -108,6 +182,16 @@ declare class AgentFuel {
     getPolicy(ref?: VaultRef): Promise<SpendPolicyAccount>;
     checkService(serviceAuthority: Pubkeyish): Promise<ServiceRegistryAccount>;
     spend(args: SpendArgs): Promise<SpendResult>;
+    pay(args: Omit<PayArgs, "connection" | "agent" | "owner"> & {
+        owner?: Pubkeyish;
+    }): Promise<PayResult>;
+    requestSpend(args: Omit<RequestSpendArgs, "connection" | "agent" | "owner"> & {
+        owner?: Pubkeyish;
+    }): Promise<RequestSpendResult>;
+    registerService(args: Omit<RegisterServiceArgs, "connection">): Promise<RegisterServiceResult>;
+    computeScore(): Promise<{
+        signature: string;
+    }>;
     onEvent(callback: (frame: LiveEventFrame) => void, options?: OnEventOptions): Subscription;
 }
 
@@ -125,6 +209,21 @@ declare function createAssociatedTokenAccountIdempotentInstruction(payer: Public
 declare function vaultPda(owner: Pubkeyish, agent: Pubkeyish): PublicKey;
 declare function policyPda(vault: Pubkeyish): PublicKey;
 declare function serviceRegistryPda(serviceAuthority: Pubkeyish): PublicKey;
+declare function agentProfilePda(agent: Pubkeyish): PublicKey;
+/** PDA used by `record_payment` to track the agent ↔ service pair. The seeds
+ *  are the *PDAs* of the agent profile and service registry, not the raw
+ *  authority pubkeys — match the on-chain Anchor account constraint. */
+declare function agentServiceLinkPda(agentProfile: Pubkeyish, serviceRegistry: Pubkeyish): PublicKey;
+/** PendingSpend PDA — created by `request_spend`, consumed (and closed) by
+ *  either `approve_spend` (CPIs into `spend`, transfers USDC) or
+ *  `cancel_spend` (closes without transfer). Nonce is the vault's
+ *  `pending_count` at request time, so every request gets a fresh PDA. */
+declare function pendingSpendPda(vault: Pubkeyish, nonce: number | bigint): PublicKey;
+/** Existence-as-signal: a `ReceiptUsed` PDA at `[b"receipt", hash]` proves
+ *  the receipt has been recorded. `record_payment`'s `init` constraint (not
+ *  `init_if_needed`) means a duplicate hash fails with `AccountAlreadyInUse`,
+ *  which is the chain-side replay defence. */
+declare function receiptUsedPda(receiptHash: Uint8Array): PublicKey;
 
 declare class AgentFuelError extends Error {
     constructor(message: string);
@@ -172,6 +271,44 @@ declare class NotWhitelistedError extends SpendPolicyError {
     readonly service: string;
     constructor(service: string);
 }
+declare class RecordPaymentError extends AgentFuelError {
+    constructor(message: string);
+}
+declare class ReceiptAlreadyRecordedError extends RecordPaymentError {
+    readonly receiptHash: Uint8Array;
+    constructor(receiptHash: Uint8Array);
+}
+declare class ServiceInactiveError extends RecordPaymentError {
+    readonly service: string;
+    constructor(service: string);
+}
+
+type RecordPaymentArgs = {
+    /** Service authority keypair. Signs the tx and pays the fee. Must match
+     *  the same keypair that was registered on chain as the service authority. */
+    service: Keypair;
+    /** Agent identity pubkey (NOT the AgentProfile PDA — we derive that). */
+    agent: Pubkeyish;
+    /** Amount in micro-USDC (1_000_000 = 1 USDC). */
+    amountUsdc: number;
+    /** 32-byte hash that uniquely identifies this payment. Common choice:
+     *  `sha256(spendTxSignature)` — the spend signature is unique on chain,
+     *  so its hash is too. The chain enforces single-use via `init` on the
+     *  ReceiptUsed PDA; resubmitting the same hash fails with AccountAlreadyInUse. */
+    receiptHash: Uint8Array;
+    connection: Connection;
+};
+type RecordPaymentResult = {
+    signature: string;
+};
+declare function recordPayment(args: RecordPaymentArgs): Promise<RecordPaymentResult>;
+
+type SubscribeOptions = {
+    onFrame: (frame: LiveEventFrame) => void;
+    onStatus?: (status: LiveStatus) => void;
+};
+declare function subscribeService(apiBase: string, servicePubkey: string, opts: SubscribeOptions): Subscription;
+declare function subscribeVault(apiBase: string, vaultPubkey: string, opts: SubscribeOptions): Subscription;
 
 type PaymentRequirement = {
     recipient: string;
@@ -190,4 +327,4 @@ declare class PaymentParseError extends AgentFuelError {
 }
 declare function paymentRequired(fuel: AgentFuel, opts?: PaymentRequiredOptions): FetchLike;
 
-export { ASSOCIATED_TOKEN_PROGRAM_ID, AccountNotFoundError, AgentFuel, AgentFuelError, type AgentFuelOptions, type Cluster, type CreditVaultAccount, type FetchLike, HourlyLimitExceededError, HttpError, LifetimeLimitExceededError, type LiveEventFrame, type LiveStatus, NotWhitelistedError, type OnEventOptions, OwnerNotConfiguredError, PROGRAM_IDS, PaymentParseError, type PaymentRequiredOptions, type PaymentRequirement, PerTxLimitExceededError, type Pubkeyish, type ReputationLookup, SLOTS_PER_HOUR, type ServiceCategory, type ServiceRegistryAccount, type SpendArgs, type SpendPolicyAccount, SpendPolicyError, type SpendResult, type Subscription, TOKEN_PROGRAM_ID, VaultFrozenError, type VaultRef, ZeroAmountError, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddress, paymentRequired, policyPda, serviceRegistryPda, vaultPda };
+export { ASSOCIATED_TOKEN_PROGRAM_ID, AccountNotFoundError, AgentFuel, AgentFuelError, type AgentFuelOptions, type Cluster, type CreditVaultAccount, type FetchLike, HourlyLimitExceededError, HttpError, LifetimeLimitExceededError, type LiveEventFrame, type LiveStatus, NotWhitelistedError, type OnEventOptions, OwnerNotConfiguredError, PROGRAM_IDS, type PayArgs, type PayResult, PaymentParseError, type PaymentRequiredOptions, type PaymentRequirement, type PendingSpendAccount, PerTxLimitExceededError, type Pubkeyish, ReceiptAlreadyRecordedError, type RecordPaymentArgs, RecordPaymentError, type RecordPaymentResult, type RegisterServiceArgs, type RegisterServiceResult, type ReputationLookup, type RequestSpendArgs, type RequestSpendResult, SLOTS_PER_HOUR, type ServiceCategory, ServiceInactiveError, type ServiceRegistryAccount, type SpendArgs, type SpendPolicyAccount, SpendPolicyError, type SpendResult, type SubscribeOptions, type Subscription, TOKEN_PROGRAM_ID, VaultFrozenError, type VaultRef, ZeroAmountError, agentProfilePda, agentServiceLinkPda, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddress, pay, paymentRequired, pendingSpendPda, policyPda, receiptUsedPda, recordPayment, registerService, requestSpend, serviceRegistryPda, subscribeService, subscribeVault, vaultPda };