@owney/sdk 0.7.25-beta.4 → 0.7.25-beta.6

package/README.md

@@ -14,7 +14,14 @@ npm install @owney/sdk
 import { OwneySDK } from "@owney/sdk";
 
 // Create the SDK instance
-const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  rpcUrls: {
+    1: "https://eth-mainnet.g.alchemy.com/v2/<key>",
+    8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
+    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
+  },
+});
 
 // Connect with an EIP-1193 wallet provider
 await sdk.connect(provider);
@@ -35,33 +42,78 @@ Create a new SDK instance.
 | Param                                   | Type                                                        | Description                                                                                       |
 | --------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `config.apiKey`                         | `string`                                                    | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys       |
-| `config.zyfaiRpcUrls`                   | `{ 8453?: string; 42161?: string }` (optional)              | Per-chain RPC URL overrides used by Zyfai SDK network calls                                       |
+| `config.rpcUrls`                        | `{ 1?: string; 8453?: string; 42161?: string }` (optional)  | Per-chain RPC overrides used by agent reads and transaction-receipt polling                       |
+| `config.zyfaiRpcUrls`                   | Same as `rpcUrls` (deprecated)                              | Legacy Zyfai-only override; use `rpcUrls` for all application-owned reads                         |
 
 ```typescript
 import { OwneySDK } from "@owney/sdk";
 
-const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  rpcUrls: {
+    1: "https://eth-mainnet.g.alchemy.com/v2/<key>",
+    8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
+    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
+  },
+});
 ```
 
-#### Custom Zyfai RPC URLs
+#### Dedicated RPC URLs
+
+Use `rpcUrls` for application-owned chain reads and transaction-receipt
+polling. The connected wallet provider remains responsible for accounts, chain
+switching, signatures, and transaction submission.
+
+`rpcUrls` is optional. The SDK resolves an endpoint independently for each
+supported chain using this precedence:
 
-Use `zyfaiRpcUrls` to override Zyfai SDK RPC endpoints (for example, to avoid public endpoint rate limits).
+1. The caller-provided `rpcUrls[chainId]`, when present and non-empty.
+2. The Owney SDK default URL for that chain.
+
+The SDK defaults are Owney-managed Alchemy endpoints embedded in the SDK. They
+keep zero-configuration integrations working, but their capacity is shared by
+every consumer that does not provide an override.
+
+```typescript
+// Zero configuration: all supported chains use Owney SDK defaults.
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+});
+```
+
+Overrides can be complete or partial:
 
 ```typescript
 const sdk = new OwneySDK({
   apiKey: "your-owney-api-key",
-  zyfaiRpcUrls: {
+  rpcUrls: {
+    // Ethereum and Arbitrum continue using Owney SDK defaults.
     8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
-    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
   },
 });
 ```
 
+The resolved URLs are shared across Owney-owned reads and agent integrations:
+
+- Wagmi or application transports remain the consuming application's
+  responsibility; Owney mini-apps configure them from the same URL map.
+- Zyfai receives the resolved Owney URL map, so its internal provider defaults
+  do not determine routing for Owney SDK consumers.
+- Yieldseeker uses the resolved Base URL for transaction-receipt polling.
+- Balance, allowance, module-state, and receipt reads use the resolved RPC.
+- Account access, chain switching, signatures, approvals, and transaction
+  submission continue through the connected wallet provider.
+
 Notes:
 
-- These overrides are used by Zyfai SDK flows only.
-- If omitted, Zyfai SDK uses its default RPC endpoints.
-- Other app-level RPC clients (for example, direct viem calls outside Zyfai) are configured separately.
+- Owney mini-apps should continue passing explicit environment-specific URLs,
+  even though the SDK defaults provide a fallback.
+- Production SDK consumers should provide their own endpoints for quota
+  isolation, origin restrictions, and predictable capacity.
+- Partial maps override only the supplied chains; missing chains retain Owney
+  SDK defaults.
+- HTTP reads use bounded retries and honor provider `Retry-After` responses.
+- `zyfaiRpcUrls` remains available for compatibility but applies only to Zyfai.
 
 ### `connect(provider)`
 
@@ -125,7 +177,7 @@ await sdk.activateAgent(42161);
 
 ### `deposit(options)`
 
-Deposit funds into a specific agent, or split equally across all agents if `agentId` is omitted. Validates that the asset is supported by the target agent(s) on the active chain, and per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) are taken into account. Custom `depositCallback` implementations run once per final valid agent. The default Permit2 flow signs one recipient-bound batch authorization for every agent share.
+Deposit funds into a specific agent, or split equally across all agents if `agentId` is omitted. Validates that the asset is supported by the target agent(s) on the active chain, and per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) are taken into account. Custom `depositCallback` implementations run once per final valid agent. The default Permit2 flow signs one recipient-bound batch authorization for every agent share. On the first Base USDC deposit, the SDK first requests an ERC-2612 signature and atomically bundles the maximum Permit2 approval with that batch in one sponsored transaction; later deposits need only the batch signature.
 
 | Param                     | Type                 | Description                                                     |
 | ------------------------- | -------------------- | --------------------------------------------------------------- |
@@ -439,8 +491,8 @@ console.log(usdcBaseApy.agentApy.zyfai.averageApy); // APY scoped to USDC on Bas
 type AgentId = "zyfai";
 type Asset = string;
 type DailyApyDays = "7D" | "14D" | "30D";
-type OwneySupportedChainId = 8453 | 42161;
-type OwneySupportedChains = "BASE" | "ARBITRUM";
+type OwneySupportedChainId = 1 | 8453 | 42161;
+type OwneySupportedChains = "ETHEREUM" | "BASE" | "ARBITRUM";
 type OwneySupportedTokens = "USDC" | "WETH";
 
 type AgentSupportedAsset = {
@@ -457,7 +509,14 @@ type AgentSupportedAssets = {
 
 interface OwneySDKConfig {
   apiKey: string;
+  rpcUrls?: {
+    1?: string;
+    8453?: string;
+    42161?: string;
+  };
+  /** @deprecated Use rpcUrls. */
   zyfaiRpcUrls?: {
+    1?: string;
     8453?: string;
     42161?: string;
   };