From 49a57d0877f6a074ed0f3f9915f4607b91a10738 Mon Sep 17 00:00:00 2001 From: Bartek Date: Thu, 6 Aug 2026 18:46:17 +0200 Subject: [PATCH 1/2] SRA UI docs --- .../onramp/smart-routing-address/react-ui.mdx | 141 ++++++++++++++++++ vocs.config.tsx | 4 + 2 files changed, 145 insertions(+) create mode 100644 docs/pages/onramp/smart-routing-address/react-ui.mdx diff --git a/docs/pages/onramp/smart-routing-address/react-ui.mdx b/docs/pages/onramp/smart-routing-address/react-ui.mdx new file mode 100644 index 0000000..dd01d2f --- /dev/null +++ b/docs/pages/onramp/smart-routing-address/react-ui.mdx @@ -0,0 +1,141 @@ +# Smart Routing Address React UI + +`@zerodev/smart-routing-address-react-ui` is a drop-in deposit UI for +[Smart Routing Address](/onramp/smart-routing-address): a provider that creates +and caches the routing address, a prebuilt deposit screen, and hooks for +driving your own UI. To work with the address directly instead, use the +[SDK](/onramp/smart-routing-address/quickstart). + +## Installation + +Install the package alongside its peer dependencies: + +:::code-group + +```bash [npm] +npm i @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +``` + +```bash [yarn] +yarn add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +``` + +```bash [pnpm] +pnpm add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +``` + +```bash [bun] +bun add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +``` + +::: + +Import the stylesheet once at your app entry: + +```tsx +import '@zerodev/smart-routing-address-react-ui/styles.css' +``` + +## Usage + +Wrap the subtree with `SmartRoutingAddressProvider` and render +`` where the deposit UI should appear. On mount it +creates the routing address for `recipient` and shows the deposit screen — +the address with a QR code, the supported source tokens with fee estimates, +and the deposits as they arrive. Past deposits and per-deposit transaction +details are built-in steps. + +```tsx +import { + SmartRoutingAddress, + SmartRoutingAddressProvider, +} from '@zerodev/smart-routing-address-react-ui' +import { arbitrum } from 'viem/chains' + +function DepositModal({ userAddress, onClose }) { + return ( + + + + ) +} +``` + +The provider holds the config and the lazily created address; the screen is +rendered inline by you, so it fits any surface — a modal, a drawer, or a page. + +## Config + +`SmartRoutingAddressProvider` takes a single `config`: + +| Option | Type | Description | +| --- | --- | --- | +| `targetChainId` | `number` | Chain id where funds settle. Required. | +| `projectId` | `string` | ZeroDev project id; when non-empty it is appended to the server URL for every request. | +| `version` | `SmartRoutingAddressVersion` | Smart routing address version. Defaults to the latest stable. | +| `actions` | `CreateSmartRoutingAddressParams['actions']` | Destination actions per token type. When omitted, funds are simply transferred to the recipient. | +| `slippage` | `number` | Max slippage in basis points (`50` = 0.5%). | +| `baseUrl` | `string` | Override the smart routing address server root URL; the `projectId` is appended to it. | +| `pollingInterval` | `number` | Deposit status polling interval in ms. Defaults to `5000`. | +| `estimatedFillTimeSeconds` | `number \| Record` | Expected fill time in seconds, either a flat value or per source chain id. | + +## Props + +| Prop | Type | Description | +| --- | --- | --- | +| `recipient` | `Address` | Recipient the routing address is created for. Required. | +| `onClose` | `() => void` | Called when the top-right × button is clicked. Required. | +| `onHelp` | `() => void` | Called when the top-left ? button is clicked on the deposit step. When omitted, no help button is shown. | +| `size` | `'sm' \| 'md' \| 'lg'` | Card size. | +| `className` | `string` | Extra classes for the card. | + +## Hooks + +Use the hooks to drive your own UI around — or instead of — the prebuilt +screen. All of them read from `SmartRoutingAddressProvider`. + +### useSmartRoutingAddress + +Access the address creation state from anywhere inside the provider: + +```tsx +const { addressState, ensureAddress, activeRoute } = useSmartRoutingAddress() +``` + +- `addressState` — `idle`, `loading`, `success` (with the `address` and fee + estimates), or `error`. +- `ensureAddress(recipient)` — create the address if needed. Repeat calls for + the same recipient reuse the same request, so calling it early — before the + deposit UI is opened — starts the creation in the background and the screen + opens with the address already there. +- `activeRoute` — the source token, chain, and estimated fee the deposit UI + currently shows; `null` until a selection exists. Useful for mirroring the + selection elsewhere, such as analytics. + +### useDepositStatus + +Polls the deposit status for an address and returns the current deposits — +the same data the prebuilt screen shows. See +[Fetching Status](/onramp/smart-routing-address/fetching-status) for the +underlying endpoint. + +```tsx +const { deposits, totalCount, hasLoaded, isLoading, error, refetch } = + useDepositStatus({ address }) +``` + +Polling runs while `enabled` (defaults to `true`) and `address` is set, at +`pollingInterval` ms (defaults to `5000`). `refetch` triggers an immediate +poll — for a retry button after an error. + +### useNewDeposits + +Filters a deposit list down to the deposits that arrived after the hook +mounted — for "your deposit just landed" moments, ignoring history: + +```tsx +const newDeposits = useNewDeposits(deposits, hasLoaded) +``` + +The second argument marks when the baseline is taken: pass `hasLoaded` so +pre-existing deposits from the first response don't count as new. diff --git a/vocs.config.tsx b/vocs.config.tsx index ad3cd42..df8136e 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -308,6 +308,10 @@ export default defineConfig({ text: "Quickstart", link: "/onramp/smart-routing-address/quickstart", }, + { + text: "React UI", + link: "/onramp/smart-routing-address/react-ui", + }, { text: "Fetching Status", link: "/onramp/smart-routing-address/fetching-status", From 4f9d68b5276dc396e69aaeb7e9d5e4a0643916e8 Mon Sep 17 00:00:00 2001 From: Bartek Date: Tue, 11 Aug 2026 13:08:34 +0200 Subject: [PATCH 2/2] add sra ui docs --- .../onramp/smart-routing-address/react-ui.mdx | 69 ++++++++----------- 1 file changed, 28 insertions(+), 41 deletions(-) diff --git a/docs/pages/onramp/smart-routing-address/react-ui.mdx b/docs/pages/onramp/smart-routing-address/react-ui.mdx index dd01d2f..d204855 100644 --- a/docs/pages/onramp/smart-routing-address/react-ui.mdx +++ b/docs/pages/onramp/smart-routing-address/react-ui.mdx @@ -2,8 +2,8 @@ `@zerodev/smart-routing-address-react-ui` is a drop-in deposit UI for [Smart Routing Address](/onramp/smart-routing-address): a provider that creates -and caches the routing address, a prebuilt deposit screen, and hooks for -driving your own UI. To work with the address directly instead, use the +and caches the routing address, a prebuilt deposit screen, and hooks that +connect the screen to your app. To build your own deposit UI instead, use the [SDK](/onramp/smart-routing-address/quickstart). ## Installation @@ -13,23 +13,27 @@ Install the package alongside its peer dependencies: :::code-group ```bash [npm] -npm i @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +npm i @zerodev/smart-routing-address-react-ui viem ``` ```bash [yarn] -yarn add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +yarn add @zerodev/smart-routing-address-react-ui viem ``` ```bash [pnpm] -pnpm add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +pnpm add @zerodev/smart-routing-address-react-ui viem ``` ```bash [bun] -bun add @zerodev/smart-routing-address-react-ui @zerodev/smart-routing-address viem +bun add @zerodev/smart-routing-address-react-ui viem ``` ::: +`@zerodev/smart-routing-address` ships with the package — add it as a direct +dependency only if you import from it, such as `createCall` for custom +`actions`. + Import the stylesheet once at your app entry: ```tsx @@ -76,8 +80,6 @@ rendered inline by you, so it fits any surface — a modal, a drawer, or a page. | `actions` | `CreateSmartRoutingAddressParams['actions']` | Destination actions per token type. When omitted, funds are simply transferred to the recipient. | | `slippage` | `number` | Max slippage in basis points (`50` = 0.5%). | | `baseUrl` | `string` | Override the smart routing address server root URL; the `projectId` is appended to it. | -| `pollingInterval` | `number` | Deposit status polling interval in ms. Defaults to `5000`. | -| `estimatedFillTimeSeconds` | `number \| Record` | Expected fill time in seconds, either a flat value or per source chain id. | ## Props @@ -85,57 +87,42 @@ rendered inline by you, so it fits any surface — a modal, a drawer, or a page. | --- | --- | --- | | `recipient` | `Address` | Recipient the routing address is created for. Required. | | `onClose` | `() => void` | Called when the top-right × button is clicked. Required. | -| `onHelp` | `() => void` | Called when the top-left ? button is clicked on the deposit step. When omitted, no help button is shown. | | `size` | `'sm' \| 'md' \| 'lg'` | Card size. | | `className` | `string` | Extra classes for the card. | ## Hooks -Use the hooks to drive your own UI around — or instead of — the prebuilt -screen. All of them read from `SmartRoutingAddressProvider`. +The hooks connect your app to the prebuilt screen: read the state it shows, +or create the address before it opens. Both read from +`SmartRoutingAddressProvider`. For a fully custom deposit UI, use the +[SDK](/onramp/smart-routing-address/quickstart) directly instead. ### useSmartRoutingAddress -Access the address creation state from anywhere inside the provider: +Read the screen's state from anywhere inside the provider: ```tsx -const { addressState, ensureAddress, activeRoute } = useSmartRoutingAddress() +const { addressState, activeRoute } = useSmartRoutingAddress() ``` - `addressState` — `idle`, `loading`, `success` (with the `address` and fee estimates), or `error`. -- `ensureAddress(recipient)` — create the address if needed. Repeat calls for - the same recipient reuse the same request, so calling it early — before the - deposit UI is opened — starts the creation in the background and the screen - opens with the address already there. - `activeRoute` — the source token, chain, and estimated fee the deposit UI - currently shows; `null` until a selection exists. Useful for mirroring the - selection elsewhere, such as analytics. - -### useDepositStatus - -Polls the deposit status for an address and returns the current deposits — -the same data the prebuilt screen shows. See -[Fetching Status](/onramp/smart-routing-address/fetching-status) for the -underlying endpoint. - -```tsx -const { deposits, totalCount, hasLoaded, isLoading, error, refetch } = - useDepositStatus({ address }) -``` - -Polling runs while `enabled` (defaults to `true`) and `address` is set, at -`pollingInterval` ms (defaults to `5000`). `refetch` triggers an immediate -poll — for a retry button after an error. + currently shows; `null` until a selection exists. The screen's token picker + owns the selection — use `activeRoute` to mirror it elsewhere, such as + analytics. -### useNewDeposits +### useCreateSmartRoutingAddress -Filters a deposit list down to the deposits that arrived after the hook -mounted — for "your deposit just landed" moments, ignoring history: +Get the deposit address, creating it when it doesn't exist yet — call it +early, before the deposit UI is opened, and the screen opens with the +address already there: ```tsx -const newDeposits = useNewDeposits(deposits, hasLoaded) +const { getOrCreateAddress } = useCreateSmartRoutingAddress() +const address = await getOrCreateAddress(recipient) ``` -The second argument marks when the baseline is taken: pass `hasLoaded` so -pre-existing deposits from the first response don't count as new. +Repeat and concurrent calls for the same recipient share one request, so +calling it on hover or on page entry is safe. The promise rejects when +creation fails; the same failure also lands in `addressState`.