@xyo-network/xl1-react-client-sdk 4.0.12 → 4.0.15

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.
Files changed (2) hide show
  1. package/README.md +53 -124
  2. package/package.json +21 -45
package/README.md CHANGED
@@ -5,32 +5,17 @@
5
5
  [![npm-badge][]][npm-link]
6
6
  [![license-badge][]][license-link]
7
7
 
8
- > The official React SDK for building wallet-aware dApps on the XL1 blockchain.
9
-
10
- ## Table of Contents
11
-
12
- - [Description](#description)
13
- - [Install](#install)
14
- - [Quick Start](#quick-start)
15
- - [Subpath Exports](#subpath-exports)
16
- - [API Surface](#api-surface)
17
- - [Peer Dependencies](#peer-dependencies)
18
- - [Building Locally](#building-locally)
19
- - [Maintainers](#maintainers)
20
- - [License](#license)
21
- - [Credits](#credits)
8
+ > React wallet, gateway, and UI primitives for XL1 dApps.
22
9
 
23
10
  ## Description
24
11
 
25
- XL1 is the XYO Layer One blockchain — a proof-of-origin, proof-of-perfect chain built on the XYO Protocol. This package is the primary entry point for React 19 + MUI 7 developers building dApps that talk to XL1.
26
-
27
- It bundles three concerns into one install:
12
+ XL1 is the XYO Layer One blockchain protocol. This package is the React entry
13
+ point for wallet-aware XL1 dApps. It provides gateway context providers, wallet
14
+ resolution hooks, permission components, shared MUI layout components, Storybook
15
+ decorators, and XL1 Blockies integration.
28
16
 
29
- - **Wallet integration** — providers and hooks that resolve a gateway from the user's installed XL1 Wallet browser extension
30
- - **In-page fallback** — gateways built directly inside the page when no wallet is present, so the same dApp works for read-only flows without an extension
31
- - **UI primitives** — pre-built MUI components for connect/account flows, plus Storybook decorators for local development
32
-
33
- The result: a single `pnpm add @xyo-network/xl1-react-client-sdk` away from a dApp that gracefully handles "wallet present", "wallet absent", and "wallet still loading" — without writing the tri-state plumbing yourself.
17
+ Use it when a browser app needs to work with the XL1 Wallet extension and with
18
+ in-page read-only gateways.
34
19
 
35
20
  ## Install
36
21
 
@@ -58,136 +43,80 @@ Using bun:
58
43
  bun add @xyo-network/xl1-react-client-sdk
59
44
  ```
60
45
 
61
- ## Quick Start
46
+ Install peer dependencies from this package's `peerDependencies` in
47
+ `package.json`, especially `react`, `react-dom`, `@mui/material`, and
48
+ `@xyo-network/xl1-sdk`.
62
49
 
63
- Wrap your app in `WalletGatewayProvider`, then read the resolved gateway with `useGatewayFromWallet`.
50
+ ## Usage
64
51
 
65
- ```tsx
66
- // app.tsx — wrap your tree in the wallet gateway provider
67
- import { WalletGatewayProvider } from '@xyo-network/xl1-react-client-sdk/client'
68
-
69
- export const App = () => (
70
- <WalletGatewayProvider gatewayName="sequence">
71
- <MyDapp />
72
- </WalletGatewayProvider>
73
- )
74
- ```
52
+ Wrap your app in `WalletGatewayProvider`, then consume the resolved gateway:
75
53
 
76
54
  ```tsx
77
- // MyDapp.tsx — read the resolved gateway with the tri-state contract
78
- import { useGatewayFromWallet } from '@xyo-network/xl1-react-client-sdk/client'
55
+ import { WalletGatewayProvider, useGatewayFromWallet } from '@xyo-network/xl1-react-client-sdk/client'
79
56
 
80
- export const MyDapp = () => {
57
+ const ChainHead = () => {
81
58
  const { gateway, isLoading, error } = useGatewayFromWallet('sequence')
82
- if (isLoading) return <Loading />
83
- if (gateway === null) return <InstallWalletPrompt />
84
- if (error) return <ErrorBanner error={error} />
85
- return <ConnectedUi gateway={gateway} />
86
- }
87
- ```
88
-
89
- `useGatewayFromWallet` follows a three-state contract:
90
-
91
- - `undefined` — wallet detection is in progress; render a loading state
92
- - `null` — wallet is definitively absent; show a "Get XL1 Wallet" prompt
93
- - `XyoGatewayRunner` — wallet is present and ready for transactions and queries
94
-
95
- For dApps that need to operate without a wallet, mount `InPageGatewaysProvider` above `GatewayProvider` to get an in-page fallback gateway alongside the wallet-backed one.
96
-
97
- ## Subpath Exports
98
59
 
99
- Import only what you need:
60
+ if (isLoading) return <>Loading wallet...</>
61
+ if (error) return <>{error.message}</>
62
+ if (gateway === null) return <>Install or connect the XL1 Wallet.</>
100
63
 
101
- - `@xyo-network/xl1-react-client-sdk` — flat barrel of everything below
102
- - `@xyo-network/xl1-react-client-sdk/client` — providers, hooks, and components for client/wallet integration
103
- - `@xyo-network/xl1-react-client-sdk/model` — `XyoGlobal` type and guards
104
- - `@xyo-network/xl1-react-client-sdk/shared` — shared MUI components and Storybook decorators
105
-
106
- ## API Surface
107
-
108
- A short tour of the main public exports. See the generated `.d.ts` files for the full surface.
109
-
110
- **Providers**
111
-
112
- - `WalletGatewayProvider` — gateway sourced exclusively from the XL1 Wallet extension
113
- - `GatewayProvider` — gateway sourced from wallet first, in-page gateways second
114
- - `InPageGatewaysProvider` — builds gateways from app config; required ancestor of `GatewayProvider`
64
+ return <>Gateway ready: {gateway.name}</>
65
+ }
115
66
 
116
- **Hooks**
67
+ export const App = () => (
68
+ <WalletGatewayProvider gatewayName="sequence">
69
+ <ChainHead />
70
+ </WalletGatewayProvider>
71
+ )
72
+ ```
117
73
 
118
- - `useGatewayFromWallet` — resolves a single gateway from the wallet (tri-state)
119
- - `useClientFromWallet` — lower-level hook returning the full XL1 client
120
- - `useProvidedGateway` — reads the published `GatewayContext`
121
- - `usePermissions`, `usePermissionsAccounts` — wallet permission and account flows
74
+ For read-only dApps that should work before wallet connection, mount
75
+ `InPageGatewaysProvider` and `GatewayProvider` around the app shell.
122
76
 
123
- **Components**
77
+ ## Documentation
124
78
 
125
- - `ConnectAccountsStack`, `Connected` — account-aware UI for connect / connected states
126
- - `DetailsStack`, `LabelValueStack` — shared MUI layout primitives
127
- - `ActiveMenuItem` — MUI menu item with active-route styling
79
+ Public subpaths:
128
80
 
129
- **Decorators**
81
+ - `@xyo-network/xl1-react-client-sdk` - full browser barrel.
82
+ - `@xyo-network/xl1-react-client-sdk/client` - providers, hooks, permission flows, and connected UI.
83
+ - `@xyo-network/xl1-react-client-sdk/model` - browser global and gateway model types.
84
+ - `@xyo-network/xl1-react-client-sdk/shared` - shared MUI components and Storybook decorators.
130
85
 
131
- - `IframeWalletWarningDecorator` — Storybook decorator that surfaces wallet-in-iframe limitations
86
+ For dApp UX rules, wallet connection patterns, in-page datalakes, and browser
87
+ verification, use the `xl1-patterns` skill.
132
88
 
133
- **Model**
89
+ ## AI Agent Skills
134
90
 
135
- - `XyoGlobal`, `GatewayFromWallet`, `ContextGatewayType`
91
+ Install the recommended XL1/XYO skills with [Skills.sh](https://skills.sh):
136
92
 
137
- ## Peer Dependencies
93
+ ```sh
94
+ npx skills add XYOracleNetwork/xyo-skills --all
95
+ ```
138
96
 
139
- This package declares its runtime stack via `peerDependencies` so the host app controls the versions. The headline peers you must install:
97
+ In XY toolchain repos, the equivalent convenience command is:
140
98
 
141
- - `react` `>=19.2.6 <20`, `react-dom`
142
- - `@mui/material` `>=7.3.10 <8`, `@mui/icons-material`
143
- - `ethers` `>=6.16.0 <7`
144
- - `@metamask/json-rpc-engine`, `@metamask/providers`
145
- - `@xyo-network/xl1-sdk`
99
+ ```sh
100
+ pnpm xy skills defaults
101
+ pnpm xy skills lint --fix
102
+ ```
146
103
 
147
- The full list (including supporting `@xylabs/*`, `@xyo-network/*`, and protocol packages) is in [`package.json`](./package.json). If your build complains about an unsatisfied peer, install it with the version range shown there.
104
+ For XL1 work, ask your agent to use `xyo-knowledge`, `xl1-knowledge`, and
105
+ `xl1-patterns`. These skills cover XYO primitives, XL1 chain and gateway APIs,
106
+ and application patterns for XL1 dApps.
148
107
 
149
108
  ## Building Locally
150
109
 
151
- From the repo root:
152
-
153
110
  ```sh
154
- xy build # tsup + tsc + publint
155
- xy test # vitest
156
- xy lint # eslint
111
+ pnpm xy build @xyo-network/xl1-react-client-sdk
112
+ pnpm xy test @xyo-network/xl1-react-client-sdk
113
+ pnpm xy lint @xyo-network/xl1-react-client-sdk
157
114
  ```
158
115
 
159
- Scope to this package by appending its name: `xy build @xyo-network/xl1-react-client-sdk`.
160
-
161
- ## Maintainers
162
-
163
- <table>
164
- <tr>
165
- <td align="center" valign="top" width="120">
166
- <a href="https://github.com/arietrouw">
167
- <img src="https://github.com/arietrouw.png" width="80" height="80" alt="Arie Trouw" /><br />
168
- <sub><b>Arie Trouw</b></sub>
169
- </a>
170
- <br />
171
- <a href="https://arietrouw.com">arietrouw.com</a>
172
- </td>
173
- <td align="center" valign="top" width="120">
174
- <a href="https://github.com/jonesmac">
175
- <img src="https://github.com/jonesmac.png" width="80" height="80" alt="Matt Jones" /><br />
176
- <sub><b>Matt Jones</b></sub>
177
- </a>
178
- </td>
179
- <td align="center" valign="top" width="120">
180
- <a href="https://github.com/JoelBCarter">
181
- <img src="https://github.com/JoelBCarter.png" width="80" height="80" alt="Joel Carter" /><br />
182
- <sub><b>Joel Carter</b></sub>
183
- </a>
184
- </td>
185
- </tr>
186
- </table>
187
-
188
116
  ## License
189
117
 
190
- See the [LICENSE](./LICENSE) file for license rights and limitations (LGPL-3.0-only).
118
+ See the [LICENSE](./LICENSE) file for license rights and limitations
119
+ (LGPL-3.0-only).
191
120
 
192
121
  ## Credits
193
122
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "http://json.schemastore.org/package.json",
3
3
  "name": "@xyo-network/xl1-react-client-sdk",
4
- "version": "4.0.12",
4
+ "version": "4.0.15",
5
5
  "description": "XL1 React Client/Wallet SDK",
6
6
  "homepage": "https://xylabs.com",
7
7
  "bugs": {
@@ -63,99 +63,75 @@
63
63
  "README.md"
64
64
  ],
65
65
  "dependencies": {
66
- "@xyo-network/xl1-protocol": "~4.0.12",
67
- "@xyo-network/xl1-sdk": "~4.0.12",
68
- "@xyo-network/xl1-blockies": "~4.0.12"
66
+ "@ariestools/eth-address": "~8.0.5",
67
+ "@mui/icons-material": "~9.2.0",
68
+ "@xyo-network/xl1-blockies": "~4.0.15",
69
+ "@xyo-network/xl1-sdk": "~4.0.15",
70
+ "@xyo-network/xl1-protocol": "~4.0.15"
69
71
  },
70
72
  "devDependencies": {
71
- "@ariestools/eth-address": "~8.0.3",
72
- "@ariestools/pixel": "~8.0.3",
73
- "@ariestools/sdk": "~8.0.3",
74
- "@ariestools/sdk-react": "~11.0.0",
75
- "@ariestools/threads": "~8.0.3",
73
+ "@ariestools/sdk": "~8.0.5",
74
+ "@ariestools/sdk-react": "~11.1.0",
75
+ "@ariestools/threads": "~8.0.5",
76
+ "@ariestools/toolchain": "~8.7.4",
77
+ "@ariestools/tsconfig": "~8.7.4",
78
+ "@ariestools/tsconfig-dom": "~8.7.4",
79
+ "@ariestools/tsconfig-react": "~8.7.4",
76
80
  "@bitauth/libauth": "~3.0.0",
77
81
  "@metamask/json-rpc-engine": "~10.5.0",
78
82
  "@metamask/providers": "~22.1.1",
79
- "@mui/icons-material": "~9.2.0",
80
83
  "@mui/material": "~9.2.0",
81
84
  "@noble/post-quantum": "~0.6.1",
82
85
  "@opentelemetry/api": "~1.9.1",
83
86
  "@opentelemetry/sdk-trace-base": "~2.9.0",
84
- "@react-spring/web": "~10.1.2",
85
87
  "@scure/base": "~2.2.0",
86
88
  "@scure/bip39": "~2.2.0",
87
89
  "@storybook/react-vite": "~10.4.6",
88
90
  "@types/react": "~19.2.17",
89
- "@xylabs/toolchain": "~8.6.10",
90
- "@xylabs/tsconfig": "~8.6.10",
91
- "@xylabs/tsconfig-dom": "~8.6.10",
92
- "@xylabs/tsconfig-react": "~8.6.10",
93
91
  "@xyo-network/sdk": "~7.0.11",
94
- "@xyo-network/sdk-protocol": "~7.0.15",
92
+ "@xyo-network/sdk-protocol": "~7.0.16",
95
93
  "ajv": "~8.20.0",
96
94
  "async-mutex": "~0.5.0",
97
- "clsx": "~2.1.1",
98
95
  "debug": "~4.4.3",
99
96
  "eslint": "~10.6.0",
100
97
  "ethers": "~6.17.0",
101
98
  "hash-wasm": "~4.12.0",
102
99
  "idb": "~8.0.3",
103
- "lru-cache": "~11.5.1",
104
- "md5": "~2.3.0",
105
- "numeral": "~2.0.6",
106
100
  "observable-fns": "~0.6.1",
107
- "query-string": "~9.4.1",
108
101
  "react": "~19.2.7",
109
102
  "react-dom": "~19.2.7",
110
- "react-router-dom": "~7.18.1",
111
- "rollbar": "~3.1.0",
112
103
  "storybook": "~10.4.6",
113
104
  "typescript": "~6.0.3",
114
- "viem": "~2.54.6",
115
- "vite": "~8.1.3",
105
+ "vite": "~8.1.4",
116
106
  "webextension-polyfill": "~0.12.0",
117
- "zod": "~4.4.3",
118
- "zustand": "~5.0.14"
107
+ "zod": "~4.4.3"
119
108
  },
120
109
  "peerDependencies": {
121
- "@ariestools/eth-address": "^8.0.3",
122
- "@ariestools/pixel": "^8.0.3",
123
- "@ariestools/sdk": "^8.0.3",
124
- "@ariestools/sdk-react": "^11.0.0",
125
- "@ariestools/threads": "^8.0.3",
110
+ "@ariestools/sdk": "^8.0.5",
111
+ "@ariestools/sdk-react": "^11.1.0",
112
+ "@ariestools/threads": "^8.0.5",
126
113
  "@bitauth/libauth": "^3.0.0",
127
114
  "@metamask/json-rpc-engine": "^10.5.0",
128
115
  "@metamask/providers": "^22.1.1",
129
- "@mui/icons-material": "^9.2.0",
130
116
  "@mui/material": "^9.2.0",
131
117
  "@noble/post-quantum": "^0.6.1",
132
118
  "@opentelemetry/api": "^1.9.1",
133
119
  "@opentelemetry/sdk-trace-base": "^2.9.0",
134
- "@react-spring/web": "^10.1.2",
135
120
  "@scure/base": "^2.2.0",
136
121
  "@scure/bip39": "^2.2.0",
137
122
  "@xyo-network/sdk": "^7.0.11",
138
- "@xyo-network/sdk-protocol": "^7.0.15",
123
+ "@xyo-network/sdk-protocol": "^7.0.16",
139
124
  "ajv": "^8.20.0",
140
125
  "async-mutex": "^0.5.0",
141
- "clsx": "^2.1.1",
142
126
  "debug": "^4.4.3",
143
127
  "ethers": "^6.17.0",
144
128
  "hash-wasm": "^4.12.0",
145
129
  "idb": "^8.0.3",
146
- "lru-cache": "^11.5.1",
147
- "md5": "^2.3.0",
148
- "numeral": "^2.0.6",
149
130
  "observable-fns": "^0.6.1",
150
- "query-string": "^9.4.1",
151
131
  "react": "^19.2.7",
152
132
  "react-dom": "^19.2.7",
153
- "react-router-dom": "^7.18.1",
154
- "rollbar": "^3.1.0",
155
- "viem": "^2.54.6",
156
133
  "webextension-polyfill": "^0.12.0",
157
- "zod": "^4.4.3",
158
- "zustand": "^5.0.14"
134
+ "zod": "^4.4.3"
159
135
  },
160
136
  "engines": {
161
137
  "node": ">=22.3"