or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bundles-queries.mdcore-payload-types.mdindex.mdstorage-metadata.mdtype-guards.mdutility-types.mdvalidation-errors.md
tile.json

tessl/npm-xyo-network--payload-model

Core payload modeling capabilities for the XYO Protocol 2.0 ecosystem, offering TypeScript interfaces and types for defining, validating, and manipulating payloads within the XYO blockchain network.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@xyo-network/payload-model@5.1.x

To install, run

npx @tessl/cli install tessl/npm-xyo-network--payload-model@5.1.0

index.mddocs/

XYO Network Payload Model

XYO Network Payload Model provides core payload modeling capabilities for the XYO Protocol 2.0 ecosystem. It offers comprehensive TypeScript interfaces and types for defining, validating, and manipulating payloads within the XYO blockchain network, including essential abstractions for payload schemas, validation functions, value expressions, and query mechanisms.

Package Information

  • Package Name: @xyo-network/payload-model
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @xyo-network/payload-model

Core Imports

Core Types and Interfaces:

import { 
  // Base payload types
  Payload, 
  PayloadFields,
  PayloadMetaFields,
  Schema,
  
  // Type guards and validation
  isPayload, 
  isPayloadOfSchemaType,
  isAnyPayload,
  isSchema,
  
  // Storage metadata
  StorageMeta,
  WithStorageMeta,
  SequenceParser
} from "@xyo-network/payload-model";

Advanced Types and Utilities:

import {
  // Validation functions
  PayloadValidationFunction,
  SyncPayloadValidationFunction,
  AsyncPayloadValidationFunction,
  
  // Bundles and queries
  PayloadBundle,
  PayloadBundleFields,
  Query,
  QueryFields,
  
  // Error handling
  ModuleError,
  
  // Utility types
  PayloadFindFilter,
  PayloadHashMap,
  PayloadValueExpression,
  PayloadProperty,
  PayloadValue,
  
  // PayloadSet types
  PayloadSet,
  PayloadSetPayload,
  
  // Timestamp utilities
  Timestamp,
  WithTimestamp,
  
  // Zod schemas
  PayloadZod,
  StorageMetaZod,
  AnyPayloadZod
} from "@xyo-network/payload-model";

Sequence and Storage Types:

import {
  // Sequence types
  Sequence,
  LocalSequence,
  QualifiedSequence,
  Epoch,
  Nonce,
  
  // Storage metadata interfaces
  HashStorageMeta,
  DataHashStorageMeta,
  SequenceStorageMeta,
  
  // Constants
  SequenceConstants,
  LocalSequenceConstants,
  QualifiedSequenceConstants
} from "@xyo-network/payload-model";

For CommonJS:

const { 
  // Core types
  Payload, 
  Schema, 
  isPayload, 
  isPayloadOfSchemaType,
  
  // Storage metadata
  StorageMeta,
  SequenceParser,
  
  // Validation
  PayloadValidationFunction,
  
  // Utilities
  PayloadBundle,
  Query,
  ModuleError
} = require("@xyo-network/payload-model");

Basic Usage

import { 
  Payload, 
  isPayload, 
  isPayloadOfSchemaType,
  Schema 
} from "@xyo-network/payload-model";

// Define a custom payload type
const MySchema = "network.example.my-payload" as const;
interface MyPayload extends Payload {
  data: string;
  timestamp: number;
  schema: typeof MySchema;
}

// Create a payload
const payload: MyPayload = {
  schema: MySchema,
  data: "hello world",
  timestamp: Date.now()
};

// Validate payload structure
if (isPayload([MySchema])(payload)) {
  console.log("Valid payload");
}

// Type-safe schema validation
const isMyPayload = isPayloadOfSchemaType<MyPayload>(MySchema);
if (isMyPayload(payload)) {
  // TypeScript knows this is MyPayload
  console.log(payload.data);
}

Architecture

