@yodlpay/react-native 0.1.0

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/README.md ADDED
@@ -0,0 +1,377 @@
1
+ # @yodlpay/react-native
2
+
3
+ > Let your users pay real-world merchants with crypto, straight from your React Native app. Scan a local QR, render one component, settle on-chain — [Yodl](https://yodl.me) turns stablecoins into the merchant's local currency.
4
+
5
+ <p>
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
+ <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
+ <a href="./README.md#license"><img alt="license" src="https://img.shields.io/npm/l/@yodlpay/react-native.svg"></a>
9
+ <img alt="platforms" src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android-blue">
10
+ </p>
11
+
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
+
14
+ The `@yodlpay/react-native` SDK brings that entire experience into your app with a single drop-in component. It wraps the Yodl miniapp in a hardened, origin-locked WebView 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
+
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.
24
+
25
+ ## Features
26
+
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 WebView is locked to the configured Yodl origin and off-origin navigation is blocked. No security config required.
30
+ - **Batched transactions** — implements [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) (`wallet_sendCalls`) with native → EIP-7702 → sequential fallback, transparently.
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.
33
+
34
+ ## Table of Contents
35
+
36
+ - [Why Yodl](#why-yodl)
37
+ - [Requirements](#requirements)
38
+ - [Installation](#installation)
39
+ - [Quick Start](#quick-start)
40
+ - [Setup](#setup)
41
+ - [1. Crypto polyfill (required)](#1-crypto-polyfill-required)
42
+ - [2. Enable Hermes / BigInt](#2-enable-hermes--bigint)
43
+ - [3. Metro configuration](#3-metro-configuration)
44
+ - [4. Expo notes](#4-expo-notes)
45
+ - [Usage](#usage)
46
+ - [Full example](#full-example)
47
+ - [Controlling the WebView (back / reload)](#controlling-the-webview-back--reload)
48
+ - [API Reference](#api-reference)
49
+ - [Security](#security)
50
+ - [Troubleshooting](#troubleshooting)
51
+ - [License](#license)
52
+
53
+ ## Requirements
54
+
55
+ | Requirement | Version |
56
+ | ------------------ | ----------------- |
57
+ | React | `>= 18` |
58
+ | React Native | `>= 0.72` |
59
+ | Hermes engine | Enabled (default) |
60
+ | Node (for tooling) | `>= 18` |
61
+
62
+ > This package uses native modules, so it requires a custom dev build — it does **not** run in Expo Go. See [Expo notes](#4-expo-notes).
63
+
64
+ ## Installation
65
+
66
+ ### Expo
67
+
68
+ Use `npx expo install` so Expo resolves native-module versions (`react-native-webview`, `react-native-get-random-values`) that match your installed SDK:
69
+
70
+ ```bash
71
+ npx expo install @yodlpay/react-native react-native-webview viem react-native-get-random-values
72
+ ```
73
+
74
+ Then create a [development build](https://docs.expo.dev/develop/development-builds/introduction/) (`npx expo run:ios` / `npx expo run:android`) — native modules don't run in Expo Go.
75
+
76
+ ### React Native (bare)
77
+
78
+ ```bash
79
+ # npm
80
+ npm install @yodlpay/react-native react-native-webview viem react-native-get-random-values
81
+
82
+ # pnpm
83
+ pnpm add @yodlpay/react-native react-native-webview viem react-native-get-random-values
84
+
85
+ # yarn
86
+ yarn add @yodlpay/react-native react-native-webview viem react-native-get-random-values
87
+ ```
88
+
89
+ Then install iOS pods and rebuild:
90
+
91
+ ```bash
92
+ npx pod-install
93
+ ```
94
+
95
+ ### Peer dependencies
96
+
97
+ You provide these in your app; the SDK declares them as peers so it shares a single copy with your project.
98
+
99
+ | Package | Why it's needed |
100
+ | ---------------------- | --------------------------------------------------------- |
101
+ | `react` | React runtime (`>= 18`) |
102
+ | `react-native` | React Native runtime (`>= 0.72`) |
103
+ | `react-native-webview` | Renders the Yodl miniapp and bridges RPC messages |
104
+ | `viem` | Powers public clients and the EIP-7702 smart-account flow |
105
+
106
+ ### Runtime requirement
107
+
108
+ `react-native-get-random-values` is **not a peer dependency**, but it is a required runtime polyfill — install it and import it first (see below).
109
+
110
+ | Package | Why it's needed |
111
+ | -------------------------------- | --------------------------------------------------------------------------------- |
112
+ | `react-native-get-random-values` | Web Crypto polyfill required by `viem` (see [Setup](#1-crypto-polyfill-required)) |
113
+
114
+ > **Required:** add `import 'react-native-get-random-values'` as the **first line of your entry file** (`index.js` / `index.ts`), before any other import. `viem` reads `crypto.getRandomValues()` at module load, so the polyfill must run first or payments will throw `crypto.getRandomValues() not supported`. For bare React Native, also run `npx pod-install`. See [Setup §1](#1-crypto-polyfill-required).
115
+
116
+ ## Quick Start
117
+
118
+ Three steps: create the SDK once, wrap your screen in `<YodlProvider>`, render `<YodlPayment>`.
119
+
120
+ ```tsx
121
+ import { createSdk, YodlProvider, YodlPayment } from '@yodlpay/react-native';
122
+
123
+ const sdk = createSdk();
124
+
125
+ export function PaymentScreen({ qrData, provider, address }) {
126
+ // bail out early if the scanned QR isn't a Yodl payment
127
+ if (!sdk.qr.isPaymentQr(qrData)) return null;
128
+
129
+ return (
130
+ <YodlProvider sdk={sdk} provider={provider} address={address} chainId={1}>
131
+ <YodlPayment
132
+ qrData={qrData}
133
+ onTransactionSent={(txHash) => console.log('paid:', txHash)}
134
+ onError={(err) => console.error(err)}
135
+ />
136
+ </YodlProvider>
137
+ );
138
+ }
139
+ ```
140
+
141
+ > Make sure you've completed the one-time [Setup](#setup) below first — the crypto polyfill in particular is required before any payment will succeed.
142
+
143
+ ## Setup
144
+
145
+ A few one-time steps are required before the SDK works on a device or simulator. `viem` and the EIP-7702 smart-account flow (via `permissionless`) rely on Web Crypto and BigInt, neither of which is available in React Native out of the box.
146
+
147
+ ### 1. Crypto polyfill (required)
148
+
149
+ `viem` and `permissionless` call `crypto.getRandomValues()` for key, nonce, and signature operations. Import the polyfill **at the very top of your app entry file** (`index.js` / `App.tsx`) — before any other import:
150
+
151
+ ```tsx
152
+ // index.js — must be the FIRST import in your app
153
+ import 'react-native-get-random-values';
154
+
155
+ import { AppRegistry } from 'react-native';
156
+ import App from './App';
157
+ // ...
158
+ ```
159
+
160
+ > If you skip this, you'll see runtime errors like `crypto.getRandomValues() not supported` when sending a payment. On bare React Native, also run `npx pod-install` after installing the package. (Expo managed workflow can ignore the "CocoaPods is not supported" notice — it's harmless.)
161
+
162
+ ### 2. Enable Hermes / BigInt
163
+
164
+ 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.
165
+
166
+ ### 3. Metro configuration
167
+
168
+ The package ships a compiled build (ESM + CJS) and (in monorepos or when linked with `file:`) shares `react`, `react-native`, `react-native-webview`, and `viem` with your app. Wire up the provided Metro helper so these resolve correctly and the linked workspace is watched for live reload.
169
+
170
+ ```js
171
+ // metro.config.js
172
+ const { getDefaultConfig } = require('expo/metro-config'); // or '@react-native/metro-config'
173
+ const { withYodlReactNative } = require('@yodlpay/react-native/metro-config');
174
+
175
+ const config = getDefaultConfig(__dirname);
176
+
177
+ // If you have a custom resolveRequest, set it BEFORE calling the helper:
178
+ // config.resolver.resolveRequest = myCustomResolver;
179
+
180
+ module.exports = withYodlReactNative(config, __dirname);
181
+ ```
182
+
183
+ > For a plain (non-monorepo) install from npm, the Metro helper is optional — but it is required when consuming the package via workspace/`file:` linking.
184
+
185
+ ### 4. Expo notes
186
+
187
+ - This package uses native modules (`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`).
188
+ - No config plugin is required — `react-native-webview` autolinks. Just rebuild the dev client after installing native dependencies.
189
+
190
+ ## Usage
191
+
192
+ 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>`.
193
+
194
+ ### Full example
195
+
196
+ ```tsx
197
+ // index.js — MUST be the first import (Web Crypto polyfill for viem)
198
+ import 'react-native-get-random-values';
199
+
200
+ // sdk.ts — create the instance once, app-wide
201
+ import { createSdk } from '@yodlpay/react-native';
202
+
203
+ export const sdk = createSdk({
204
+ // webviewBaseUrl defaults to https://sdk-webview.yodl.me
205
+ supportedChainIds: [1, 42161, 8453, 137, 10, 56, 100],
206
+ });
207
+
208
+ // App.tsx
209
+ import { useEffect, useState } from 'react';
210
+ import { View, Button } from 'react-native';
211
+ import {
212
+ YodlProvider,
213
+ YodlPayment,
214
+ YodlDashboard,
215
+ } from '@yodlpay/react-native';
216
+ import { sdk } from './sdk';
217
+
218
+ export default function App() {
219
+ const [screen, setScreen] = useState<'idle' | 'pay' | 'dashboard'>('idle');
220
+ const [qrData, setQrData] = useState<string | null>(null);
221
+
222
+ // optional: warm caches early (no-op stub today)
223
+ useEffect(() => {
224
+ sdk.prefetch();
225
+ }, []);
226
+
227
+ // from your wallet SDK (Privy, MetaMask, Coinbase, WalletConnect, ...)
228
+ const provider = useWallet().getProvider(); // EIP-1193
229
+ const address = useWallet().address;
230
+
231
+ function onScan(scanned: string) {
232
+ if (!sdk.qr.isPaymentQr(scanned)) {
233
+ alert('Not a Yodl-supported QR');
234
+ return;
235
+ }
236
+ setQrData(scanned);
237
+ setScreen('pay');
238
+ }
239
+
240
+ return (
241
+ <YodlProvider
242
+ sdk={sdk}
243
+ provider={provider}
244
+ address={address}
245
+ chainId={1}
246
+ supportedChainIds={[1, 42161, 8453, 137, 10, 56, 100]}
247
+ >
248
+ {screen === 'idle' && (
249
+ <View style={{ flex: 1, justifyContent: 'center', gap: 12 }}>
250
+ <Button
251
+ title="Scan to pay"
252
+ onPress={() => onScan(scanner.getResult())}
253
+ />
254
+ <Button
255
+ title="Open dashboard"
256
+ onPress={() => setScreen('dashboard')}
257
+ />
258
+ </View>
259
+ )}
260
+
261
+ {screen === 'pay' && qrData && (
262
+ <YodlPayment
263
+ qrData={qrData}
264
+ onTransactionSent={(txHash) => console.log('tx:', txHash)}
265
+ onError={(err) => console.error(err)}
266
+ />
267
+ )}
268
+
269
+ {screen === 'dashboard' && <YodlDashboard />}
270
+ </YodlProvider>
271
+ );
272
+ }
273
+ ```
274
+
275
+ ### Controlling the WebView (back / reload)
276
+
277
+ `<YodlPayment>` and `<YodlDashboard>` forward a `YodlWebViewRef`, letting you drive WebView navigation imperatively — handy for wiring a hardware/Android back button.
278
+
279
+ ```tsx
280
+ import { useRef } from 'react';
281
+ import { Button } from 'react-native';
282
+ import { YodlPayment, type YodlWebViewRef } from '@yodlpay/react-native';
283
+
284
+ function PayScreen({ qrData }: { qrData: string }) {
285
+ const ref = useRef<YodlWebViewRef>(null);
286
+
287
+ return (
288
+ <>
289
+ <YodlPayment ref={ref} qrData={qrData} />
290
+ <Button title="Back" onPress={() => ref.current?.goBack()} />
291
+ <Button title="Reload" onPress={() => ref.current?.reload()} />
292
+ </>
293
+ );
294
+ }
295
+ ```
296
+
297
+ ## API Reference
298
+
299
+ ### `createSdk(config?)`
300
+
301
+ Returns a `Yodl` instance. `config`:
302
+
303
+ | Option | Type | Default | Description |
304
+ | ------------------- | ---------- | ------------------------------------ | ------------------------------------- |
305
+ | `webviewBaseUrl` | `string` | `https://sdk-webview.yodl.me` | Base URL for the Yodl miniapp WebView |
306
+ | `supportedChainIds` | `number[]` | `[1, 42161, 8453, 137, 10, 56, 100]` | Chain IDs the wallet can switch to |
307
+
308
+ Instance members:
309
+
310
+ - **`sdk.config`** — the resolved config (read-only).
311
+ - **`sdk.qr.isPaymentQr(qrData)`** — `string \| string[]` → `boolean`. True if any entry is a Yodl-supported payment QR.
312
+ - **`sdk.prefetch()`** — `Promise<void>`. No-op stub today; reserved for future cache warming.
313
+
314
+ ### `<YodlProvider />`
315
+
316
+ Supplies the SDK instance and wallet state to the components. Render it once, high in your tree.
317
+
318
+ | Prop | Type | Required | Description |
319
+ | ------------------- | ----------------- | -------- | --------------------------------------------------- |
320
+ | `sdk` | `Yodl` | Yes | Instance from `createSdk()` |
321
+ | `provider` | `EIP1193Provider` | Yes | EIP-1193 provider from any wallet SDK |
322
+ | `address` | `string` | Yes | Connected wallet address |
323
+ | `chainId` | `number` | Yes | Chain ID the wallet is currently on |
324
+ | `supportedChainIds` | `number[]` | No | Override for switchable chains (defaults to config) |
325
+
326
+ ### `<YodlPayment />`
327
+
328
+ Renders the payment flow for a scanned QR code. Forwards a [`YodlWebViewRef`](#controlling-the-webview-back--reload).
329
+
330
+ | Prop | Type | Required | Description |
331
+ | ------------------- | -------------------------- | -------- | ---------------------------------- |
332
+ | `qrData` | `string` | Yes | Raw QR data string |
333
+ | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
334
+ | `onError` | `(error: Error) => void` | No | Called on RPC / payment errors |
335
+ | `style` | `ViewStyle` | No | Container style |
336
+
337
+ ### `<YodlDashboard />`
338
+
339
+ Renders the full Yodl account dashboard. Forwards a [`YodlWebViewRef`](#controlling-the-webview-back--reload).
340
+
341
+ | Prop | Type | Required | Description |
342
+ | ------------------- | -------------------------- | -------- | ---------------------------------- |
343
+ | `onTransactionSent` | `(txHash: string) => void` | No | Called after a transaction is sent |
344
+ | `onError` | `(error: Error) => void` | No | Called on RPC errors |
345
+ | `style` | `ViewStyle` | No | Container style |
346
+
347
+ ### `YodlWebViewRef`
348
+
349
+ Imperative handle forwarded by both components.
350
+
351
+ | Member | Type | Description |
352
+ | ------------ | ------------ | ------------------------------------- |
353
+ | `goBack` | `() => void` | Navigate back within the WebView |
354
+ | `reload` | `() => void` | Reload the current WebView page |
355
+ | `webViewRef` | `RefObject` | Underlying `react-native-webview` ref |
356
+
357
+ ## Security
358
+
359
+ `<YodlPayment>` and `<YodlDashboard>` inject an EIP-1193 provider bound to the user's wallet, so the underlying WebView 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.
360
+
361
+ The WebView bridge implements EIP-5792 v2 (`wallet_sendCalls` with native → EIP-7702 → sequential fallback, `wallet_getCallsStatus`, `wallet_getCapabilities`) internally — no configuration required.
362
+
363
+ ## Troubleshooting
364
+
365
+ | Symptom | Cause & fix |
366
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
367
+ | `crypto.getRandomValues() not supported` | The polyfill isn't loaded first. Make `import 'react-native-get-random-values'` the very first line of your entry file. See [Setup §1](#1-crypto-polyfill-required). |
368
+ | `Can't find variable: BigInt` | Hermes is disabled. Re-enable Hermes or add a `BigInt` polyfill. See [Setup §2](#2-enable-hermes--bigint). |
369
+ | 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/). |
370
+ | `Unable to resolve module react-native-webview` (monorepo) | Shared deps aren't resolving. Add the Metro helper. See [Setup §3](#3-metro-configuration). |
371
+ | `Unable to resolve module ./...node_modules/.pnpm/ox@.../ox/_esm/index` | A transitive dep (e.g. `ox` via `viem`/`permissionless`) is resolving from the linked workspace instead of your app. Wire up the Metro helper (`withYodlReactNative`) — it redirects all third-party deps to your project root — then clear the cache: `npx expo start -c`. See [Setup §3](#3-metro-configuration). |
372
+ | `Yodl components must be rendered inside <YodlProvider>` | A component is mounted outside the provider. Wrap it in `<YodlProvider>`. |
373
+ | Payment screen renders blank | `qrData` isn't a Yodl payment QR. Guard with `sdk.qr.isPaymentQr(qrData)` before rendering `<YodlPayment>`. |
374
+
375
+ ## License
376
+
377
+ MIT © Yodl