@xyo-network/xl1-protocol

XL1 protocol models, interfaces, schemas, and validation in one package.

Description

XL1 is the XYO Layer One blockchain protocol. This package is the protocol surface for XL1: data models, provider and viewer contracts, network metadata, JSON schema exports, and validation utilities.

Use it when you need protocol-level types or runtime validation without pulling in gateway construction, JSON-RPC transports, storage drivers, or React bindings. For application and service development, start with @xyo-network/xl1-sdk.

Install

Using npm:

npm i --save @xyo-network/xl1-protocol

Using yarn:

yarn add @xyo-network/xl1-protocol

Using pnpm:

pnpm add @xyo-network/xl1-protocol

Using bun:

bun add @xyo-network/xl1-protocol

Usage

Import the protocol layer from its explicit subpaths:

import { DefaultNetworks } from '@xyo-network/xl1-protocol/network-model'
import { BlockViewerMoniker } from '@xyo-network/xl1-protocol/protocol-lib'
import { asXL1BlockNumber } from '@xyo-network/xl1-protocol/protocol-model'

const sequence = DefaultNetworks.find(network => network.id === 'sequence')
const genesis = asXL1BlockNumber(0, true)

console.log(sequence?.name, BlockViewerMoniker, genesis)

Available subpaths:

• @xyo-network/xl1-protocol
• @xyo-network/xl1-protocol/network-model
• @xyo-network/xl1-protocol/protocol-lib
• @xyo-network/xl1-protocol/protocol-model
• @xyo-network/xl1-protocol/schema
• @xyo-network/xl1-protocol/validation
• @xyo-network/xl1-protocol/test

Documentation

• Use protocol-model for Zod-first XL1 data structures and value guards.
• Use protocol-lib for provider, viewer, runner, gateway, and status contracts.
• Use network-model for network metadata and static REST path helpers.
• Use schema and validation at serialization, storage, and chain-validation boundaries.
• Use @xyo-network/xl1-sdk when you need concrete gateway, RPC, or provider implementations.

Payload schemas, revisions, and identity

XYO schema identifiers use nonempty, dot-separated segments containing only ASCII lowercase letters and digits: ^(?:[a-z0-9]+\.)*[a-z0-9]+$. Hyphens, underscores, Unicode, whitespace, empty segments, and URL syntax are not allowed. Namespace ownership and publication rules are separate from this lexical validation. Do not strip punctuation from an actual domain to invent a namespace you do not own.

Keep schema identifiers stable. Suffixes such as .v1, .v01, and .1 are an anti-pattern for payload revisioning. Do not silently rename an existing published identifier. Keep external API/product versions in clearly named data fields instead of conflating them with the payload contract revision.

The optional $version metadata field identifies the payload contract revision:

{
  "schema": "com.example.observation",
  "$version": 1002003,
  "temperatureCelsius": 23
}

The encoding is major * 1_000_000 + minor * 1_000 + patch, with each component in 0..999. Thus 1002003 means 1.2.3. Values must be integers in 0..999999999; strings, null, fractions, and out-of-range numbers are invalid. Absence permanently means 1000000 (1.0.0). Readers interpret this default without adding it to the original payload. An omitted version and an explicitly written 1.0.0 can have different root hashes.

Use root hashes for almost all application operations. Use PayloadBuilder.hash(payload) or a verified _hash for identity, references, commitments, deduplication, and validation caches. Do not use dataHash or _dataHash for those purposes: data hashes exclude $version and all other client metadata. Root hashes include client metadata and exclude storage metadata (_ fields). A recomputed hash establishes integrity only when compared with an expected hash authenticated by the surrounding protocol.

Bound-witness signing is an intentional exception: signatures continue to cover the data hash because signatures are themselves metadata. A bound witness's own signature does not authenticate its own $version. A signed parent reference to a child's root hash does bind the child's metadata. Existing protocols that explicitly require data-hash references retain that contract until a separately reviewed migration; this guidance does not authorize replacing those hashes.

Validation must check the exact schema, version format, a deliberately supported revision, the body, and the relevant signature/reference/authorization rules. Validate $version before any metadata-stripping projection. Do not select weaker consensus, authorization, or signature rules using unauthenticated metadata, and never try older validators until one accepts the body. A format check or a schema-only predicate is not complete contract validation.

This implementation recognizes XL1 built-in payload revision 1.0.0 at its block/transaction contracts, direct Transfer/Claim/Time guards, elevated-payload admission gate, and six exported payload/bound-witness JSON schemas. For example, isTransferPayload checks both the complete Transfer body and supported revision. Generic hydrated application payloads retain their independent revisions; an application must supply its own supported-revision/body validator. The existing signed block protocol field is a different version and remains unchanged.

Published (schema, effective version) definitions are immutable. That is separate from object closure: a closed object rejects unknown fields, while an open object explicitly permits them. Set the policy for nested objects and metadata too. Evaluate old readers receiving new data and new readers replaying old data before calling a change compatible. In particular, widening an existing field's type is not automatically safe. See the canonical XYO contract and compatibility rules.

Published @xyo-network/xl1-protocol 5.4.1 and @xyo-network/xl1-sdk 5.4.1 include the XL1 enforcement described here. Their schema changes were qualified in a registry consumer with @xyo-network/sdk 7.4.0 and @xyo-network/sdk-protocol 7.4.2. Older consumer lockfiles must resolve protocol SDK/core 7.4.2 to receive the schema-cache fix. Package publication and dependency adoption do not deploy validators or activate network rules. Upgrading validators can reject arbitrary $version metadata that older software ignored. Audit historical data and plan any admission/replay activation before deployment. The repository's implementation and rollout notes separate the published-artifact checks from the earlier full source qualification at 6f50969f and describe the remaining rollout work.

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-protocol
pnpm xy test @xyo-network/xl1-protocol
pnpm xy lint @xyo-network/xl1-protocol

License

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

Credits

Made with 🔥 and ❄️ by XYO Foundation