The XYO Network Payload Model is built around several key components:

  • Core Payload System: Base Payload<T, S> type with flexible generic typing for custom payload structures
  • Schema System: String-based schema identification with regex validation and branded types
  • Type Guards: Comprehensive validation functions for runtime type checking and narrowing
  • Storage Metadata: Hash-based and sequence-based metadata tracking for blockchain storage
  • Query System: Structured query interface for payload discovery and filtering
  • Bundle System: Grouping multiple related payloads with root hash references
  • Validation Framework: Sync/async validation functions with Zod integration
  • Value Expression System: Type-safe property extraction and manipulation utilities

Capabilities

Core Payload Types

Foundation types and interfaces for XYO Protocol payloads, including the base Payload<T, S> type, schema definitions, and metadata handling.

type Payload<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = 
  (T extends WithSchema
    ? S extends Schema
      ? WithPayload<Omit<T, 'schema'> & { schema: S }>
      : WithPayload<T>
    : T extends object
      ? S extends Schema
        ? WithPayload<T & { schema: S }>
        : WithPayload<T & PayloadFields>
      : WithPayload<{
        schema: S extends Schema ? S : Schema
      }>) & Partial<PayloadMetaFields>;

type Schema = string;

interface PayloadFields extends SchemaField {
  schema: Schema;
}

Core Payload Types

Type Guards and Validation

Runtime validation functions for payload structure verification and type narrowing, including schema-specific type guards and validation utilities.

function isPayload<T extends Payload>(schema: string[]): (value: unknown) => value is T;

function isPayloadOfSchemaType<T extends Payload | never = never>(
  schema: T['schema']
): (x?: unknown | null) => x is T;

function isAnyPayload(value: unknown): value is Payload;

Type Guards and Validation

Storage Metadata

Hash-based and sequence-based metadata system for tracking payloads in blockchain storage, including data hash, storage hash, and sequence management.

interface StorageMeta extends SequenceStorageMeta, HashStorageMeta {
  _hash: Hash;
  _dataHash: Hash;
  _sequence: Sequence;
}

type WithStorageMeta<T extends Payload = Payload> = T & StorageMeta;

class SequenceParser {
  static from(sequence: Sequence, address?: Address): SequenceParser;
  get address(): Address;
  get epoch(): Epoch;
  get localSequence(): LocalSequence;
  get nonce(): Nonce;
  get qualifiedSequence(): QualifiedSequence;
}

Storage Metadata

Payload Bundles and Queries

System for grouping related payloads and structured querying capabilities for payload discovery and filtering.

interface PayloadBundleFields<T extends Payload = Payload> {
  payloads: T[];
  root: Hash;
}

type PayloadBundle = Payload<PayloadBundleFields, PayloadBundleSchema>;

interface QueryFields {
  address?: Address | Address[];
  budget?: number;
  maxFrequency?: 'once' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
  minBid?: number;
}

type Query<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = 
  Payload<T extends void ? QueryFields : T & QueryFields, S>;

Payload Bundles and Queries

Validation and Error Handling

Comprehensive validation framework with sync/async validation functions, error payload structures, and Zod integration for runtime validation.

type PayloadValidationFunction<T extends Payload = Payload> = 
  SyncPayloadValidationFunction<T> | AsyncPayloadValidationFunction<T>;

type SyncPayloadValidationFunction<T extends Payload = Payload> = (payload: T) => boolean;

type AsyncPayloadValidationFunction<T extends Payload = Payload> = (payload: T) => Promise<boolean>;

interface ModuleError extends Payload {
  details?: JsonValue;
  message?: string;
  name?: string;
  query?: Hash | Schema;
  schema: ModuleErrorSchema;
}

Validation and Error Handling

Utility Types

Additional utility types for payload manipulation, filtering, value expressions, and type transformations.

interface PayloadFindFilter {
  limit?: number;
  order?: 'desc' | 'asc';
  schema?: string | string[];
}

interface PayloadHashMap<TPayload extends Payload = Payload, TId extends string | number | symbol = Hash> {
  dataHash: Record<TId, TId>;
  hash: Record<TId, TPayload>;
}

type PayloadValueExpression<T extends Payload = Payload, Key extends PayloadProperty<T> = PayloadProperty<T>, TValue = PayloadValue<T, Key>> = 
  (payload: T) => TValue;

Utility Types