@xyo-network/xl1-react-client-sdk

React wallet, gateway, and UI primitives for XL1 dApps.

Description

XL1 is the XYO Layer One blockchain protocol. This package is the React entry point for wallet-aware XL1 dApps. It provides gateway context providers, wallet resolution hooks, permission components, shared MUI layout components, Storybook decorators, and XL1 Blockies integration.

Use it when a browser app needs to work with the XL1 Wallet extension and with in-page read-only gateways.

Install

Using npm:

npm i --save @xyo-network/xl1-react-client-sdk

Using yarn:

yarn add @xyo-network/xl1-react-client-sdk

Using pnpm:

pnpm add @xyo-network/xl1-react-client-sdk

Using bun:

bun add @xyo-network/xl1-react-client-sdk

Install peer dependencies from this package's peerDependencies in package.json, especially react, react-dom, @mui/material, and @xyo-network/xl1-sdk.

Usage

Wrap your app in WalletGatewayProvider, then consume the resolved gateway:

import { WalletGatewayProvider, useGatewayFromWallet } from '@xyo-network/xl1-react-client-sdk/client'

const ChainHead = () => {
  const { gateway, isLoading, error } = useGatewayFromWallet('sequence')

  if (isLoading) return <>Loading wallet...</>
  if (error) return <>{error.message}</>
  if (gateway === null) return <>Install or connect the XL1 Wallet.</>

  return <>Gateway ready: {gateway.name}</>
}

export const App = () => (
  <WalletGatewayProvider gatewayName="sequence">
    <ChainHead />
  </WalletGatewayProvider>
)

For read-only dApps that should work before wallet connection, mount InPageGatewaysProvider and GatewayProvider around the app shell.

Documentation

Public subpaths:

• @xyo-network/xl1-react-client-sdk - full browser barrel.
• @xyo-network/xl1-react-client-sdk/client - providers, hooks, permission flows, and connected UI.
• @xyo-network/xl1-react-client-sdk/model - browser global and gateway model types.
• @xyo-network/xl1-react-client-sdk/shared - shared MUI components and Storybook decorators.

For dApp UX rules, wallet connection patterns, in-page datalakes, and browser verification, use the xl1-patterns skill.

AI Agent Skills

Install the recommended XL1/XYO skills with Skills.sh:

npx skills add XYOracleNetwork/xyo-skills --all

In XY toolchain repos, the equivalent convenience command is:

pnpm xy skills defaults
pnpm xy skills lint --fix

For XL1 work, ask your agent to use xyo-knowledge, xl1-knowledge, and xl1-patterns. These skills cover XYO primitives, XL1 chain and gateway APIs, and application patterns for XL1 dApps.

Building Locally

pnpm xy build @xyo-network/xl1-react-client-sdk
pnpm xy test @xyo-network/xl1-react-client-sdk
pnpm xy lint @xyo-network/xl1-react-client-sdk

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Credits

Made with 🔥 and ❄️ by XYO Foundation