[![logo][]](https://xyo.network)

# @xyo-network/xl1-rpc

[![npm-badge][]][npm-link]
[![license-badge][]][license-link]

> JSON-RPC layer for XL1 — maps protocol viewers and runners to network-callable methods over HTTP, postMessage, or in-memory transports.

## About

This package bridges XL1 protocol interfaces (from [`@xyo-network/xl1-protocol-lib`](https://www.npmjs.com/package/@xyo-network/xl1-protocol-lib)) to JSON-RPC. It builds on `@metamask/json-rpc-engine` and provides Zod-based serialization for both request params and responses, a registry of all RPC schemas, engine handler factories, and four transport implementations.

Most consumers reach this package via the [`@xyo-network/xl1-sdk`](https://www.npmjs.com/package/@xyo-network/xl1-sdk) aggregate. Install directly when you're building an RPC client/server or implementing a custom transport.

## Install

Using npm:

```sh
npm i --save @xyo-network/xl1-rpc
```

Using yarn:

```sh
yarn add @xyo-network/xl1-rpc
```

Using pnpm:

```sh
pnpm add @xyo-network/xl1-rpc
```

Using bun:

```sh
bun add @xyo-network/xl1-rpc
```

## Build Targets

| Export | Contents |
|--------|----------|
| `.` | Client + server (full package) |
| `./client` | JsonRpc providers, transports, types, outbound engine handlers |
| `./server` | Inbound RPC engines (`rpcEngineFromConnection`, middleware) |

```ts
import { JsonRpcBlockViewer } from '@xyo-network/xl1-rpc/client'
import { composedRpcEngineFromConnection } from '@xyo-network/xl1-rpc/server'
import { JsonRpcBlockViewer, rpcEngineFromConnection } from '@xyo-network/xl1-rpc'
```

## What's Inside

**Type system**

- 25 RPC type-mapping files deriving `${viewer}_${method}` names and handler types from each viewer's `Methods` interface
- 22 Zod schema maps with `to`/`from` serialization transforms for request and response
- `AllRpcSchemas` — aggregate registry of every schema, used by transports for auto-validation

**Engine handlers**

- 16 `rpcMethodHandlersFrom*` factories that adapt a viewer/runner instance into JSON-RPC method handlers
- `rpcMethodHandlersFromConnection` — full orchestrator that wires every handler from an `XyoConnection`

**Providers (client-side)**

- `JsonRpc*Viewer` and `JsonRpc*Runner` implementations that delegate to a transport
- `JsonRpcXyoViewer` — composite client viewer covering the full read surface

**Transports**

- `MemoryRpcTransport` — in-memory engine, useful for tests and same-process composition
- `HttpRpcTransport` — HTTP/HTTPS transport
- `PostMessageRpcTransport` — cross-window messaging with `SessionEnvelope` and `MessageBus` abstraction (used by browser wallet integrations)

## Building Locally

```sh
xy build @xyo-network/xl1-rpc
xy test @xyo-network/xl1-rpc
xy lint @xyo-network/xl1-rpc
```

## 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 (LGPL-3.0-only).

## Credits

[Made with 🔥 and ❄️ by XYO Foundation](https://xyo.network)

[npm-badge]: https://img.shields.io/npm/v/@xyo-network/xl1-rpc.svg
[npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-rpc
[license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-rpc.svg
[license-link]: ./LICENSE
[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png