@rhinestone/deposit-modal 0.1.14 → 0.1.16

package/README.md

@@ -23,16 +23,42 @@ import "@rhinestone/deposit-modal/styles.css";
 <DepositModal
   isOpen={isOpen}
   onClose={() => setIsOpen(false)}
-  walletClient={walletClient}
-  publicClient={publicClient}
-  address={address}
+  dappWalletClient={walletClient}
+  dappPublicClient={publicClient}
+  dappAddress={address}
   targetChain={8453}
   targetToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
-  switchChain={(chainId) => switchChainAsync({ chainId })}
   onDepositComplete={(data) => console.log("Done!", data)}
 />
 ```
 
+### Deposit flow matrix
+
+|  | Flow 1: Dapp signer | Flow 2: External wallet | Flow 3: QR deposit |
+|---|---|---|---|
+| Typical dapp input | `dappWalletClient` + `dappAddress` | `dappAddress` (user selects/connects external wallet in modal) | `dappAddress` only |
+| Connect step options | `Connected Wallet` (+ `External Wallet`/`Transfer Crypto` if available) | Usually `External Wallet` + `Transfer Crypto` | Same options, user picks `Transfer Crypto` |
+| Smart-account owner (`ownerAddress`) | `dappWalletClient.account.address` | Selected external wallet address | `dappAddress` |
+| `createSmartAccount(userSigner, sessionOwner.account)` `userSigner` | `walletClientToAccount(dappWalletClient)` | `walletClientToAccount(externalWalletClient)` | `createViewOnlyAccount(dappAddress)` |
+| `createSmartAccount(..., sessionOwner.account)` co-owner | Local browser session-owner keypair (`sessionOwner.account`) | Local browser session-owner keypair (`sessionOwner.account`) | Local browser session-owner keypair (`sessionOwner.account`) |
+| Smart account `S` owners passed to SDK | `[ownerAddress, sessionOwner.address]` | `[ownerAddress, sessionOwner.address]` | `[ownerAddress, sessionOwner.address]` |
+| Session-owner localStorage key | `rhinestone:session-owner:<ownerAddress.lowercase()>` | `rhinestone:session-owner:<ownerAddress.lowercase()>` | `rhinestone:session-owner:<ownerAddress.lowercase()>` |
+| Session policy signer in `sessionDetails` | `DEFAULT_SIGNER_ADDRESS` (or `signerAddress` prop override) | `DEFAULT_SIGNER_ADDRESS` (or `signerAddress` prop override) | `DEFAULT_SIGNER_ADDRESS` (or `signerAddress` prop override) |
+| Who signs source transfer | `dappWalletClient` | External wallet client | No modal signer (user sends funds manually) |
+| How processing starts | Confirm step submits transfer tx | Confirm step submits transfer tx | User sends to QR address; modal polls status |
+| `POST /register` `address` | Smart account address (`S`) | Smart account address (`S`) | Smart account address (`S`) |
+| `POST /register` `eoaAddress` | `ownerAddress` | `ownerAddress` | `dappAddress` |
+| `POST /register` `sessionOwner` | `sessionOwner.address` (local co-owner key) | `sessionOwner.address` (local co-owner key) | `sessionOwner.address` (local co-owner key) |
+| `POST /register` `accountParams.sessionDetails` | Built from session policy signer + `sessionOwner.account` signature | Built from session policy signer + `sessionOwner.account` signature | Built from session policy signer + `sessionOwner.account` signature |
+| `POST /register` `target` | `{ chain: targetChain, token: targetToken, recipient? }` | `{ chain: targetChain, token: targetToken, recipient? }` | `{ chain: targetChain, token: targetToken, recipient? }` |
+| If `dappAddress` is missing | Unsupported for this flow | External-only flow can still run | Not available (QR hidden) |
+
+Notes:
+- External wallet option is available when Reown is enabled (`reownAppId`) and a wallet can be connected in the modal.
+- `onConnected({ address, smartAccount })` reports the active owner address used for that flow.
+- Smart-account owner config is passed to the SDK as two ECDSA owners (`ownerAddress` + local `sessionOwner`) with threshold `1`.
+- `DEFAULT_SIGNER_ADDRESS` is the session policy signer inside `sessionDetails`; it is not the local co-owner key stored in browser.
+
 ### Props
 
 | Prop | Type | Required | Description |
@@ -41,16 +67,16 @@ import "@rhinestone/deposit-modal/styles.css";
 | `onClose` | `() => void` | Yes | Close handler |
 | `targetChain` | `Chain \| number` | Yes | Destination chain |
 | `targetToken` | `Address` | Yes | Destination token address |
-| `walletClient` | `WalletClient \| null` | No | viem WalletClient |
-| `publicClient` | `PublicClient \| null` | No | viem PublicClient |
-| `address` | `Address \| null` | No | Connected wallet address |
-| `switchChain` | `(chainId: number) => Promise<{id: number} \| void>` | No | Chain switch callback |
+| `dappWalletClient` | `WalletClient \| null` | No | Host-provided signer wallet client |
+| `dappPublicClient` | `PublicClient \| null` | No | Host-provided public client (fallbacks are created internally if missing) |
+| `dappAddress` | `Address \| null` | No | Dapp identity / owner anchor used by setup and QR flow |
 | `inline` | `boolean` | No | Render inline without overlay |
 | `sourceChain` | `Chain \| number` | No | Pre-selected source chain |
 | `sourceToken` | `Address` | No | Pre-selected source token |
 | `defaultAmount` | `string` | No | Pre-filled amount |
 | `recipient` | `Address` | No | Custom recipient address |
 | `backendUrl` | `string` | No | Backend URL |
+| `rhinestoneApiKey` | `string` | No | Optional SDK api key forwarded to `RhinestoneSDK` during smart-account setup |
 | `signerAddress` | `Address` | No | Session signer address |
 | `waitForFinalTx` | `boolean` | No | Wait for destination tx (default: true) |
 | `onRequestConnect` | `() => void` | No | Called when wallet connection needed |
@@ -65,11 +91,11 @@ import "@rhinestone/deposit-modal/styles.css";
 | Callback | Description |
 |----------|-------------|
 | `onReady` | Modal initialized |
-| `onConnected(address, smartAccount)` | Smart account created |
-| `onDepositSubmitted(txHash, sourceChain, amount)` | Transfer signed |
-| `onDepositComplete(txHash, destinationTxHash?)` | Deposit arrived on target chain |
-| `onDepositFailed(txHash, error?)` | Bridge failed |
-| `onError(message, code?)` | Error during flow |
+| `onConnected(data)` | Smart account created (`{ address, smartAccount }`) |
+| `onDepositSubmitted(data)` | Transfer signed (`{ txHash, sourceChain, amount }`) |
+| `onDepositComplete(data)` | Deposit arrived (`{ txHash, destinationTxHash? }`) |
+| `onDepositFailed(data)` | Bridge failed (`{ txHash, error? }`) |
+| `onError(data)` | Error payload (`{ message, code? }`) |
 
 ## WithdrawModal
 
@@ -86,15 +112,14 @@ import "@rhinestone/deposit-modal/styles.css";
 <WithdrawModal
   isOpen={isOpen}
   onClose={() => setIsOpen(false)}
-  walletClient={walletClient}
-  publicClient={publicClient}
-  address={address}
+  dappWalletClient={walletClient}
+  dappPublicClient={publicClient}
+  dappAddress={address}
   safeAddress="0x..."
   sourceChain={8453}
   sourceToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
   targetChain={1}
   targetToken="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
-  switchChain={(chainId) => switchChainAsync({ chainId })}
   onWithdrawComplete={(data) => console.log("Done!", data)}
 />
 ```
@@ -111,9 +136,9 @@ import "@rhinestone/deposit-modal/styles.css";
 
 | Callback | Description |
 |----------|-------------|
-| `onWithdrawSubmitted(txHash, sourceChain, amount, safeAddress)` | Safe transfer signed |
-| `onWithdrawComplete(txHash, destinationTxHash?)` | Withdrawal arrived |
-| `onWithdrawFailed(txHash, error?)` | Bridge failed |
+| `onWithdrawSubmitted(data)` | Safe transfer signed (`{ txHash, sourceChain, amount, safeAddress }`) |
+| `onWithdrawComplete(data)` | Withdrawal arrived (`{ txHash, destinationTxHash? }`) |
+| `onWithdrawFailed(data)` | Bridge failed (`{ txHash, error? }`) |
 
 Also supports `onReady`, `onConnected`, and `onError` (same as DepositModal).
 
@@ -146,7 +171,7 @@ import {
 
 ## Supported Chains
 
-Base (8453), Optimism (10), Arbitrum (42161)
+Mainnet (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), BSC (56)
 
 ## License