@yodlpay/react-native 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,88 @@
1
+ Business Source License 1.1
2
+
3
+ License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
4
+ "Business Source License" is a trademark of MariaDB Corporation Ab.
5
+
6
+ -----------------------------------------------------------------------------
7
+
8
+ Parameters
9
+
10
+ Licensor: Yodl Verein, Switzerland
11
+ Licensed Work: @yodlpay/react-native
12
+ The Licensed Work is (c) 2026 Yodl Verein.
13
+ Additional Use Grant: None
14
+ Change Date: The fourth anniversary of the first publicly available
15
+ distribution of a specific version of the Licensed Work.
16
+ Change License: MIT
17
+
18
+ For information about alternative licensing arrangements for the Licensed
19
+ Work, please contact Yodl Verein.
20
+
21
+ -----------------------------------------------------------------------------
22
+
23
+ Terms
24
+
25
+ The Licensor hereby grants you the right to copy, modify, create derivative
26
+ works, redistribute, and make non-production use of the Licensed Work. The
27
+ Licensor may make an Additional Use Grant, above, permitting limited
28
+ production use.
29
+
30
+ Effective on the Change Date, or the fourth anniversary of the first publicly
31
+ available distribution of a specific version of the Licensed Work under this
32
+ License, whichever comes first, the Licensor hereby grants you rights under
33
+ the terms of the Change License, and the rights granted in the paragraph
34
+ above terminate.
35
+
36
+ If your use of the Licensed Work does not comply with the requirements
37
+ currently in effect as described in this License, you must purchase a
38
+ commercial license from the Licensor, its affiliated entities, or authorized
39
+ resellers, or you must refrain from using the Licensed Work.
40
+
41
+ All copies of the original and modified Licensed Work, and derivative works
42
+ of the Licensed Work, are subject to this License. This License applies
43
+ separately for each version of the Licensed Work and the Change Date may vary
44
+ for each version of the Licensed Work released by Licensor.
45
+
46
+ You must conspicuously display this License on each original or modified copy
47
+ of the Licensed Work. If you receive the Licensed Work in original or
48
+ modified form from a third party, the terms and conditions set forth in this
49
+ License apply to your use of that work.
50
+
51
+ Any use of the Licensed Work in violation of this License will automatically
52
+ terminate your rights under this License for the current and all other
53
+ versions of the Licensed Work.
54
+
55
+ This License does not grant you any right in any trademark or logo of
56
+ Licensor or its affiliates (provided that you may use a trademark or logo of
57
+ Licensor as expressly required by this License).
58
+
59
+ TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
60
+ AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
61
+ EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
62
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
63
+ TITLE.
64
+
65
+ MariaDB hereby grants you permission to use this License's text to license
66
+ your works, and to refer to it using the trademark "Business Source License",
67
+ as long as you comply with the Covenants of Licensor below.
68
+
69
+ Covenants of Licensor
70
+
71
+ In consideration of the right to use this License's text and the "Business
72
+ Source License" name and trademark, Licensor covenants to MariaDB, and to all
73
+ other recipients of the licensed work to be provided by Licensor:
74
+
75
+ 1. To specify as the Change License the GPL Version 2.0 or any later version,
76
+ or a license that is compatible with GPL Version 2.0 or a later version,
77
+ where "compatible" means that software provided under the Change License can
78
+ be included in a program with software provided under GPL Version 2.0 or a
79
+ later version. Licensor may specify additional Change Licenses without
80
+ limitation.
81
+
82
+ 2. To either: (a) specify an additional grant of rights to use that does not
83
+ impose any additional restriction on the right granted in this License, as
84
+ the Additional Use Grant; or (b) insert the text "None".
85
+
86
+ 3. To specify a Change Date.
87
+
88
+ 4. Not to modify this License in any other way.
package/README.md CHANGED
@@ -6,41 +6,36 @@
6
6
  <a href="https://www.npmjs.com/package/@yodlpay/react-native"><img alt="npm version" src="https://img.shields.io/npm/v/@yodlpay/react-native.svg"></a>
7
7
  <a href="https://www.npmjs.com/package/@yodlpay/react-native"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@yodlpay/react-native.svg"></a>
8
8
  <a href="./README.md#license"><img alt="license" src="https://img.shields.io/npm/l/@yodlpay/react-native.svg"></a>
9
+ <img alt="types included" src="https://img.shields.io/npm/types/@yodlpay/react-native.svg">
9
10
  <img alt="platforms" src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android-blue">
10
11
  </p>
11
12
 
