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

package/README.md

@@ -14,7 +14,10 @@ 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",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
 
 // Connect with an EIP-1193 wallet provider
 await sdk.connect(provider);
@@ -35,33 +38,76 @@ 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.routingApiBaseUrl`              | `string` (optional)                                         | Routing API URL; required for proxy reads unless the SDK build has `OWNEY_ROUTING_API_BASE_URL` or all `rpcUrls` are set |
+| `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",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
 ```
 
-#### Custom Zyfai RPC URLs
+#### Dedicated RPC URLs
 
-Use `zyfaiRpcUrls` to override Zyfai SDK RPC endpoints (for example, to avoid public endpoint rate limits).
+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:
+
+1. The caller-provided `rpcUrls[chainId]`, when present and non-empty.
+2. The Owney routing API read-only RPC proxy for that chain.
+
+The Alchemy credential stays on the routing API server. The SDK sends its
+existing organization key to the proxy for per-organization rate limiting.
+The proxy base URL must be provided through `routingApiBaseUrl` or the SDK
+build's `OWNEY_ROUTING_API_BASE_URL`; there is no hardcoded production fallback.
 
 ```typescript
+// All supported chains use the Owney routing API proxy.
 const sdk = new OwneySDK({
   apiKey: "your-owney-api-key",
-  zyfaiRpcUrls: {
-    8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
-    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
+```
+
+Overrides can be complete or partial:
+
+```typescript
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  routingApiBaseUrl: "https://your-routing-api.example",
+  rpcUrls: {
+    // Ethereum and Arbitrum continue using the routing API proxy.
+    8453: "https://your-own-rpc.example/rpc",
   },
 });
 ```
 
+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 pass the same routing API proxy URLs to Wagmi and the SDK.
+- SDK consumers may override endpoints if they operate their own RPC provider.
+- Partial maps override only the supplied chains; missing chains use Owney's
+  routing API proxy.
+- 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 +171,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 +485,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 +503,14 @@ type AgentSupportedAssets = {
 
 interface OwneySDKConfig {
   apiKey: string;
+  rpcUrls?: {
+    1?: string;
+    8453?: string;
+    42161?: string;
+  };
+  /** @deprecated Use rpcUrls. */
   zyfaiRpcUrls?: {
+    1?: string;
     8453?: string;
     42161?: string;
   };