@xyo-network/xl1-react-client-sdk 4.0.12 → 4.0.14
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 +53 -124
- package/package.json +14 -38
package/README.md
CHANGED
|
@@ -5,32 +5,17 @@
|
|
|
5
5
|
[![npm-badge][]][npm-link]
|
|
6
6
|
[![license-badge][]][license-link]
|
|
7
7
|
|
|
8
|
-
>
|
|
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
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
30
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
+
## Usage
|
|
64
51
|
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
102
|
-
|
|
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
|
-
|
|
67
|
+
export const App = () => (
|
|
68
|
+
<WalletGatewayProvider gatewayName="sequence">
|
|
69
|
+
<ChainHead />
|
|
70
|
+
</WalletGatewayProvider>
|
|
71
|
+
)
|
|
72
|
+
```
|
|
117
73
|
|
|
118
|
-
-
|
|
119
|
-
|
|
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
|
-
|
|
77
|
+
## Documentation
|
|
124
78
|
|
|
125
|
-
|
|
126
|
-
- `DetailsStack`, `LabelValueStack` — shared MUI layout primitives
|
|
127
|
-
- `ActiveMenuItem` — MUI menu item with active-route styling
|
|
79
|
+
Public subpaths:
|
|
128
80
|
|
|
129
|
-
|
|
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
|
-
|
|
86
|
+
For dApp UX rules, wallet connection patterns, in-page datalakes, and browser
|
|
87
|
+
verification, use the `xl1-patterns` skill.
|
|
132
88
|
|
|
133
|
-
|
|
89
|
+
## AI Agent Skills
|
|
134
90
|
|
|
135
|
-
|
|
91
|
+
Install the recommended XL1/XYO skills with [Skills.sh](https://skills.sh):
|
|
136
92
|
|
|
137
|
-
|
|
93
|
+
```sh
|
|
94
|
+
npx skills add XYOracleNetwork/xyo-skills --all
|
|
95
|
+
```
|
|
138
96
|
|
|
139
|
-
|
|
97
|
+
In XY toolchain repos, the equivalent convenience command is:
|
|
140
98
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
- `@xyo-network/xl1-sdk`
|
|
99
|
+
```sh
|
|
100
|
+
pnpm xy skills defaults
|
|
101
|
+
pnpm xy skills lint --fix
|
|
102
|
+
```
|
|
146
103
|
|
|
147
|
-
|
|
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
|
|
155
|
-
xy test
|
|
156
|
-
xy lint
|
|
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
|
|
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.
|
|
4
|
+
"version": "4.0.14",
|
|
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
|
-
"@
|
|
67
|
-
"@
|
|
68
|
-
"@xyo-network/xl1-blockies": "~4.0.
|
|
66
|
+
"@ariestools/eth-address": "~8.0.3",
|
|
67
|
+
"@mui/icons-material": "~9.2.0",
|
|
68
|
+
"@xyo-network/xl1-blockies": "~4.0.14",
|
|
69
|
+
"@xyo-network/xl1-protocol": "~4.0.14",
|
|
70
|
+
"@xyo-network/xl1-sdk": "~4.0.14"
|
|
69
71
|
},
|
|
70
72
|
"devDependencies": {
|
|
71
|
-
"@ariestools/eth-address": "~8.0.3",
|
|
72
|
-
"@ariestools/pixel": "~8.0.3",
|
|
73
73
|
"@ariestools/sdk": "~8.0.3",
|
|
74
|
-
"@ariestools/sdk-react": "~11.0.
|
|
74
|
+
"@ariestools/sdk-react": "~11.0.2",
|
|
75
75
|
"@ariestools/threads": "~8.0.3",
|
|
76
|
+
"@ariestools/toolchain": "~8.6.12",
|
|
77
|
+
"@ariestools/tsconfig": "~8.6.12",
|
|
78
|
+
"@ariestools/tsconfig-dom": "~8.6.12",
|
|
79
|
+
"@ariestools/tsconfig-react": "~8.6.12",
|
|
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
92
|
"@xyo-network/sdk-protocol": "~7.0.15",
|
|
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
105
|
"vite": "~8.1.3",
|
|
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
110
|
"@ariestools/sdk": "^8.0.3",
|
|
124
|
-
"@ariestools/sdk-react": "^11.0.
|
|
111
|
+
"@ariestools/sdk-react": "^11.0.2",
|
|
125
112
|
"@ariestools/threads": "^8.0.3",
|
|
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
123
|
"@xyo-network/sdk-protocol": "^7.0.15",
|
|
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"
|