feat: deposit to any address (#316)

feat: allowing deposits to secondary addresses

Author: lordshashank

AGENTS.md

@@ -17,7 +17,7 @@ This document serves as context for LLM agent sessions working with the Synapse
 ### Key Components
 
 - `Synapse`: Main SDK entry; minimal interface with `payments` property and `storage` manager; strict network validation (mainnet/calibration).
-- `PaymentsService`: Payment operations - deposits, withdrawals, balances, service approvals.
+- `PaymentsService`: Payment operations - deposits, withdrawals, balances, service approvals. The `deposit()` method accepts an optional `DepositOptions` object with `to` property to deposit funds to a different address than the signer, plus callback functions for visibility.
 - `SPRegistryService`: Service provider registry - registration, updates, product management, provider discovery.
 - `WarmStorageService`: Storage coordination - costs, allowances, data sets. Factory method `WarmStorageService.create(provider, address)`. Source of all contract addresses via discovery.
 - `StorageManager/StorageContext`: Storage operations with auto-managed or explicit contexts.
@@ -208,6 +208,7 @@ WarmStorageService (storage coordination)
 - Manages payment rails between parties
 - Supports operator approvals for account management
 - Address discovered from WarmStorage
+- **Deposit Flexibility**: The `deposit(token, to, amount)` function allows depositing to any address, not just the signer. SDK's `PaymentsService.deposit()` exposes this via `DepositOptions` object with optional `to` property.
 
 #### 5. Curio Storage Provider (Service Node)
 

docs/src/content/docs/intro/components.mdx

@@ -22,6 +22,10 @@ const depositTx = await paymentsService.deposit(amount) // amount in base units
 console.log(`Deposit transaction: ${depositTx.hash}`)
 await depositTx.wait() // Wait for confirmation
 
+// Optional: Deposit to a different address
+const recipientAddress = '0x1234...'
+await paymentsService.deposit(amount, TOKENS.USDFC, { to: recipientAddress })
+
 // Check account info
 const info = await paymentsService.accountInfo() // Uses USDFC by default
 console.log('Available funds:', info.availableFunds)

docs/src/content/docs/intro/getting-started.mdx

@@ -170,6 +170,10 @@ const depositTx = await synapse.payments.deposit(requiredAmount, TOKENS.USDFC, {
 console.log(`Deposit transaction: ${depositTx.hash}`)
 await depositTx.wait()
 
+// Optional: Deposit to a different address (e.g., for a service or another user)
+const recipientAddress = '0x1234...'
+await synapse.payments.deposit(amount, TOKENS.USDFC, { to: recipientAddress })
+
 // Service operator approvals (required before creating data sets)
 const warmStorageAddress = await synapse.getWarmStorageAddress()
 
@@ -377,7 +381,7 @@ await synapse.storage.download(pieceCid, { context: storageContext })
 
 **Token Operations:**
 
-- `deposit(amount, token?, callbacks?)` - Deposit funds to payments contract (handles approval automatically), returns `TransactionResponse`
+- `deposit(amount, token?, options?)` - Deposit funds to payments contract (handles approval automatically). Options include `to` (recipient address), and callbacks for visibility. Returns `TransactionResponse`
 - `withdraw(amount, token?)` - Withdraw funds from payments contract, returns `TransactionResponse`
 - `approve(spender, amount, token?)` - Approve token spending (for manual control), returns `TransactionResponse`
 - `allowance(spender, token?)` - Check current token allowance

packages/synapse-sdk/src/payments/index.ts

@@ -1,5 +1,5 @@
 /**
- * Exports the PaymentsService and DepositCallbacks types
+ * Exports the PaymentsService and DepositOptions types
  *
  * @module Payments
  * @example
@@ -8,5 +8,5 @@
  * ```
  */
 
-export type { DepositCallbacks } from './service.ts'
+export type { DepositOptions } from './service.ts'
 export { PaymentsService } from './service.ts'

packages/synapse-sdk/src/payments/service.ts

@@ -19,9 +19,11 @@ import {
 } from '../utils/index.ts'
 
 /**
- * Callbacks for deposit operation visibility
+ * Options for deposit operation
  */
-export interface DepositCallbacks {
+export interface DepositOptions {
+  /** Optional recipient address (defaults to signer address if not provided) */
+  to?: string
   /** Called when checking current allowance */
   onAllowanceCheck?: (current: bigint, required: bigint) => void
   /** Called when approval transaction is sent */
@@ -603,7 +605,7 @@ export class PaymentsService {
   async deposit(
     amount: TokenAmount,
     token: TokenIdentifier = TOKENS.USDFC,
-    callbacks?: DepositCallbacks
+    options?: DepositOptions
   ): Promise<ethers.TransactionResponse> {
     // Only support USDFC for now
     if (token !== TOKENS.USDFC) {
@@ -616,6 +618,7 @@ export class PaymentsService {
     }
 
     const signerAddress = await this._signer.getAddress()
+    const depositTo = options?.to ?? signerAddress
     const usdfcContract = this._getUsdfcContract()
     const paymentsContract = this._getPaymentsContract()
 
@@ -632,24 +635,24 @@ export class PaymentsService {
 
     // Check and update allowance if needed
     const currentAllowance = await this.allowance(this._paymentsAddress, token)
-    callbacks?.onAllowanceCheck?.(currentAllowance, depositAmountBigint)
+    options?.onAllowanceCheck?.(currentAllowance, depositAmountBigint)
 
     if (currentAllowance < depositAmountBigint) {
       // Golden path: automatically approve the exact amount needed
       const approveTx = await this.approve(this._paymentsAddress, depositAmountBigint, token)
-      callbacks?.onApprovalTransaction?.(approveTx)
+      options?.onApprovalTransaction?.(approveTx)
 
       // Wait for approval to be mined before proceeding
       const approvalReceipt = await approveTx.wait(TIMING_CONSTANTS.TRANSACTION_CONFIRMATIONS)
       if (approvalReceipt != null) {
-        callbacks?.onApprovalConfirmed?.(approvalReceipt)
+        options?.onApprovalConfirmed?.(approvalReceipt)
       }
     }
 
     // Check if account has sufficient available balance (no frozen account check needed for deposits)
 
     // Notify that deposit is starting
-    callbacks?.onDepositStarting?.()
+    options?.onDepositStarting?.()
 
     // Only set explicit nonce if NonceManager is disabled
     const txOptions: any = {}
@@ -658,7 +661,7 @@ export class PaymentsService {
       txOptions.nonce = currentNonce
     }
 
-    const depositTx = await paymentsContract.deposit(this._usdfcAddress, signerAddress, depositAmountBigint, txOptions)
+    const depositTx = await paymentsContract.deposit(this._usdfcAddress, depositTo, depositAmountBigint, txOptions)
 
     return depositTx
   }