@agent-fuel/sdk 0.1.1 → 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,13 @@ 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;
     }>;
@@ -133,6 +214,11 @@ declare function agentProfilePda(agent: Pubkeyish): PublicKey;
  *  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`,
@@ -241,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, ReceiptAlreadyRecordedError, type RecordPaymentArgs, RecordPaymentError, type RecordPaymentResult, type ReputationLookup, 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, paymentRequired, policyPda, receiptUsedPda, recordPayment, serviceRegistryPda, subscribeService, subscribeVault, 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,13 @@ 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;
     }>;
@@ -133,6 +214,11 @@ declare function agentProfilePda(agent: Pubkeyish): PublicKey;
  *  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`,
@@ -241,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, ReceiptAlreadyRecordedError, type RecordPaymentArgs, RecordPaymentError, type RecordPaymentResult, type ReputationLookup, 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, paymentRequired, policyPda, receiptUsedPda, recordPayment, serviceRegistryPda, subscribeService, subscribeVault, 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 };