# Reference

## `withYodl7702(provider, options)`

Returns an EIP-1193-compatible provider wrapper.

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `chains` | `{ id: number; bundlerUrl: string; rpcUrl?: string }[]` | No | Chains where the wrapper serves the fallback. Defaults to [`yodlHostedChains()`](#yodlhostedchainschainids). An explicitly empty array is rejected. See [using Yodl's bundler](/sdk/eip-7702-provider/setup#using-yodls-bundler) |
| `yodl` | `YodlLike` | No | A `Yodl` from `@yodlpay/sdk-core`. Defaults `chains` to the chains the instance reads on that Yodl sponsors (never mainnet), routed to its `baseUrl`'s bundler with its RPC proxy as `rpcUrl` where it names one, and `getAuthHeaders` to `config.getAuthHeaders`, sent only to `baseUrl`'s origin. Explicit `chains` / `getAuthHeaders` win. See [using Yodl's bundler](/sdk/eip-7702-provider/setup#using-yodls-bundler) |
| `estimateUserOperationFees` | `(chainId: number) => Promise<{ maxFeePerGas: bigint; maxPriorityFeePerGas: bigint }>` | No | Overrides the built-in pricing, which asks the configured bundler. See [gas pricing](/sdk/eip-7702-provider/setup#gas-pricing) |
| `signAuthorization` | `(request: { account; chainId; contractAddress; nonce }) => Promise<SignedAuthorization>` | Yes | Signs the EIP-7702 authorization. No universal wallet method exists, so this one has no default. See [authorization signing](/sdk/eip-7702-provider/setup#authorization-signing) |

`YodlLike` is structural — `{ config: { baseUrl?; chainIds?; rpcUrls?; getAuthHeaders? } }` — so passing a `Yodl` needs no type import and the package takes no dependency on `@yodlpay/sdk-core`.

`chains[].rpcUrl` is optional. Omit it and the wrapper's three chain reads go over the wrapped wallet's own transport — see [chain reads](/sdk/eip-7702-provider/setup#chain-reads).

## `yodlHostedChains(chainIds?)`

Returns `chains` entries pointing at Yodl's own bundler — what `withYodl7702` falls back to when `chains` is omitted. Called with no argument it covers every chain Yodl sponsors gas on; pass ids to narrow it.

```tsx
yodlHostedChains();          // every sponsored chain
yodlHostedChains([8453]);    // Base only
```

A chain outside `YODL_SPONSORED_CHAIN_IDS` throws rather than being handed an invented endpoint, and an empty list is rejected. Mainnet is deliberately excluded: on L1 gas is bundled into the payment rather than sponsored.

| Export | What it is |
| --- | --- |
| `yodlHostedChains(chainIds?)` | `chains` entries for Yodl's bundler, with no `rpcUrl` so reads ride the wallet transport |
| `YODL_SPONSORED_CHAIN_IDS` | The chain ids Yodl sponsors gas on |
| `YODL_BUNDLER_BASE_URL` | The bundler and ERC-7677 paymaster endpoint those entries point at |

## How it works

The wrapper is **native-first**. Every request is tried against the original provider, and the EIP-7702 path is used only as a fallback.

```mermaid
flowchart TD
    UI["Yodl UI calls wallet_sendCalls"] --> TRY[Try the wallet natively]
    TRY -->|Succeeds| NATIVE[Native path wins]
    TRY -->|"Unsupported, 5700 or 5760"| FB[EIP-7702 fallback]
    TRY -->|"User rejected or any other error"| ERR[Surfaced as-is, never masked]
    FB --> SIGN["signAuthorization — you supply this"]
    SIGN --> FEES["estimateUserOperationFees — defaults to the bundler's oracle"]
    FEES --> SUB[Submit through the configured bundler]
    SUB --> ID[Return an EIP-5792 id and track it]
```

`wallet_sendCalls` falls back when native support is unavailable, when the wallet rejects a required capability with EIP-5792 code `5700`, or when it reports atomicity unsupported with code `5760`. User rejection and unrelated wallet errors surface as-is and are never hidden by the fallback.

When it does fall back, the wrapper sends the calls through the Yodl EIP-7702 smart-account path, returns an EIP-5792 `{ id }`, and tracks that id for later status checks.

## Per-method behaviour

| Method | Behaviour |
| --- | --- |
| `wallet_getCapabilities` | Advertises fallback capabilities for the configured `chains` — the hosted default when none were passed: `atomic: ready` and `paymasterService` available |
| `wallet_sendCalls` | Tries native first; falls back only on `5700` / `5760` / unsupported. A `capabilities.paymasterService.url` is used via the standard ERC-7677 paymaster client |
| `wallet_getCallsStatus` | EIP-5792-shaped status for wrapper-tracked ids — pending, confirmed, reverted, partially reverted |
| `wallet_showCallsStatus` | Resolves with no result for wrapper-tracked ids, since fallback bundles have no native status screen. Unknown ids delegate to the original provider, then report the EIP-5792 unknown-bundle error |
| everything else | Passed straight through to the original provider |

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| `crypto.getRandomValues ... not supported` | The `react-native-get-random-values` native module isn't linked. Reinstall pods and rebuild — not Expo Go |
| `Can't find variable: BigInt` | Hermes is disabled — see [requirements](/sdk/react-native#requirements) |
| `Unsupported chain id` (EIP-5792 `5710`) | The bundle's chain isn't in `chains`. Add a `{ id, bundlerUrl }` entry for it. On the hosted default this means Yodl doesn't sponsor that chain — mainnet included |
| Wallet chain mismatch (`-32602`) | Chain reads are riding the wallet transport and the wallet is on a different chain than the bundle. Switch the wallet before sending, or give that chain its own `rpcUrl`. See [chain reads](/sdk/eip-7702-provider/setup#chain-reads) |
| Error naming `rpcUrl` and a `'pending'` nonce | The wallet's node proxy method-whitelists and refuses `eth_getTransactionCount` at `blockTag: 'pending'`. Configure `rpcUrl` for that chain |
| Fallback never triggers | The wallet supports `wallet_sendCalls` natively. That's expected — native always wins |
| `maxFeePerGas` / `maxPriorityFeePerGas` too low | An `estimateUserOperationFees` override returned a value below the bundler's floor, e.g. `0n` or a stale cached price. Drop the override to use the bundler's own oracle, or return real fees from it |
| Fallback fails at submission | Check that chain's `bundlerUrl` (and `rpcUrl` if you set one), including API keys |

:::tip
"Fallback never triggers" is the most-reported non-issue. If the wallet has native EIP-5792, this package is correctly doing nothing — verify with `wallet_getCapabilities` before debugging further.
:::