@rhinestone/deposit-modal 0.13.0 → 0.14.0

package/README.md

@@ -50,6 +50,17 @@ console error pointing at the CSP. Hosts without an explicit `img-src` (or with
 > sufficient. They now come from the CDN, which drops ~20 kB (brotli) from the
 > bundle and gives every Rhinestone surface one source of truth.
 
+All three modals also post session analytics to Rhinestone (see
+[Analytics](#analytics)), so a host with an explicit `connect-src` must allow the
+orchestrator alongside its own proxy:
+
+```
+connect-src 'self' https://v1.orchestrator.rhinestone.dev;
+```
+
+A blocked origin is reported on `onEvent` as an `analytics_ingest_failure`, not
+surfaced to the user.
+
 ## Example
 
 ```tsx
@@ -296,10 +307,40 @@ Flow: user picks Fund from Exchange → backend returns supported exchanges + lo
 | ----------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `enableExchangeConnect` | `boolean` | `false` | Show the "Fund from Exchange" row. Requires backend Swapped keys. Needs no wallet. Can be combined with `enableFiatOnramp`. |
 
+## Analytics
+
+`onEvent` receives the deposit, withdraw and claim funnels as a session-scoped
+stream:
+every event carries the session id, the modal, the widget version and a snapshot
+of the session's configuration.
+
+The same events are also sent to Rhinestone, batched, in the background, and
+flushed when the modal closes or the page goes away. Delivery never affects the
+flow and never changes what `onEvent` receives. Sessions are attributed to your
+project through a short-lived token minted at `POST /analytics/ingest-token` on
+your proxy; a proxy that does not forward that route still collects, just
+unattributed.
+
+| Prop                     | Type      | Default | Description                                                     |
+| ------------------------ | --------- | ------- | --------------------------------------------------------------- |
+| `enableAnalyticsIngest`  | `boolean` | `true`  | Set `false` to stop sending analytics to Rhinestone. `onEvent` is unaffected. |
+
+When a batch cannot be delivered, `onEvent` receives one
+`analytics_ingest_failure` per distinct reason per session, naming the reason
+(`network` — which includes a CSP block — `rejected`, `conflict`,
+`unauthorized`, `throttled`, `unavailable`, `token_unavailable`, `unsupported`),
+the HTTP status when there was one, and how many events the session has lost so
+far.
+
 ## Upgrading
 
-Upgrading from 0.8.x is a breaking change on both modals. See
-[`MIGRATION.md`](./MIGRATION.md), or the same guide
+Upgrading from 0.13.x changes what `onEvent` delivers: the deposit events are
+replaced by a method-aware taxonomy, the five flat claim events are replaced by
+a claim funnel, and every event gains a session envelope. A claim-only
+integration now posts analytics too, so it needs the `connect-src` above.
+Upgrading from 0.8.x is a breaking change on both modals.
+
+See [`MIGRATION.md`](./MIGRATION.md), or the same guide
 [in the docs](https://docs.rhinestone.dev/deposits/widget/migration).
 
 ## Contributing

package/bridge-transcript.json

@@ -0,0 +1,653 @@
+{
+  "transcriptFormat": 1,
+  "vocabulary": {
+    "protocol": 2,
+    "channels": {
+      "pageToHost": "rhinestoneBridge",
+      "hostToPage": "__rhinestone_bridge"
+    },
+    "maxFrameLength": 262144,
+    "pageMethods": [
+      "bridge.probeFrameScope",
+      "hello",
+      "host.openUrl",
+      "host.sendTransaction",
+      "host.signRecovery",
+      "wallet.request"
+    ],
+    "hostMethods": [
+      "ui.back"
+    ],
+    "pageEvents": [
+      "analytics",
+      "dismissRequested",
+      "error",
+      "lifecycle",
+      "ready",
+      "ui.state",
+      "wallet.connectRequested",
+      "wallet.disconnectRequested"
+    ],
+    "passthroughEvents": [
+      "analytics",
+      "error",
+      "lifecycle"
+    ],
+    "hostEvents": [
+      "session.configure",
+      "wallet.state"
+    ],
+    "capabilities": [
+      "bridge.probeFrameScope",
+      "host.openUrl",
+      "host.sendTransaction",
+      "host.signRecovery"
+    ],
+    "walletMethods": [
+      "eth_accounts",
+      "eth_chainId",
+      "eth_sendTransaction",
+      "eth_signTypedData_v4",
+      "wallet_sendTransaction",
+      "wallet_switchEthereumChain"
+    ],
+    "dismissalReasons": [
+      "settlement-in-progress",
+      "submission-in-flight",
+      "wallet-request-pending"
+    ],
+    "dismissSources": [
+      "back-past-first-screen",
+      "close-button",
+      "flow-complete"
+    ],
+    "errorDomain": "bridge",
+    "errorCodes": {
+      "CHANNEL_CLOSED": 4,
+      "MALFORMED_RESULT": 5,
+      "REQUEST_TIMEOUT": 3,
+      "SUBMISSION_UNCERTAIN": 2,
+      "WALLET_UNAVAILABLE": 1
+    },
+    "signRecovery": {
+      "domain": {
+        "name": "Rhinestone Deposit Recovery",
+        "version": "1"
+      },
+      "types": {
+        "RecoverDeposit": [
+          {
+            "name": "depositId",
+            "type": "uint256"
+          },
+          {
+            "name": "destination",
+            "type": "address"
+          }
+        ]
+      },
+      "primaryType": "RecoverDeposit",
+      "encodeType": "RecoverDeposit(uint256 depositId,address destination)",
+      "domainEncodeType": "EIP712Domain(string name,string version)"
+    }
+  },
+  "frames": [
+    {
+      "dir": "host->page",
+      "kind": "event",
+      "type": "session.configure",
+      "shape": {
+        "backendUrl": "string",
+        "mode": "deposit",
+        "recipient": "string",
+        "targetChain": "number",
+        "targetToken": "string",
+        "theme": {
+          "mode": "dark"
+        }
+      }
+    },
+    {
+      "dir": "host->page",
+      "kind": "event",
+      "type": "wallet.state",
+      "shape": {
+        "accounts": [
+          {
+            "caip10": "string"
+          }
+        ],
+        "chainId": "string",
+        "isConnected": "boolean",
+        "isReady": "boolean",
+        "name": "string"
+      }
+    },
+    {
+      "dir": "host->page",
+      "kind": "request",
+      "method": "ui.back"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "bridge.probeFrameScope",
+      "ok": false,
+      "errorCode": 4200
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "hello",
+      "ok": true,
+      "shape": {
+        "capabilities": [
+          "bridge.probeFrameScope",
+          "host.openUrl",
+          "host.sendTransaction",
+          "host.signRecovery"
+        ],
+        "config": {
+          "accountAddress": [
+            "string",
+            "undefined"
+          ],
+          "backendUrl": "string",
+          "mode": [
+            "deposit",
+            "withdraw"
+          ],
+          "recipient": "string",
+          "targetChain": "number",
+          "targetToken": "string"
+        },
+        "host": {
+          "app": "string",
+          "platform": "ios"
+        },
+        "protocol": "number",
+        "wallet": {
+          "accounts": [
+            {
+              "caip10": "string"
+            }
+          ],
+          "chainId": "string",
+          "isConnected": "boolean",
+          "isReady": "boolean",
+          "name": "string"
+        }
+      }
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.openUrl",
+      "ok": false,
+      "errorCode": 4200
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.openUrl",
+      "ok": true,
+      "shape": {}
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.sendTransaction",
+      "ok": false,
+      "errorCode": 1,
+      "errorDomain": "bridge"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.sendTransaction",
+      "ok": false,
+      "errorCode": 2,
+      "errorDomain": "bridge"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.sendTransaction",
+      "ok": false,
+      "errorCode": 4200
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.sendTransaction",
+      "ok": false,
+      "errorCode": 5,
+      "errorDomain": "bridge"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.sendTransaction",
+      "ok": true,
+      "shape": {
+        "txHash": "string"
+      }
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.signRecovery",
+      "ok": false,
+      "errorCode": 4200
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "host.signRecovery",
+      "ok": true,
+      "shape": {
+        "signature": "string"
+      }
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "eth_accounts",
+      "ok": true,
+      "shape": [
+        "string"
+      ]
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "eth_chainId",
+      "ok": true,
+      "shape": "string"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "eth_sendTransaction",
+      "ok": true,
+      "shape": "string"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "eth_signTypedData_v4",
+      "ok": true,
+      "shape": "string"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "wallet_sendTransaction",
+      "ok": true,
+      "shape": "string"
+    },
+    {
+      "dir": "host->page",
+      "kind": "response",
+      "answers": "wallet.request",
+      "walletMethod": "wallet_switchEthereumChain",
+      "ok": true,
+      "shape": "null"
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "analytics",
+      "passthrough": true,
+      "shape": {
+        "after_handoff": [
+          "boolean",
+          "undefined"
+        ],
+        "correlator": [
+          "undefined",
+          {
+            "type": "transaction_hash",
+            "value": "string"
+          }
+        ],
+        "entry_source": [
+          "string",
+          "undefined"
+        ],
+        "funding_method": [
+          "null",
+          "string"
+        ],
+        "identifiers": [
+          "undefined",
+          {
+            "integration": "string",
+            "network": "string"
+          }
+        ],
+        "modal": "string",
+        "reason": [
+          "string",
+          "undefined"
+        ],
+        "session_id": "string",
+        "session_properties": {
+          "asset_migration_providers": "[]",
+          "enabled_funding_methods": [
+            "string"
+          ],
+          "fiat_methods": {
+            "source": "backend_resolved"
+          },
+          "gasless_wallet_flow_enabled": "boolean",
+          "initial_asset_migration": "null",
+          "overlay_close_enabled": "boolean",
+          "prefills": {
+            "amount": "boolean",
+            "initial_asset_migration": "boolean",
+            "source_chain": "boolean",
+            "source_token": "boolean"
+          },
+          "presentation": "string",
+          "target_chain": "string",
+          "target_token": "string",
+          "wallet_integration": "string"
+        },
+        "source": [
+          "header_button",
+          "undefined"
+        ],
+        "step": [
+          "string",
+          "undefined"
+        ],
+        "timestamp": "string",
+        "type": [
+          "deposit_modal_close",
+          "deposit_modal_friction",
+          "deposit_modal_handoff",
+          "deposit_modal_method_selected",
+          "deposit_modal_open",
+          "deposit_modal_step_complete",
+          "deposit_modal_step_open"
+        ],
+        "widget_version": "string"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "dismissRequested",
+      "shape": {
+        "source": "close-button"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "error",
+      "passthrough": true,
+      "shape": {
+        "code": "string",
+        "message": "string"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "lifecycle",
+      "passthrough": true,
+      "shape": {
+        "address": [
+          "string",
+          "undefined"
+        ],
+        "amount": [
+          "string",
+          "undefined"
+        ],
+        "amountUsd": [
+          "string",
+          "undefined"
+        ],
+        "evm": [
+          "string",
+          "undefined"
+        ],
+        "smartAccount": [
+          "string",
+          "undefined"
+        ],
+        "solana": [
+          "string",
+          "undefined"
+        ],
+        "sourceChain": [
+          "number",
+          "undefined"
+        ],
+        "sourceDecimals": [
+          "number",
+          "undefined"
+        ],
+        "totalUsd": [
+          "number",
+          "undefined"
+        ],
+        "txHash": [
+          "string",
+          "undefined"
+        ],
+        "type": [
+          "balance-changed",
+          "connected",
+          "smart-account-changed",
+          "submitted"
+        ]
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "ready"
+    },
+    {
+      "dir": "page->host",
+      "kind": "event",
+      "type": "ui.state",
+      "shape": {
+        "dismissal": {
+          "message": [
+            "string",
+            "undefined"
+          ],
+          "reason": [
+            "settlement-in-progress",
+            "submission-in-flight",
+            "undefined"
+          ],
+          "state": [
+            "allowed",
+            "blocked"
+          ]
+        },
+        "screen": [
+          "amount",
+          "confirm",
+          "connect",
+          "processing",
+          "select-asset",
+          "unknown"
+        ]
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "bridge.probeFrameScope",
+      "shape": {}
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "hello",
+      "shape": {
+        "modalVersion": "string",
+        "protocol": "number"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "host.openUrl",
+      "shape": {
+        "url": "string"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "host.sendTransaction",
+      "shape": {
+        "amount": "string",
+        "chainId": "number",
+        "from": "string",
+        "to": "string",
+        "token": "string"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "host.signRecovery",
+      "shape": {
+        "chainId": "number",
+        "depositId": "string",
+        "destination": "string",
+        "signer": "string"
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "eth_accounts",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "eth_accounts",
+          "params": "[]"
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "eth_chainId",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "eth_chainId",
+          "params": [
+            "[]",
+            "undefined"
+          ]
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "eth_sendTransaction",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "eth_sendTransaction",
+          "params": {
+            "0": {
+              "data": [
+                "string",
+                "undefined"
+              ],
+              "from": "string",
+              "to": "string",
+              "value": [
+                "string",
+                "undefined"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "eth_signTypedData_v4",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "eth_signTypedData_v4",
+          "params": {
+            "0": "string",
+            "1": "string"
+          }
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "wallet_sendTransaction",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "wallet_sendTransaction",
+          "params": {
+            "0": {
+              "from": "string",
+              "to": "string",
+              "value": "string"
+            }
+          }
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "request",
+      "method": "wallet.request",
+      "walletMethod": "wallet_switchEthereumChain",
+      "shape": {
+        "chainId": "string",
+        "request": {
+          "method": "wallet_switchEthereumChain",
+          "params": {
+            "0": {
+              "chainId": "string"
+            }
+          }
+        }
+      }
+    },
+    {
+      "dir": "page->host",
+      "kind": "response",
+      "answers": "ui.back",
+      "ok": true,
+      "shape": {
+        "handled": "boolean"
+      }
+    }
+  ]
+}