@xyo-network/xl1-react-client-sdk 1.28.0 → 1.28.2
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 +182 -9
- package/package.json +79 -79
package/README.md
CHANGED
|
@@ -1,30 +1,203 @@
|
|
|
1
|
+
[![logo][]][logo-link]
|
|
2
|
+
|
|
1
3
|
# @xyo-network/xl1-react-client-sdk
|
|
2
4
|
|
|
3
|
-
[![npm
|
|
4
|
-
[![license
|
|
5
|
+
[![npm-badge][]][npm-link]
|
|
6
|
+
[![license-badge][]][license-link]
|
|
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)
|
|
22
|
+
|
|
23
|
+
## Description
|
|
24
|
+
|
|
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:
|
|
28
|
+
|
|
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.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
Using npm:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npm i --save @xyo-network/xl1-react-client-sdk
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Using yarn:
|
|
5
44
|
|
|
6
|
-
|
|
45
|
+
```sh
|
|
46
|
+
yarn add @xyo-network/xl1-react-client-sdk
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Using pnpm:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
pnpm add @xyo-network/xl1-react-client-sdk
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Using bun:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
bun add @xyo-network/xl1-react-client-sdk
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Quick Start
|
|
62
|
+
|
|
63
|
+
Wrap your app in `WalletGatewayProvider`, then read the resolved gateway with `useGatewayFromWallet`.
|
|
64
|
+
|
|
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
|
+
```
|
|
7
75
|
|
|
8
|
-
|
|
76
|
+
```tsx
|
|
77
|
+
// MyDapp.tsx — read the resolved gateway with the tri-state contract
|
|
78
|
+
import { useGatewayFromWallet } from '@xyo-network/xl1-react-client-sdk/client'
|
|
79
|
+
|
|
80
|
+
export const MyDapp = () => {
|
|
81
|
+
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
|
+
|
|
99
|
+
Import only what you need:
|
|
9
100
|
|
|
10
101
|
- `@xyo-network/xl1-react-client-sdk` — flat barrel of everything below
|
|
11
|
-
- `@xyo-network/xl1-react-client-sdk/client` — providers, hooks, components for client/wallet integration
|
|
102
|
+
- `@xyo-network/xl1-react-client-sdk/client` — providers, hooks, and components for client/wallet integration
|
|
12
103
|
- `@xyo-network/xl1-react-client-sdk/model` — `XyoGlobal` type and guards
|
|
13
104
|
- `@xyo-network/xl1-react-client-sdk/shared` — shared MUI components and Storybook decorators
|
|
14
105
|
|
|
15
|
-
##
|
|
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`
|
|
115
|
+
|
|
116
|
+
**Hooks**
|
|
117
|
+
|
|
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
|
|
122
|
+
|
|
123
|
+
**Components**
|
|
124
|
+
|
|
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
|
|
128
|
+
|
|
129
|
+
**Decorators**
|
|
130
|
+
|
|
131
|
+
- `IframeWalletWarningDecorator` — Storybook decorator that surfaces wallet-in-iframe limitations
|
|
132
|
+
|
|
133
|
+
**Model**
|
|
134
|
+
|
|
135
|
+
- `XyoGlobal`, `GatewayFromWallet`, `ContextGatewayType`
|
|
136
|
+
|
|
137
|
+
## Peer Dependencies
|
|
138
|
+
|
|
139
|
+
This package declares its runtime stack via `peerDependencies` so the host app controls the versions. The headline peers you must install:
|
|
140
|
+
|
|
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`
|
|
146
|
+
|
|
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.
|
|
148
|
+
|
|
149
|
+
## Building Locally
|
|
150
|
+
|
|
151
|
+
From the repo root:
|
|
16
152
|
|
|
17
153
|
```sh
|
|
18
|
-
|
|
154
|
+
xy build # tsup + tsc + publint
|
|
155
|
+
xy test # vitest
|
|
156
|
+
xy lint # eslint
|
|
19
157
|
```
|
|
20
158
|
|
|
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
|
+
|
|
21
188
|
## License
|
|
22
189
|
|
|
23
|
-
See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
|
|
190
|
+
See the [LICENSE](./LICENSE) file for license rights and limitations (LGPL-3.0-only).
|
|
191
|
+
|
|
192
|
+
## Credits
|
|
24
193
|
|
|
194
|
+
[Made with 🔥 and ❄️ by XYO](https://xyo.network)
|
|
25
195
|
|
|
196
|
+
[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png
|
|
197
|
+
[logo-link]: https://xyo.network
|
|
26
198
|
|
|
27
199
|
[npm-badge]: https://img.shields.io/npm/v/@xyo-network/xl1-react-client-sdk.svg
|
|
28
200
|
[npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-react-client-sdk
|
|
201
|
+
|
|
29
202
|
[license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-react-client-sdk.svg
|
|
30
|
-
[license-link]:
|
|
203
|
+
[license-link]: ./LICENSE
|
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": "1.28.
|
|
4
|
+
"version": "1.28.2",
|
|
5
5
|
"description": "XL1 React Client/Wallet SDK",
|
|
6
6
|
"homepage": "https://xylabs.com",
|
|
7
7
|
"bugs": {
|
|
@@ -63,8 +63,8 @@
|
|
|
63
63
|
"README.md"
|
|
64
64
|
],
|
|
65
65
|
"dependencies": {
|
|
66
|
-
"@xyo-network/xl1-blockies": "~1.28.
|
|
67
|
-
"@xyo-network/xl1-sdk": "~1.28.
|
|
66
|
+
"@xyo-network/xl1-blockies": "~1.28.2",
|
|
67
|
+
"@xyo-network/xl1-sdk": "~1.28.2"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
70
|
"@bitauth/libauth": "~3.0.0",
|
|
@@ -90,10 +90,10 @@
|
|
|
90
90
|
"@xylabs/react-theme": "~7.2.3",
|
|
91
91
|
"@xylabs/sdk-js": "^5.1.1",
|
|
92
92
|
"@xylabs/threads": "~5.1.1",
|
|
93
|
-
"@xylabs/toolchain": "~7.13.
|
|
94
|
-
"@xylabs/tsconfig": "~7.13.
|
|
95
|
-
"@xylabs/tsconfig-dom": "~7.13.
|
|
96
|
-
"@xylabs/tsconfig-react": "~7.13.
|
|
93
|
+
"@xylabs/toolchain": "~7.13.13",
|
|
94
|
+
"@xylabs/tsconfig": "~7.13.13",
|
|
95
|
+
"@xylabs/tsconfig-dom": "~7.13.13",
|
|
96
|
+
"@xylabs/tsconfig-react": "~7.13.13",
|
|
97
97
|
"@xyo-network/account": "~5.6.1",
|
|
98
98
|
"@xyo-network/account-model": "~5.6.2",
|
|
99
99
|
"@xyo-network/api": "~5.6.1",
|
|
@@ -149,79 +149,79 @@
|
|
|
149
149
|
"zod": "~4.4.3"
|
|
150
150
|
},
|
|
151
151
|
"peerDependencies": {
|
|
152
|
-
"@bitauth/libauth": "
|
|
153
|
-
"@metamask/json-rpc-engine": "
|
|
154
|
-
"@metamask/providers": "
|
|
155
|
-
"@metamask/utils": "
|
|
156
|
-
"@mui/icons-material": "
|
|
157
|
-
"@mui/material": "
|
|
158
|
-
"@opentelemetry/api": "
|
|
159
|
-
"@opentelemetry/sdk-trace-base": "
|
|
160
|
-
"@react-spring/web": "
|
|
161
|
-
"@scure/base": "
|
|
162
|
-
"@scure/bip39": "
|
|
152
|
+
"@bitauth/libauth": "~3.0",
|
|
153
|
+
"@metamask/json-rpc-engine": "^10.3",
|
|
154
|
+
"@metamask/providers": "^22.1",
|
|
155
|
+
"@metamask/utils": "^11.11",
|
|
156
|
+
"@mui/icons-material": "^7.3",
|
|
157
|
+
"@mui/material": "^7.3",
|
|
158
|
+
"@opentelemetry/api": "^1.9",
|
|
159
|
+
"@opentelemetry/sdk-trace-base": "^2.7",
|
|
160
|
+
"@react-spring/web": "~10.0",
|
|
161
|
+
"@scure/base": "~2.2",
|
|
162
|
+
"@scure/bip39": "~2.2",
|
|
163
163
|
"@storybook/react-vite": "^10.3.6",
|
|
164
|
-
"@xylabs/fetch": "
|
|
165
|
-
"@xylabs/geo": "
|
|
166
|
-
"@xylabs/pixel": "
|
|
167
|
-
"@xylabs/react-button": "
|
|
168
|
-
"@xylabs/react-error": "
|
|
169
|
-
"@xylabs/react-promise": "
|
|
170
|
-
"@xylabs/react-shared": "
|
|
171
|
-
"@xylabs/react-theme": "
|
|
172
|
-
"@xylabs/sdk-js": "
|
|
173
|
-
"@xylabs/threads": "
|
|
174
|
-
"@xyo-network/account": "
|
|
175
|
-
"@xyo-network/account-model": "
|
|
176
|
-
"@xyo-network/api": "
|
|
177
|
-
"@xyo-network/api-models": "
|
|
178
|
-
"@xyo-network/boundwitness-builder": "
|
|
179
|
-
"@xyo-network/boundwitness-model": "
|
|
180
|
-
"@xyo-network/boundwitness-wrapper": "
|
|
181
|
-
"@xyo-network/config-payload-plugin": "
|
|
182
|
-
"@xyo-network/huri": "
|
|
183
|
-
"@xyo-network/manifest-model": "
|
|
184
|
-
"@xyo-network/payload-builder": "
|
|
185
|
-
"@xyo-network/payload-model": "
|
|
186
|
-
"@xyo-network/payload-plugin": "
|
|
187
|
-
"@xyo-network/payload-wrapper": "
|
|
188
|
-
"@xyo-network/query-payload-plugin": "
|
|
189
|
-
"@xyo-network/sdk-js": "
|
|
190
|
-
"@xyo-network/sdk-protocol-js": "
|
|
191
|
-
"@xyo-network/wallet": "
|
|
192
|
-
"@xyo-network/wallet-model": "
|
|
193
|
-
"ajv": "
|
|
194
|
-
"async-mutex": "
|
|
195
|
-
"bn.js": "
|
|
196
|
-
"bowser": "
|
|
197
|
-
"buffer": "
|
|
198
|
-
"chalk": "
|
|
199
|
-
"cosmiconfig": "
|
|
200
|
-
"debug": "
|
|
201
|
-
"ethers": "
|
|
202
|
-
"fast-deep-equal": "
|
|
203
|
-
"hash-wasm": "
|
|
204
|
-
"idb": "
|
|
205
|
-
"js-cookie": "
|
|
206
|
-
"lru-cache": "
|
|
207
|
-
"mapbox-gl": "
|
|
208
|
-
"mixpanel-browser": "
|
|
209
|
-
"observable-fns": "
|
|
210
|
-
"pako": "
|
|
211
|
-
"query-string": "
|
|
212
|
-
"react": "
|
|
213
|
-
"react-dom": "
|
|
214
|
-
"react-is": "
|
|
215
|
-
"react-router-dom": "
|
|
216
|
-
"recharts": "
|
|
217
|
-
"spark-md5": "
|
|
218
|
-
"store2": "
|
|
219
|
-
"storybook": "
|
|
220
|
-
"uuid": "
|
|
221
|
-
"vite": "
|
|
222
|
-
"wasm-feature-detect": "
|
|
223
|
-
"webextension-polyfill": "
|
|
224
|
-
"zod": "
|
|
164
|
+
"@xylabs/fetch": "^5.1",
|
|
165
|
+
"@xylabs/geo": "^5.1",
|
|
166
|
+
"@xylabs/pixel": "~5.1",
|
|
167
|
+
"@xylabs/react-button": "~7.2",
|
|
168
|
+
"@xylabs/react-error": "~7.2",
|
|
169
|
+
"@xylabs/react-promise": "^7.2",
|
|
170
|
+
"@xylabs/react-shared": "~7.2",
|
|
171
|
+
"@xylabs/react-theme": "~7.2",
|
|
172
|
+
"@xylabs/sdk-js": "^5.1",
|
|
173
|
+
"@xylabs/threads": "~5.1",
|
|
174
|
+
"@xyo-network/account": "~5.6",
|
|
175
|
+
"@xyo-network/account-model": "~5.6",
|
|
176
|
+
"@xyo-network/api": "~5.6",
|
|
177
|
+
"@xyo-network/api-models": "~5.6",
|
|
178
|
+
"@xyo-network/boundwitness-builder": "~5.6",
|
|
179
|
+
"@xyo-network/boundwitness-model": "~5.6",
|
|
180
|
+
"@xyo-network/boundwitness-wrapper": "~5.6",
|
|
181
|
+
"@xyo-network/config-payload-plugin": "~5.6",
|
|
182
|
+
"@xyo-network/huri": "~5.6",
|
|
183
|
+
"@xyo-network/manifest-model": "~5.6",
|
|
184
|
+
"@xyo-network/payload-builder": "~5.6",
|
|
185
|
+
"@xyo-network/payload-model": "~5.6",
|
|
186
|
+
"@xyo-network/payload-plugin": "~5.6",
|
|
187
|
+
"@xyo-network/payload-wrapper": "~5.6",
|
|
188
|
+
"@xyo-network/query-payload-plugin": "~5.6",
|
|
189
|
+
"@xyo-network/sdk-js": "^5.6",
|
|
190
|
+
"@xyo-network/sdk-protocol-js": "~5.6",
|
|
191
|
+
"@xyo-network/wallet": "~5.6",
|
|
192
|
+
"@xyo-network/wallet-model": "^5.6",
|
|
193
|
+
"ajv": "^8.20",
|
|
194
|
+
"async-mutex": "^0.5",
|
|
195
|
+
"bn.js": "^5.2",
|
|
196
|
+
"bowser": "^2.14",
|
|
197
|
+
"buffer": "^6.0",
|
|
198
|
+
"chalk": "^5.6",
|
|
199
|
+
"cosmiconfig": "^9.0",
|
|
200
|
+
"debug": "~4.4",
|
|
201
|
+
"ethers": "^6.16",
|
|
202
|
+
"fast-deep-equal": "~3.1",
|
|
203
|
+
"hash-wasm": "~4.12",
|
|
204
|
+
"idb": "^8.0",
|
|
205
|
+
"js-cookie": "~3.0",
|
|
206
|
+
"lru-cache": "^11.3",
|
|
207
|
+
"mapbox-gl": "^3.23",
|
|
208
|
+
"mixpanel-browser": "~2.78",
|
|
209
|
+
"observable-fns": "~0.6",
|
|
210
|
+
"pako": "^2.1",
|
|
211
|
+
"query-string": "~9.3",
|
|
212
|
+
"react": "^19.2",
|
|
213
|
+
"react-dom": "^19.2",
|
|
214
|
+
"react-is": "~19.2",
|
|
215
|
+
"react-router-dom": "^7.15",
|
|
216
|
+
"recharts": "~3.8",
|
|
217
|
+
"spark-md5": "~3.0",
|
|
218
|
+
"store2": "~2.14",
|
|
219
|
+
"storybook": "^10.3",
|
|
220
|
+
"uuid": "~14.0",
|
|
221
|
+
"vite": "^8.0",
|
|
222
|
+
"wasm-feature-detect": "~1.8",
|
|
223
|
+
"webextension-polyfill": "^0.12",
|
|
224
|
+
"zod": "~4.4"
|
|
225
225
|
},
|
|
226
226
|
"engines": {
|
|
227
227
|
"node": ">=22.3"
|