@owney/sdk 0.7.25-beta.15 → 0.7.25-beta.17

package/dist/index.d.cts

@@ -145,6 +145,14 @@ interface IAgent {
     endFundingBalanceRefresh?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
     getFundingHistory?(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
     getFundingWallet?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    /** Verify the displayed remaining balance after a receipt-confirmed payout.
+     * Undefined means unknown; never substitute a failed read with zero. */
+    verifyWithdrawalBalance?(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    /** Read-only chain proof when indexed withdrawal components are incomplete.
+     * Returns raw owner-withdrawable units; unavailable proof must throw.
+     * minimumAmount is the raw liquidity required from this agent for a typed
+     * plan, so adapters can expand discovery when known positions fall short. */
+    getWithdrawableBalance?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
     /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
     hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
     getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
@@ -355,7 +363,9 @@ interface FundingEvidence {
         method?: "GET" | "POST";
         path?: "/users/withdraw" | "/users/partial-withdraw";
         elapsedMs?: number;
-        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "other";
+        /** Actual response status captured before the vendor replaces the HTTP error. */
+        httpStatus?: number;
+        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "withdrawal-in-progress" | "other";
     };
     transfer: FundingStage;
     registration: FundingStage;
@@ -374,6 +384,12 @@ interface AssetReadMetadata {
     snapshotId?: string;
     blockNumber?: string;
     netDepositsRaw?: string;
+    /** Display-only agreement with a post-payout read. Does not prove that
+     * provider accounting, history or allocations include the transaction. */
+    withdrawalCheck?: {
+        txHash: string;
+        blockNumber: string;
+    };
     positionsStatus: "available" | "unavailable";
 }
 interface OwneyDepositResult {
@@ -393,6 +409,13 @@ interface AgentWithdrawResult {
     completion?: "unverified";
     /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
     amount: string;
+    /** Yieldseeker typed withdrawal fulfilled after an exactly verified fee
+     * deduction. Amount remains the confirmed net owner payout, and the gross
+     * amount must equal that payout plus the fee, all in token base units. */
+    feeAdjustment?: {
+        grossAmount: string;
+        feeAmount: string;
+    };
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
@@ -695,6 +718,7 @@ declare class OwneySDK {
     private cachedSponsoredCallsCallbacks;
     private readonly agentReads;
     private readonly recoveredFundingReads;
+    private fundingBalanceChecks;
     private readonly activationChecks;
     private readAgent;
     private initializingAgentsPromise;
@@ -868,6 +892,9 @@ declare class OwneySDK {
     /** Whether a foreground deposit can resume the same signed batch, never a
      * fresh authorization. The batch rail independently rechecks the exact plan. */
     canResumePendingDeposit(evidences: FundingEvidence[], amount: string): Promise<boolean>;
+    /** Optional post-payout display proof; receipt verification and the provider
+     * adapter must agree before attaching it to this exact balance object. */
+    verifyWithdrawalBalance(evidence: FundingEvidence, balance: AgentBalance): Promise<AgentBalance>;
     /** A display acknowledgement controls polling only; it never confirms a financial outcome. */
     endFundingBalanceRefresh(evidence: FundingEvidence, read: AssetReadMetadata): boolean;
     /** History lookup for receipt recovery; adapters may not authenticate or sign here. */
@@ -904,6 +931,8 @@ declare class OwneySDK {
         chainId?: number;
         asset?: OwneySupportedTokens;
     }): Promise<OwneyBalances | AgentBalance>;
+    /** Preserve failure objects for withdrawal recovery without changing public balance results. */
+    private readAggregatedBalances;
     /**
      * Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated earnings.
@@ -1070,6 +1099,8 @@ declare class YieldseekerAgent implements IAgent {
     private readonly transactionExecutor?;
     private readonly unwindReceiptWaiter?;
     private readonly agentContexts;
+    private readonly balanceContexts;
+    private readonly balanceVaults;
     private readonly users;
     private readonly pendingAgents;
     private readonly pendingWalletContexts;
@@ -1100,7 +1131,15 @@ declare class YieldseekerAgent implements IAgent {
     deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress): Promise<AgentWithdrawResult>;
     private withdrawInternal;
+    /** A withdrawal-only liquidity floor; display snapshots never authorize it. */
+    getWithdrawableBalance(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    private readVaultLiquidity;
+    private validateWithdrawalPositions;
+    private withdrawalVaultHints;
+    private readWithdrawalPositions;
+    private resolveWithdrawalLiquidity;
     getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
     invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number): void;
     endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
     getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;

package/dist/index.d.ts

@@ -145,6 +145,14 @@ interface IAgent {
     endFundingBalanceRefresh?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
     getFundingHistory?(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
     getFundingWallet?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    /** Verify the displayed remaining balance after a receipt-confirmed payout.
+     * Undefined means unknown; never substitute a failed read with zero. */
+    verifyWithdrawalBalance?(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    /** Read-only chain proof when indexed withdrawal components are incomplete.
+     * Returns raw owner-withdrawable units; unavailable proof must throw.
+     * minimumAmount is the raw liquidity required from this agent for a typed
+     * plan, so adapters can expand discovery when known positions fall short. */
+    getWithdrawableBalance?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
     /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
     hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
     getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
@@ -355,7 +363,9 @@ interface FundingEvidence {
         method?: "GET" | "POST";
         path?: "/users/withdraw" | "/users/partial-withdraw";
         elapsedMs?: number;
-        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "other";
+        /** Actual response status captured before the vendor replaces the HTTP error. */
+        httpStatus?: number;
+        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "withdrawal-in-progress" | "other";
     };
     transfer: FundingStage;
     registration: FundingStage;
@@ -374,6 +384,12 @@ interface AssetReadMetadata {
     snapshotId?: string;
     blockNumber?: string;
     netDepositsRaw?: string;
+    /** Display-only agreement with a post-payout read. Does not prove that
+     * provider accounting, history or allocations include the transaction. */
+    withdrawalCheck?: {
+        txHash: string;
+        blockNumber: string;
+    };
     positionsStatus: "available" | "unavailable";
 }
 interface OwneyDepositResult {
@@ -393,6 +409,13 @@ interface AgentWithdrawResult {
     completion?: "unverified";
     /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
     amount: string;
+    /** Yieldseeker typed withdrawal fulfilled after an exactly verified fee
+     * deduction. Amount remains the confirmed net owner payout, and the gross
+     * amount must equal that payout plus the fee, all in token base units. */
+    feeAdjustment?: {
+        grossAmount: string;
+        feeAmount: string;
+    };
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
@@ -695,6 +718,7 @@ declare class OwneySDK {
     private cachedSponsoredCallsCallbacks;
     private readonly agentReads;
     private readonly recoveredFundingReads;
+    private fundingBalanceChecks;
     private readonly activationChecks;
     private readAgent;
     private initializingAgentsPromise;
@@ -868,6 +892,9 @@ declare class OwneySDK {
     /** Whether a foreground deposit can resume the same signed batch, never a
      * fresh authorization. The batch rail independently rechecks the exact plan. */
     canResumePendingDeposit(evidences: FundingEvidence[], amount: string): Promise<boolean>;
+    /** Optional post-payout display proof; receipt verification and the provider
+     * adapter must agree before attaching it to this exact balance object. */
+    verifyWithdrawalBalance(evidence: FundingEvidence, balance: AgentBalance): Promise<AgentBalance>;
     /** A display acknowledgement controls polling only; it never confirms a financial outcome. */
     endFundingBalanceRefresh(evidence: FundingEvidence, read: AssetReadMetadata): boolean;
     /** History lookup for receipt recovery; adapters may not authenticate or sign here. */
@@ -904,6 +931,8 @@ declare class OwneySDK {
         chainId?: number;
         asset?: OwneySupportedTokens;
     }): Promise<OwneyBalances | AgentBalance>;
+    /** Preserve failure objects for withdrawal recovery without changing public balance results. */
+    private readAggregatedBalances;
     /**
      * Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated earnings.
@@ -1070,6 +1099,8 @@ declare class YieldseekerAgent implements IAgent {
     private readonly transactionExecutor?;
     private readonly unwindReceiptWaiter?;
     private readonly agentContexts;
+    private readonly balanceContexts;
+    private readonly balanceVaults;
     private readonly users;
     private readonly pendingAgents;
     private readonly pendingWalletContexts;
@@ -1100,7 +1131,15 @@ declare class YieldseekerAgent implements IAgent {
     deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress): Promise<AgentWithdrawResult>;
     private withdrawInternal;
+    /** A withdrawal-only liquidity floor; display snapshots never authorize it. */
+    getWithdrawableBalance(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    private readVaultLiquidity;
+    private validateWithdrawalPositions;
+    private withdrawalVaultHints;
+    private readWithdrawalPositions;
+    private resolveWithdrawalLiquidity;
     getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
     invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number): void;
     endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
     getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;