@xyo-network/xl1-sdk 1.28.0 → 1.28.2

package/README.md

@@ -1,24 +1,188 @@
+[![logo][]][logo-link]
+
 # @xyo-network/xl1-sdk
 
-[![npm][npm-badge]][npm-link]
-[![license][license-badge]][license-link]
+[![npm-badge][]][npm-link]
+[![license-badge][]][license-link]
+
+> The official TypeScript SDK for the XL1 blockchain — gateways, providers, RPC, and protocol primitives in one install.
+
+## Table of Contents
+
+- [Description](#description)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Subpath Exports](#subpath-exports)
+- [API Surface](#api-surface)
+- [Peer Dependencies](#peer-dependencies)
+- [Building Locally](#building-locally)
+- [Maintainers](#maintainers)
+- [License](#license)
+- [Credits](#credits)
+
+## Description
+
+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 **non-React** TypeScript and JavaScript developers — Node.js services, CLIs, indexers, scripts, and any code that needs to read from or write to XL1.
+
+It's a single barrel re-exporting six focused sub-packages:
+
+- `@xyo-network/xl1-protocol` — type definitions, schemas, and validation
+- `@xyo-network/xl1-protocol-sdk` — config (cosmiconfig), caching (LRU), helpers
+- `@xyo-network/xl1-rpc` — JSON-RPC method handlers and schemas
+- `@xyo-network/xl1-providers` — neutral / Node / browser providers
+- `@xyo-network/xl1-gateway` — `GatewayBuilder` and the read/write gateway runtime
+- `@xyo-network/xl1-wrappers` — payload and bound-witness wrappers
 
-> XYO Layer One Protocol
+Install it once and you have everything you need to construct a gateway, read chain state, and submit transactions. For React-specific bindings (providers, hooks, MUI components), use [`@xyo-network/xl1-react-client-sdk`](https://www.npmjs.com/package/@xyo-network/xl1-react-client-sdk) instead.
 
 ## Install
 
+Using npm:
+
+```sh
+npm i --save @xyo-network/xl1-sdk
+```
+
+Using yarn:
+
+```sh
+yarn add @xyo-network/xl1-sdk
+```
+
+Using pnpm:
+
+```sh
+pnpm add @xyo-network/xl1-sdk
+```
+
+Using bun:
+
+```sh
+bun add @xyo-network/xl1-sdk
+```
+
+## Quick Start
+
+Construct a read-only gateway and query the current block:
+
+```ts
+import { GatewayBuilder } from '@xyo-network/xl1-sdk'
+
+const gateway = await new GatewayBuilder()
+  .rpcUrl('https://beta.api.chain.xyo.network/rpc')
+  .build()
+
+const viewer = gateway.connection.viewer
+const blockNumber = await viewer.block.currentBlockNumber()
+
+console.log(`Current block on sequence: ${blockNumber}`)
+```
+
+The `viewer` exposes typed query interfaces for blocks, accounts, transactions, and time. To submit transactions, attach a signer with `.signer(account)` on the builder — that promotes the result to an `XyoGatewayRunner`, which extends the read-only `XyoGateway` with write methods.
+
+Common public endpoints:
+
+- Mainnet — `https://api.chain.xyo.network/rpc`
+- Sequence (testnet) — `https://beta.api.chain.xyo.network/rpc`
+- Local rpc-server — `http://localhost:8080/rpc`
+
+For programmatic network selection use `DefaultNetworks` from the barrel rather than hard-coding URLs.
+
+## Subpath Exports
+
+- `@xyo-network/xl1-sdk` — flat barrel of all six sub-packages
+- `@xyo-network/xl1-sdk/test` — shared test utilities (stub block viewers, fixtures) for use in your own integration tests
+
+## API Surface
+
+The barrel re-exports the full surface of each sub-package. The handful of symbols most consumers reach for first:
+
+**Gateway construction**
+
+- `GatewayBuilder` — fluent factory; produces an `XyoGateway` (read-only) or `XyoGatewayRunner` (read + write, when a signer is attached)
+- `XyoGateway`, `XyoGatewayRunner` — runtime interfaces with `.connection.viewer` for queries
+
+**Viewers (under `gateway.connection.viewer`)**
+
+- `viewer.block` — `currentBlockNumber()`, `block(id)`, etc.
+- `viewer.account` — balances, nonces, account state
+- `viewer.transaction` — transaction lookup
+- `viewer.time` — chain time queries
+
+**Providers**
+
+- Neutral/Node/Browser provider variants for transports, with OpenTelemetry hooks built in
+
+**Wrappers**
+
+- Payload and bound-witness wrappers from `xl1-wrappers` for working with raw protocol messages
+
+See the generated `.d.ts` files for the full surface, or the per-package `CLAUDE.md` files in the monorepo for deeper patterns.
+
+## Peer Dependencies
+
+This package declares its runtime stack via `peerDependencies` so the host app controls the versions. Headline peers:
+
+- `ethers` `>=6.16.0 <7`
+- `@metamask/json-rpc-engine`, `@metamask/providers`, `@metamask/utils`
+- `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`
+- `@xyo-network/sdk-js`, `@xyo-network/sdk-protocol-js`, `@xyo-network/account`, `@xyo-network/payload-*`, `@xyo-network/boundwitness-*`
+- `zod`, `ajv`, `cosmiconfig`, `lru-cache`
+
+The full list — including the supporting `@xylabs/*` and `@xyo-network/*` packages — is in [`package.json`](./package.json). If your build complains about an unsatisfied peer, install it with the version range shown there.
+
+## Building Locally
+
+From the repo root:
+
 ```sh
-{{pm}} add {{name}}
+xy build      # tsup + tsc + publint
+xy test       # vitest
+xy lint       # eslint
 ```
 
+Scope to this package by appending its name: `xy build @xyo-network/xl1-sdk`.
+
+## Maintainers
+
+<table>
+  <tr>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/arietrouw">
+        <img src="https://github.com/arietrouw.png" width="80" height="80" alt="Arie Trouw" /><br />
+        <sub><b>Arie Trouw</b></sub>
+      </a>
+      <br />
+      <a href="https://arietrouw.com">arietrouw.com</a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/jonesmac">
+        <img src="https://github.com/jonesmac.png" width="80" height="80" alt="Matt Jones" /><br />
+        <sub><b>Matt Jones</b></sub>
+      </a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/JoelBCarter">
+        <img src="https://github.com/JoelBCarter.png" width="80" height="80" alt="Joel Carter" /><br />
+        <sub><b>Joel Carter</b></sub>
+      </a>
+    </td>
+  </tr>
+</table>
 
 ## License
 
-See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
+See the [LICENSE](./LICENSE) file for license rights and limitations (LGPL-3.0-only).
+
+## Credits
 
+[Made with 🔥 and ❄️ by XYO](https://xyo.network)
 
+[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png
+[logo-link]: https://xyo.network
 
 [npm-badge]: https://img.shields.io/npm/v/@xyo-network/xl1-sdk.svg
 [npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-sdk
+
 [license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-sdk.svg
-[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
+[license-link]: ./LICENSE

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package.json",
   "name": "@xyo-network/xl1-sdk",
-  "version": "1.28.0",
+  "version": "1.28.2",
   "description": "XYO Layer One Protocol",
   "homepage": "https://xylabs.com",
   "bugs": {
@@ -39,12 +39,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@xyo-network/xl1-gateway": "~1.28.0",
-    "@xyo-network/xl1-protocol": "~1.28.0",
-    "@xyo-network/xl1-protocol-sdk": "~1.28.0",
-    "@xyo-network/xl1-providers": "~1.28.0",
-    "@xyo-network/xl1-rpc": "~1.28.0",
-    "@xyo-network/xl1-wrappers": "~1.28.0"
+    "@xyo-network/xl1-gateway": "~1.28.2",
+    "@xyo-network/xl1-protocol": "~1.28.2",
+    "@xyo-network/xl1-protocol-sdk": "~1.28.2",
+    "@xyo-network/xl1-wrappers": "~1.28.2",
+    "@xyo-network/xl1-providers": "~1.28.2",
+    "@xyo-network/xl1-rpc": "~1.28.2"
   },
   "devDependencies": {
     "@bitauth/libauth": "~3.0.0",
@@ -59,8 +59,8 @@
     "@xylabs/geo": "^5.1.1",
     "@xylabs/sdk-js": "^5.1.1",
     "@xylabs/threads": "~5.1.1",
-    "@xylabs/toolchain": "~7.13.8",
-    "@xylabs/tsconfig": "~7.13.8",
+    "@xylabs/toolchain": "~7.13.13",
+    "@xylabs/tsconfig": "~7.13.13",
     "@xylabs/vitest-extended": "^5.1.1",
     "@xyo-network/account": "~5.6.1",
     "@xyo-network/account-model": "~5.6.2",
@@ -106,64 +106,64 @@
     "wasm-feature-detect": "~1.8.0",
     "webextension-polyfill": "^0.12.0",
     "zod": "~4.4.3",
-    "@xyo-network/xl1-protocol-model": "~1.28.0",
-    "@xyo-network/xl1-schema": "~1.28.0",
-    "@xyo-network/xl1-validation": "~1.28.0",
-    "@xyo-network/xl1-network-model": "~1.28.0",
-    "@xyo-network/xl1-test": "~1.28.0",
-    "@xyo-network/xl1-protocol-lib": "~1.28.0"
+    "@xyo-network/xl1-protocol-lib": "~1.28.2",
+    "@xyo-network/xl1-network-model": "~1.28.2",
+    "@xyo-network/xl1-protocol-model": "~1.28.2",
+    "@xyo-network/xl1-schema": "~1.28.2",
+    "@xyo-network/xl1-test": "~1.28.2",
+    "@xyo-network/xl1-validation": "~1.28.2"
   },
   "peerDependencies": {
-    "@bitauth/libauth": ">=3.0.0 <3.1",
-    "@metamask/json-rpc-engine": ">=10.3.0 <11",
-    "@metamask/providers": ">=22.1.1 <23",
-    "@metamask/utils": ">=11.11.0 <12",
-    "@opentelemetry/api": ">=1.9.1 <2",
-    "@opentelemetry/sdk-trace-base": ">=2.7.1 <3",
-    "@scure/base": ">=2.2.0 <2.3",
-    "@scure/bip39": ">=2.2.0 <2.3",
-    "@xylabs/fetch": ">=5.1.1 <6",
-    "@xylabs/geo": ">=5.1.1 <6",
-    "@xylabs/sdk-js": ">=5.1.1 <6",
-    "@xylabs/threads": ">=5.1.1 <5.2",
-    "@xyo-network/account": ">=5.6.1 <5.7",
-    "@xyo-network/account-model": ">=5.6.2 <5.7",
-    "@xyo-network/api": ">=5.6.1 <5.7",
-    "@xyo-network/api-models": ">=5.6.2 <5.7",
-    "@xyo-network/boundwitness-builder": ">=5.6.1 <5.7",
-    "@xyo-network/boundwitness-model": ">=5.6.2 <5.7",
-    "@xyo-network/boundwitness-wrapper": ">=5.6.1 <5.7",
-    "@xyo-network/config-payload-plugin": ">=5.6.2 <5.7",
-    "@xyo-network/huri": ">=5.6.1 <5.7",
-    "@xyo-network/manifest-model": ">=5.6.2 <5.7",
-    "@xyo-network/payload-builder": ">=5.6.1 <5.7",
-    "@xyo-network/payload-model": ">=5.6.2 <5.7",
-    "@xyo-network/payload-plugin": ">=5.6.2 <5.7",
-    "@xyo-network/payload-wrapper": ">=5.6.1 <5.7",
-    "@xyo-network/query-payload-plugin": ">=5.6.2 <5.7",
-    "@xyo-network/sdk-js": ">=5.6.3 <6",
-    "@xyo-network/sdk-protocol-js": ">=5.6.2 <5.7",
-    "@xyo-network/wallet": ">=5.6.1 <5.7",
-    "@xyo-network/wallet-model": ">=5.6.2 <6",
-    "ajv": ">=8.20.0 <9",
-    "async-mutex": ">=0.5.0 <1",
-    "bn.js": ">=5.2.3 <6",
-    "buffer": ">=6.0.3 <7",
-    "chalk": ">=5.6.2 <6",
-    "cosmiconfig": ">=9.0.1 <10",
-    "debug": ">=4.4.3 <4.5",
-    "ethers": ">=6.16.0 <7",
-    "hash-wasm": ">=4.12.0 <4.13",
-    "idb": ">=8.0.3 <9",
-    "lru-cache": ">=11.3.6 <12",
-    "mapbox-gl": ">=3.23.1 <4",
-    "observable-fns": ">=0.6.1 <0.7",
-    "pako": ">=2.1.0 <3",
-    "store2": ">=2.14.4 <2.15",
-    "uuid": ">=14.0.0 <14.1",
-    "wasm-feature-detect": ">=1.8.0 <1.9",
-    "webextension-polyfill": ">=0.12.0 <1",
-    "zod": ">=4.4.3 <4.5"
+    "@bitauth/libauth": "~3.0",
+    "@metamask/json-rpc-engine": "^10.3",
+    "@metamask/providers": "^22.1",
+    "@metamask/utils": "^11.11",
+    "@opentelemetry/api": "^1.9",
+    "@opentelemetry/sdk-trace-base": "^2.7",
+    "@scure/base": "~2.2",
+    "@scure/bip39": "~2.2",
+    "@xylabs/fetch": "^5.1",
+    "@xylabs/geo": "^5.1",
+    "@xylabs/sdk-js": "^5.1",
+    "@xylabs/threads": "~5.1",
+    "@xyo-network/account": "~5.6",
+    "@xyo-network/account-model": "~5.6",
+    "@xyo-network/api": "~5.6",
+    "@xyo-network/api-models": "~5.6",
+    "@xyo-network/boundwitness-builder": "~5.6",
+    "@xyo-network/boundwitness-model": "~5.6",
+    "@xyo-network/boundwitness-wrapper": "~5.6",
+    "@xyo-network/config-payload-plugin": "~5.6",
+    "@xyo-network/huri": "~5.6",
+    "@xyo-network/manifest-model": "~5.6",
+    "@xyo-network/payload-builder": "~5.6",
+    "@xyo-network/payload-model": "~5.6",
+    "@xyo-network/payload-plugin": "~5.6",
+    "@xyo-network/payload-wrapper": "~5.6",
+    "@xyo-network/query-payload-plugin": "~5.6",
+    "@xyo-network/sdk-js": "^5.6",
+    "@xyo-network/sdk-protocol-js": "~5.6",
+    "@xyo-network/wallet": "~5.6",
+    "@xyo-network/wallet-model": "^5.6",
+    "ajv": "^8.20",
+    "async-mutex": "^0.5",
+    "bn.js": "^5.2",
+    "buffer": "^6.0",
+    "chalk": "^5.6",
+    "cosmiconfig": "^9.0",
+    "debug": "~4.4",
+    "ethers": "^6.16",
+    "hash-wasm": "~4.12",
+    "idb": "^8.0",
+    "lru-cache": "^11.3",
+    "mapbox-gl": "^3.23",
+    "observable-fns": "~0.6",
+    "pako": "^2.1",
+    "store2": "~2.14",
+    "uuid": "~14.0",
+    "wasm-feature-detect": "~1.8",
+    "webextension-polyfill": "^0.12",
+    "zod": "~4.4"
   },
   "engines": {
     "node": ">=22.3"