12
- [Yodl](https://yodl.me) is a payments protocol that connects crypto to the world's local payment rails: users pay in stablecoins by scanning everyday QR codes — Pix in Brazil, transfers in Argentina, and more — while merchants receive their local currency and users keep self-custody of their funds, often at FX rates that beat Visa and Mastercard.
13
+ Drop-in crypto payments for React Native. You bring an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) wallet provider; the SDK renders the Yodl payment UI in a hardened, origin-locked WebView and handles the RPC bridge and on-chain execution. Users keep self-custody and often settle at FX rates that beat Visa/Mastercard.
13
14
 
14
- The `@yodlpay/react-native` SDK brings that entire experience into your app with a single drop-in component. It wraps the Yodl UI in a hardened, origin-locked surface with an injected [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) provider, so you bring the wallet and the SDK handles the payment UI, the RPC bridge, and the on-chain execution flow.
15
+ The provider interface is always plain **EIP-1193**. Transaction **batching and paymasters** ride on top via **[EIP-5792](https://eips.ethereum.org/EIPS/eip-5792)** (`wallet_sendCalls`) — available when your wallet supports EIP-5792 natively, or through the optional [EIP-7702 add-on](#optional-eip-7702-fallback) for wallets that don't.
15
16
 
16
- ## Why Yodl
17
-
18
- - **Real-world spending, not just transfers** — your users pay real merchants via local QR codes; merchants get paid in their own currency without touching crypto.
19
- - **Self-custody by default** — funds stay in the user's wallet until the moment of payment. No deposits, no intermediaries holding balances.
20
- - **Better rates than cards** — settling on-chain regularly beats Visa/Mastercard FX, a tangible reason for users to choose your app abroad.
21
- - **Ship in an afternoon, not a quarter** — no payment UI to build, no RPC plumbing to maintain, no chain-by-chain edge cases to chase.
22
- - **Works with the wallets your users already have** — any EIP-1193 provider, zero lock-in.
23
- - **Secure by construction** — the payment surface is origin-locked and sandboxed, with no security configuration to get wrong.
17
+ ```tsx
18
+ import { createSdk, YodlProvider, YodlPayment } from '@yodlpay/react-native';
24
19
 
25
- ## Features
20
+ const sdk = createSdk({
21
+ integrationId: 'your-app',
22
+ supportedChainIds: [1, 8453],
23
+ });
26
24
 
27
- - **Wallet-agnostic** — works with any EIP-1193 provider: Privy, MetaMask, Coinbase Wallet, Rainbow, WalletConnect, and more.
28
- - **Two drop-in components** — `<YodlPayment>` for QR-driven payments and `<YodlDashboard>` for the full account view.
29
- - **Hardened by default** — the Yodl UI is locked to the configured Yodl origin and off-origin navigation is blocked. No security config required.
30
- - **Batched transactions** — bridges [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) (`wallet_sendCalls`) to the wallet provider and falls back to sequential non-atomic sends only when the request explicitly allows it.
31
- - **Multi-chain** — Ethereum, Arbitrum, Base, Polygon, Optimism, BNB Chain, and Gnosis out of the box.
32
- - **Fully typed** — ships first-class TypeScript types for every component, prop, and config option.
25
+ // provider, address, and chainId are the live wallet state from your wallet SDK
26
+ <YodlProvider sdk={sdk} provider={walletProvider} address={address} chainId={chainId}>
27
+ <YodlPayment qrData={scannedQr} onTransactionSent={(tx) => console.log(tx)} />
28
+ </YodlProvider>;
29
+ ```
33
30
 
34
- ## Table of Contents
31
+ ## Contents
35
32
 
36
- - [Why Yodl](#why-yodl)
37
33
  - [Requirements](#requirements)
38
34
  - [Installation](#installation)
39
- - [Base SDK](#base-sdk)
40
35
  - [Quick Start](#quick-start)
36
+ - [Why Yodl](#why-yodl)
37
+ - [Features](#features)
41
38
  - [Platform Notes](#platform-notes)
42
- - [Native builds](#native-builds)
43
- - [Hermes / BigInt](#hermes--bigint)
44
39
  - [Usage](#usage)
45
40
  - [Full example](#full-example)
46
41
  - [Optional EIP-7702 fallback](#optional-eip-7702-fallback)
@@ -51,71 +46,55 @@ The `@yodlpay/react-native` SDK brings that entire experience into your app with
51
46
 
52
47
  ## Requirements
53
48
 
54
- | Requirement | Version |
55
- | ------------------ | ----------------- |
56
- | React | `>= 18` |
57
- | React Native | `>= 0.72` |
58
- | Hermes engine | Enabled (default) |
49
+ | Requirement | Version |
50
+ | ------------- | ----------------- |
51
+ | React | `>= 18` |
52
+ | React Native | `>= 0.72` |
53
+ | Hermes engine | Enabled (default) |
59
54
 
60
- > This package uses native modules, so it requires a custom dev build — it does **not** run in Expo Go. See [Native builds](#native-builds).
55
+ > Uses native modules (`react-native-webview`), so it requires a custom dev build — it does **not** run in Expo Go. See [Platform Notes](#platform-notes).
61
56
 
62
57
  ## Installation
63
58
 
64
- ### Base SDK
59
+ Install the SDK and its `react-native-webview` peer dependency, then rebuild the native app.
65
60
 
66
- For Expo apps, install the SDK and WebView with Expo so `react-native-webview` resolves to the version that matches your installed Expo SDK:
61
+ **Expo** (resolves the WebView version to your Expo SDK):
67
62
 
68
63
  ```bash
69
64
  npx expo install @yodlpay/react-native react-native-webview
65
+ npx expo run:ios # or: npx expo run:android
70
66
  ```
71
67
 
72
- Then rebuild the native app:
73
-
74
- ```bash
75
- npx expo run:ios
76
- # or
77
- npx expo run:android
78
- ```
79
-
80
- For bare React Native apps, install the SDK and WebView with your package manager:
81
-
82
- ```bash
83
- # npm
84
- npm install @yodlpay/react-native react-native-webview
85
-
86
- # pnpm
87
- pnpm add @yodlpay/react-native react-native-webview
88
-
89
- # yarn
90
- yarn add @yodlpay/react-native react-native-webview
91
- ```
92
-
93
- Then install iOS pods and rebuild the app:
68
+ **Bare React Native:**
94
69
 
95
70
  ```bash
96
- npx pod-install
71
+ npm install @yodlpay/react-native react-native-webview # or: pnpm add / yarn add
72
+ npx pod-install # iOS
97
73
  ```
98
74
 
99
- That is the full base install.
75
+ Then rebuild the app. That's the full install.
100
76
 
101
77
  ## Quick Start
102
78
 
103
79
  Three steps: create the SDK once, wrap your screen in `<YodlProvider>`, render `<YodlPayment>`.
104
80
 
105
81
  ```tsx
106
- import { createSdk, YodlProvider, YodlPayment } from '@yodlpay/react-native';
82
+ import { createSdk, isPaymentQr, YodlProvider, YodlPayment } from '@yodlpay/react-native';
107
83
 
84
+ // 1. Create the SDK once, app-wide.
108
85
  const sdk = createSdk({
109
- integrationId: 'privy-wallet',
110
- supportedChainIds: [1, 42161, 8453, 137, 10, 56, 100],
86
+ integrationId: 'your-app', // identifies your app to Yodl
87
+ supportedChainIds: [1, 8453],
111
88
  });
112
89
 
113
- export function PaymentScreen({ qrData, provider, address }) {
114
- // bail out early if the scanned QR isn't a Yodl payment
115
- if (!sdk.qr.isPaymentQr(qrData)) return null;
90
+ // provider, address, and chainId are the live wallet state from your wallet SDK's hooks.
91
+ export function PaymentScreen({ qrData, provider, address, chainId }) {
92
+ // 2. Bail out early if the scanned QR isn't a Yodl payment (no SDK instance needed).
93
+ if (!isPaymentQr(qrData)) return null;
116
94
 
95
+ // 3. Supply live wallet state; the SDK keeps the Yodl UI in sync with it.
117
96
  return (
118
- <YodlProvider sdk={sdk} provider={provider} address={address} chainId={1}>
97
+ <YodlProvider sdk={sdk} provider={provider} address={address} chainId={chainId}>
119
98
  <YodlPayment
120
99
  qrData={qrData}
121
100
  onTransactionSent={(txHash) => console.log('paid:', txHash)}
@@ -126,97 +105,109 @@ export function PaymentScreen({ qrData, provider, address }) {
126
105
  }
127
106
  ```
128
107
 
129
- > After installing the base SDK and rebuilding the native app, you can render the component.
108
+ `provider`, `address`, and `chainId` all come from your wallet SDK (Privy, MetaMask, Coinbase Wallet, WalletConnect, …) — `chainId` is the chain the wallet is **currently** on, not a fixed value. See [`<YodlProvider />`](#yodlprovider-) for how this state drives the UI, and the [full example](#full-example) for scanning, the dashboard, and lifecycle events.
130
109
 
131
- ## Platform Notes
110
+ ## Why Yodl
111
+
112
+ > **Pay like a local, with crypto.** Live in Argentina, Brazil, the Philippines, and Vietnam — across Pix, Mercado Pago, QRPh, and VietQR.
113
+
114
+ - **Real-world spending** — users pay merchants by scanning everyday local QR codes; merchants get their own currency, never crypto.
115
+ - **Self-custody** — funds stay in the user's wallet until the moment of payment. No deposits, no custodian.
116
+ - **Beats card FX** — on-chain settlement regularly comes in cheaper than Visa/Mastercard abroad.
117
+ - **Ship in an afternoon** — one component, no payment UI or RPC plumbing to build.
132
118
 
133
- Most apps only need the base install command and a native rebuild. These notes cover platform-specific cases.
119
+ [Learn more about Yodl Pay →](https://yodl.me)
134
120
 
135
- ### Native builds
121
+ ## Features
122
+
123
+ - **Wallet-agnostic** — any EIP-1193 provider (Privy, MetaMask, Coinbase Wallet, Rainbow, WalletConnect).
124
+ - **Two drop-in components** — `<YodlPayment>` for QR payments, `<YodlDashboard>` for the account view.
125
+ - **Hardened by default** — UI locked to the Yodl origin, off-origin navigation blocked. No config.
126
+ - **Batching & paymasters** — bridges [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) (`wallet_sendCalls`); native support passes through, or add the [EIP-7702 provider](#optional-eip-7702-fallback) for atomic batching + gas sponsorship.
127
+ - **Multi-chain** — Ethereum, Arbitrum, Base, Polygon, Optimism, BNB Chain, Gnosis.
128
+ - **Fully typed** — first-class TypeScript throughout.
136
129
 
137
- The base SDK renders the Yodl UI with `react-native-webview`, so it does **not** run in Expo Go. Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/) (`npx expo run:ios` / `npx expo run:android`) or a bare React Native build.
130
+ ## Platform Notes
138
131
 
139
- ### Hermes / BigInt
132
+ Most apps just need the install above and a native rebuild. Edge cases:
140
133
 
141
- The SDK uses `BigInt`, which requires the Hermes engine (enabled by default in React Native `0.70+` and all recent Expo SDKs). If you've disabled Hermes, re-enable it or add a `BigInt` polyfill.
134
+ - **Not Expo Go** — uses the native `react-native-webview`, so run a [dev build](https://docs.expo.dev/develop/development-builds/introduction/) (`npx expo run:ios` / `run:android`) or bare React Native.
135
+ - **Hermes required** — the SDK uses `BigInt` (Hermes is on by default in RN `0.70+`). If you disabled Hermes, re-enable it or add a `BigInt` polyfill.
142
136
 
143
137
  ## Usage
144
138
 
145
- The package mirrors `@yodlpay/sdk-core`'s façade: create the SDK once with `createSdk(config)`, then use the namespaced instance (`sdk.qr.*`, `sdk.prefetch()`) and the components. Wallet state is supplied at runtime via `<YodlProvider>`.
139
+ Create the SDK once with `createSdk(config)` and supply wallet state at runtime via `<YodlProvider>`. Stateless helpers like `isPaymentQr(qrData)` are standalone exports — no SDK instance required to call them.
146
140
 
147
141
  ### Full example
148
142
 
143
+ **`sdk.ts`** — create the instance once, app-wide:
144
+
149
145
  ```tsx
150
- // sdk.ts — create the instance once, app-wide
151
146
  import { createSdk } from '@yodlpay/react-native';
152
147
 
153
148
  export const sdk = createSdk({
154
- integrationId: 'privy-wallet',
149
+ integrationId: 'your-app',
155
150
  // yodlUiBaseUrl defaults to https://sdk-webview.yodl.me
156
151
  supportedChainIds: [1, 42161, 8453, 137, 10, 56, 100],
157
152
  });
153
+ ```
154
+
155
+ **`PaymentScreen.tsx`** — scan → pay → back, plus the dashboard:
158
156
 
159
- // App.tsx
160
- import { useEffect, useState } from 'react';
161
- import { View, Button } from 'react-native';
162
- import {
163
- YodlProvider,
164
- YodlPayment,
165
- YodlDashboard,
166
- } from '@yodlpay/react-native';
157
+ ```tsx
158
+ import { useState } from 'react';
159
+ import { Button, Text, View } from 'react-native';
160
+ import { isPaymentQr, YodlProvider, YodlPayment, YodlDashboard } from '@yodlpay/react-native';
167
161
  import { sdk } from './sdk';
162
+ import { useWallet } from './wallet'; // your wallet SDK (Privy, WalletConnect, …)
163
+ import { QrScanner } from './QrScanner'; // your camera component, e.g. expo-camera
168
164
 
169
- export default function App() {
170
- const [screen, setScreen] = useState<'idle' | 'pay' | 'dashboard'>('idle');
171
- const [qrData, setQrData] = useState<string | null>(null);
165
+ type Screen = 'scan' | 'pay' | 'dashboard';
172
166
 
173
- // optional: warm caches early (no-op stub today)
174
- useEffect(() => {
175
- sdk.prefetch();
176
- }, []);
167
+ export function PaymentScreen() {
168
+ // `provider` is your EIP-1193 wallet. If it already supports EIP-5792 natively,
169
+ // pass it as-is; if not, wrap it with withYodl7702(...) for batching/paymasters (see below).
170
+ // `address`/`chainId` track the wallet.
171
+ const { provider, address, chainId, isConnected } = useWallet();
172
+ const [screen, setScreen] = useState<Screen>('scan');
173
+ const [qrData, setQrData] = useState<string | null>(null);
177
174
 
178
- // from your wallet SDK (Privy, MetaMask, Coinbase, WalletConnect, ...)
179
- const provider = useWallet().getProvider(); // EIP-1193
180
- const address = useWallet().address;
175
+ if (!isConnected) {
176
+ return <Text>Connect a wallet to continue.</Text>;
177
+ }
181
178
 
182
- function onScan(scanned: string) {
183
- if (!sdk.qr.isPaymentQr(scanned)) {
184
- alert('Not a Yodl-supported QR');
185
- return;
186
- }
179
+ function handleScan(scanned: string) {
180
+ // Guard before rendering — no SDK instance needed for the check.
181
+ if (!isPaymentQr(scanned)) return; // not a Yodl QR: keep scanning
187
182
  setQrData(scanned);
188
183
  setScreen('pay');
189
184
  }
190
185
 
191
186
  return (
192
- <YodlProvider
193
- sdk={sdk}
194
- provider={provider}
195
- address={address}
196
- chainId={1}
197
- >
198
- {screen === 'idle' && (
199
- <View style={{ flex: 1, justifyContent: 'center', gap: 12 }}>
200
- <Button
201
- title="Scan to pay"
202
- onPress={() => onScan(scanner.getResult())}
203
- />
204
- <Button
205
- title="Open dashboard"
206
- onPress={() => setScreen('dashboard')}
207
- />
187
+ <YodlProvider sdk={sdk} provider={provider} address={address} chainId={chainId}>
188
+ {screen === 'scan' && (
189
+ <View style={{ flex: 1, gap: 12 }}>
190
+ <QrScanner onScan={handleScan} />
191
+ <Button title="Open dashboard" onPress={() => setScreen('dashboard')} />
208
192
  </View>
209
193
  )}
210
194
 
211
195
  {screen === 'pay' && qrData && (
212
196
  <YodlPayment
213
197
  qrData={qrData}
214
- onTransactionSent={(txHash) => console.log('tx:', txHash)}
215
- onError={(err) => console.error(err)}
198
+ onTransactionSent={(txHash) => console.log('submitted:', txHash)}
199
+ onPaymentDetails={(details) => {
200
+ // 'submitted' | 'processing' | 'success' | 'failure'
201
+ if (details.status === 'success') setScreen('scan'); // done → scan again
202
+ }}
203
+ onError={(err) => {
204
+ console.error(err);
205
+ setScreen('scan');
206
+ }}
216
207
  />
217
208
  )}
218
209
 
219
- {screen === 'dashboard' && <YodlDashboard />}
210
+ {screen === 'dashboard' && <YodlDashboard onError={console.error} />}
220
211
  </YodlProvider>
221
212
  );
222
213
  }
@@ -224,18 +215,31 @@ export default function App() {
224
215
 
225
216
  ### Optional EIP-7702 fallback
226
217
 
227
- Most wallets do not need this. `@yodlpay/react-native` uses your EIP-1193 provider as the wallet transport and forwards the EIP-5792 wallet call methods when the wallet supports them natively.
218
+ **Native wallet support is always preferred** — if your wallet handles EIP-5792 (`wallet_sendCalls`) itself, pass it straight through and skip this section. `@yodlpay/react-native` forwards those calls natively whenever the wallet supports them. The add-on below is purely a fallback for wallets that don't.
228
219
 
229
- Add `@yodlpay/react-native-eip-7702-provider` only when the wallet lacks the atomic EIP-5792 `wallet_sendCalls` support your flow requires, can sign EIP-7702 authorizations, and you want Yodl to provide that fallback path. The add-on wraps the same provider, advertises the fallback through `wallet_getCapabilities`, and still lets native `wallet_sendCalls` win when the wallet supports it.
220
+ Add [`@yodlpay/react-native-eip-7702-provider`](https://www.npmjs.com/package/@yodlpay/react-native-eip-7702-provider) only when the wallet lacks the atomic EIP-5792 `wallet_sendCalls` support your flow requires, can sign EIP-7702 authorizations, and you want Yodl to provide that fallback path. The add-on wraps the same provider and advertises **atomic batching** (`atomic: ready`) plus **paymaster support** (`paymasterService`) through `wallet_getCapabilities` — so batched, gas-sponsored calls work even on wallets without native EIP-5792, while native `wallet_sendCalls` still wins when the wallet supports it.
230
221
 
231
222
  ```tsx
232
- import { withYodl7702 } from '@yodlpay/react-native-eip-7702-provider';
223
+ import { signAuthorizationViaProvider, withYodl7702 } from '@yodlpay/react-native-eip-7702-provider';
233
224
  import { YodlProvider, YodlPayment } from '@yodlpay/react-native';
234
225
 
226
+ // Bring your own RPC + bundler — the add-on ships no defaults, so 7702 traffic
227
+ // runs through your endpoints. List only the chains you can actually serve
228
+ // (independent of the SDK's `supportedChainIds`).
235
229
  const provider = withYodl7702(walletProvider, {
236
- address,
237
- chainId,
238
- supportedChainIds: [1, 42161, 8453, 137, 10, 56, 100],
230
+ chains: [
231
+ {
232
+ id: 8453,
233
+ rpcUrl: 'https://your-rpc.example/8453',
234
+ bundlerUrl: 'https://api.pimlico.io/v2/8453/rpc?apikey=YOUR_KEY',
235
+ },
236
+ ],
237
+ // Required: you price each fallback UserOperation (the add-on stays bundler-
238
+ // agnostic). See the add-on's "Gas pricing" section for caching guidance.
239
+ estimateUserOperationFees: async (chainId) => getYourBundlerGasPrice(chainId),
240
+ // Required: you sign the EIP-7702 authorization (no universal wallet method).
241
+ // The add-on ships `signAuthorizationViaProvider` to try for EIP-1193 wallets.
242
+ signAuthorization: signAuthorizationViaProvider(walletProvider),
239
243
  });
240
244
 
241
245
  <YodlProvider sdk={sdk} provider={provider} address={address} chainId={chainId}>
@@ -243,35 +247,41 @@ const provider = withYodl7702(walletProvider, {
243
247
  </YodlProvider>;
244
248
  ```
245
249
 
246
- Base SDK users can skip this optional add-on entirely. Without it, unsupported EIP-5792 requests can still fall back to sequential `eth_sendTransaction` only when the request explicitly allows non-atomic execution.
247
-
248
- See [`@yodlpay/react-native-eip-7702-provider`](../react-native-eip-7702-provider/README.md) for installation and fallback details.
250
+ Base SDK users can skip this entirely. Without it, a wallet that lacks native EIP-5792 `wallet_sendCalls` simply can't batch — the base SDK forwards the request and the wallet's own response (it performs no sequential fallback of its own).
249
251
 
250
252
  ## API Reference
251
253
 
252
254
  ### `createSdk(config)`
253
255
 
254
- Returns a `Yodl` instance. `config`:
256
+ Returns a `Yodl` instance.
255
257
 
256
- | Option | Type | Required | Default | Description |
257
- | ------------------- | ---------- | -------- | ----------------------------- | ------------------------------------------------ |
258
- | `integrationId` | `string` | Yes | — | Identifies your app in Yodl-owned request headers |
259
- | `yodlUiBaseUrl` | `string` | No | `https://sdk-webview.yodl.me` | Base URL for the Yodl UI |
260
- | `supportedChainIds` | `number[]` | Yes | — | Chain IDs the wallet can switch to |
258
+ | Option | Type | Required | Default | Description |
259
+ | ------------------- | ----------------------------- | -------- | ----------------------------- | -------------------------------------------------------------------------- |
260
+ | `integrationId` | `string` | Yes | — | Identifies your app in Yodl-owned request headers |
261
+ | `supportedChainIds` | `number[]` | Yes | — | Chain IDs the wallet can switch to |
262
+ | `yodlUiBaseUrl` | `string` | No | `https://sdk-webview.yodl.me` | Base URL for the Yodl UI |
261
263
 
262
- `integrationId` must be a non-empty string, for example `privy-wallet`. The SDK sends it with package metadata on Yodl-owned requests:
264
+ `integrationId` must be a non-empty string (e.g. `your-app`). The SDK sends it with package metadata on Yodl-owned requests:
263
265
 
264
266
  ```txt
265
- X-Yodl-Integration-Id: privy-wallet
267
+ X-Yodl-Integration-Id: your-app
266
268
  X-Yodl-SDK-Name: @yodlpay/react-native
267
- X-Yodl-SDK-Version: 0.1.0
269
+ X-Yodl-SDK-Version: <installed package version>
268
270
  ```
269
271
 
270
272
  Instance members:
271
273
 
272
274
  - **`sdk.config`** — the resolved config (read-only).
273
- - **`sdk.qr.isPaymentQr(qrData)`** — `string \| string[]` → `boolean`. True if any entry is a Yodl-supported payment QR.
274
- - **`sdk.prefetch()`** — `Promise<void>`. No-op stub today; reserved for future cache warming.
275
+
276
+ ### `isPaymentQr(qrData)`
277
+
278
+ Standalone helper — `string | string[]` → `boolean`. Returns `true` if any entry is a Yodl-supported payment QR. Pure: it takes no SDK instance, so you can guard a render before `<YodlProvider>` is mounted.
279
+
280
+ ```tsx
281
+ import { isPaymentQr } from '@yodlpay/react-native';
282
+
283
+ if (!isPaymentQr(scannedQr)) return null;
284
+ ```
275
285
 
276
286
  ### `<YodlProvider />`
277
287
 
@@ -280,56 +290,57 @@ Supplies the SDK instance and wallet state to the components. Render it once, hi
280
290
  | Prop | Type | Required | Description |
281
291
  | ---------- | ----------------- | -------- | ------------------------------------- |
282
292
  | `sdk` | `Yodl` | Yes | Instance from `createSdk()` |
283
- | `provider` | `EIP1193Provider` | Yes | EIP-1193 provider from any wallet SDK |
293
+ | `provider` | `EIP1193Provider` | Yes | EIP-1193 provider from any wallet SDK. Prefer the wallet's native EIP-5792 support; only if it lacks it, wrap with `withYodl7702(...)` for the [EIP-7702 fallback](#optional-eip-7702-fallback) |
284
294
  | `address` | `string` | Yes | Connected wallet address |
285
295
  | `chainId` | `number` | Yes | Chain ID the wallet is currently on |
286
296
 
297
+ `address` and `chainId` are the wallet's **live** account and chain — pass them straight from your wallet SDK's hooks (e.g. `useWallets()`, `useAccount()`), not as fixed values. They tell the embedded Yodl UI who is connected and on which chain, and the SDK pushes `accountsChanged` / `chainChanged` into the UI whenever they change — so keep them updated when the user switches account or network. (The `provider` is used only as the RPC/signing transport.)
298
+
287
299
  ### `<YodlPayment />`
288
300
 
289
- Renders the payment flow for a scanned QR code.
301
+ Renders the payment flow for a scanned QR code. Renders nothing if `qrData` is empty or unsupported.
290
302
 
291
- | Prop | Type | Required | Description |
292
- | ------------------- | --------------------------------------- | -------- | ---------------------------------------------------------------------- |
293
- | `qrData` | `string` | Yes | Raw QR data string |
294
- | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
295
- | `onPaymentDetails` | `(details: YodlPaymentDetails) => void` | No | Called with generalized payment lifecycle details emitted by the WebView |
296
- | `onError` | `(error: Error) => void` | No | Called on RPC / payment errors |
297
- | `style` | `ViewStyle` | No | Container style |
303
+ | Prop | Type | Required | Description |
304
+ | ------------------- | --------------------------------------- | -------- | -------------------------------------------------- |
305
+ | `qrData` | `string` | Yes | Raw scanned QR data string |
306
+ | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
307
+ | `onPaymentDetails` | `(details: YodlPaymentDetails) => void` | No | Called with payment lifecycle details from the UI |
308
+ | `onError` | `(error: Error) => void` | No | Called on RPC / payment errors |
309
+ | `style` | `ViewStyle` | No | Container style |
298
310
 
299
311
  ### `<YodlDashboard />`
300
312
 
301
313
  Renders the full Yodl account dashboard.
302
314
 
303
- | Prop | Type | Required | Description |
304
- | ------------------- | --------------------------------------- | -------- | ---------------------------------------------------------------------- |
305
- | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
306
- | `onPaymentDetails` | `(details: YodlPaymentDetails) => void` | No | Called with generalized payment lifecycle details emitted by the WebView |
307
- | `onError` | `(error: Error) => void` | No | Called on RPC errors |
308
- | `style` | `ViewStyle` | No | Container style |
315
+ | Prop | Type | Required | Description |
316
+ | ------------------- | --------------------------------------- | -------- | -------------------------------------------------- |
317
+ | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
318
+ | `onPaymentDetails` | `(details: YodlPaymentDetails) => void` | No | Called with payment lifecycle details from the UI |
319
+ | `onError` | `(error: Error) => void` | No | Called on RPC errors |
320
+ | `style` | `ViewStyle` | No | Container style |
309
321
 
310
322
  ### Payment details events
311
323
 
312
- `onPaymentDetails` is optional and additive. Existing `onTransactionSent(txHash)` and `onError(error)` behavior is unchanged.
313
-
314
- The Yodl WebView emits generalized payment lifecycle details after it has payment status information. The SDK forwards those details to `onPaymentDetails`. Normalized fields cover transaction hash, chain, lifecycle status, recipient, invoice, token amounts, refund state, and rewards when available. The original WebView/backend payload may be included under `raw`.
324
+ `onPaymentDetails` is optional and additive — `onTransactionSent(txHash)` and `onError(error)` behavior is unchanged.
315
325
 
316
- The SDK does not fetch transaction details directly; it only bridges WebView messages.
326
+ The Yodl UI emits generalized payment lifecycle details once it has payment status. The SDK forwards them to `onPaymentDetails`. Normalized fields cover transaction hash, chain, lifecycle status, recipient, invoice, token amounts, refund state, and rewards when available; the original payload may be included under `raw`. The SDK does not fetch transaction details itself — it only bridges UI messages.
317
327
 
318
328
  ## Security
319
329
 
320
330
  `<YodlPayment>` and `<YodlDashboard>` inject an EIP-1193 provider bound to the user's wallet, so the underlying Yodl UI is **locked to the configured Yodl origin** and off-origin navigation is blocked (`onShouldStartLoadWithRequest`). This prevents origin spoofing and mid-request navigation that could intercept signed responses. The injected provider also enforces a 30 s pending-request timeout.
321
331
 
322
- The bridge implements EIP-5792 v2 request handling without owning a smart-account stack: it forwards native `wallet_sendCalls`, `wallet_getCallsStatus`, `wallet_showCallsStatus`, and `wallet_getCapabilities` support from the supplied provider, and only falls back to sequential `eth_sendTransaction` when the request explicitly sets `atomicRequired: false`. Local fallback responses preserve EIP-5792 error codes for unsupported chains, duplicate ids, and unknown bundle ids. Use `@yodlpay/react-native-eip-7702-provider` when the host wallet needs Yodl's EIP-7702 fallback.
332
+ The bridge forwards EIP-5792 (`wallet_sendCalls`, `wallet_getCallsStatus`, `wallet_showCallsStatus`, `wallet_getCapabilities`) and all signing methods straight to the supplied wallet provider — it owns no smart-account stack and makes no RPC calls of its own (the embedded UI reads chain state through its own provider). For wallets without native EIP-5792, add `@yodlpay/react-native-eip-7702-provider` for atomic batching.
323
333
 
324
334
  ## Troubleshooting
325
335
 
326
- | Symptom | Cause & fix |
327
- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
328
- | `Can't find variable: BigInt` | Hermes is disabled. Re-enable Hermes or add a `BigInt` polyfill. See [Hermes / BigInt](#hermes--bigint). |
329
- | App crashes / blank screen in Expo Go | Native modules aren't available in Expo Go. Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/). |
330
- | `Yodl components must be rendered inside <YodlProvider>` | A component is mounted outside the provider. Wrap it in `<YodlProvider>`. |
331
- | Payment screen renders blank | `qrData` isn't a Yodl payment QR. Guard with `sdk.qr.isPaymentQr(qrData)` before rendering `<YodlPayment>`. |
336
+ | Symptom | Cause & fix |
337
+ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
338
+ | `Can't find variable: BigInt` | Hermes is disabled. Re-enable Hermes or add a `BigInt` polyfill. See [Platform Notes](#platform-notes). |
339
+ | App crashes / blank screen in Expo Go | Native modules aren't available in Expo Go. Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/). |
340
+ | `Yodl components must be rendered inside <YodlProvider>` | A component is mounted outside the provider. Wrap it in `<YodlProvider>`. |
341
+ | Payment screen renders blank | `qrData` isn't a Yodl payment QR. Guard with `isPaymentQr(qrData)` before rendering `<YodlPayment>`. |
342
+ | `webview-action providers are not supported yet` | The scanned QR maps to a provider whose hosted webview flow isn't supported yet. Catch it (e.g. via `onError` or an error boundary) and prompt a retry. |
332
343
 
333
344
  ## License
334
345
 
335
- MIT © Yodl
346
+ [BUSL-1.1](./LICENSE.md) © Yodl
@@ -0,0 +1,32 @@
1
+ THIRD-PARTY NOTICES
2
+ ===================
3
+
4
+ @yodlpay/react-native is licensed under the Business Source License 1.1 (see LICENSE.md).
5
+
6
+ Its published bundle inlines the following third-party software, included
7
+ here under their respective licenses:
8
+
9
+ -------------------------------------------------------------------------------
10
+ promptparse (https://github.com/maythiwat/promptparse) — MIT
11
+ -------------------------------------------------------------------------------
12
+ MIT License
13
+
14
+ Copyright (c) 2023 Maythiwat Chomchuen
15
+
16
+ Permission is hereby granted, free of charge, to any person obtaining a copy
17
+ of this software and associated documentation files (the "Software"), to deal
18
+ in the Software without restriction, including without limitation the rights
19
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
20
+ copies of the Software, and to permit persons to whom the Software is
21
+ furnished to do so, subject to the following conditions:
22
+
23
+ The above copyright notice and this permission notice shall be included in all
24
+ copies or substantial portions of the Software.
25
+
26
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
27
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
28
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
29
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
30
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
31
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32
+ SOFTWARE.