0
# XYO Network Payload Model
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @xyo-network/payload-model
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @xyo-network/payload-model`
10

11
## Core Imports
12

13
**Core Types and Interfaces:**
14
```typescript
15
import { 
16
  // Base payload types
17
  Payload, 
18
  PayloadFields,
19
  PayloadMetaFields,
20
  Schema,
21
  
22
  // Type guards and validation
23
  isPayload, 
24
  isPayloadOfSchemaType,
25
  isAnyPayload,
26
  isSchema,
27
  
28
  // Storage metadata
29
  StorageMeta,
30
  WithStorageMeta,
31
  SequenceParser
32
} from "@xyo-network/payload-model";
33
```
34

35
**Advanced Types and Utilities:**
36
```typescript
37
import {
38
  // Validation functions
39
  PayloadValidationFunction,
40
  SyncPayloadValidationFunction,
41
  AsyncPayloadValidationFunction,
42
  
43
  // Bundles and queries
44
  PayloadBundle,
45
  PayloadBundleFields,
46
  Query,
47
  QueryFields,
48
  
49
  // Error handling
50
  ModuleError,
51
  
52
  // Utility types
53
  PayloadFindFilter,
54
  PayloadHashMap,
55
  PayloadValueExpression,
56
  PayloadProperty,
57
  PayloadValue,
58
  
59
  // PayloadSet types
60
  PayloadSet,
61
  PayloadSetPayload,
62
  
63
  // Timestamp utilities
64
  Timestamp,
65
  WithTimestamp,
66
  
67
  // Zod schemas
68
  PayloadZod,
69
  StorageMetaZod,
70
  AnyPayloadZod
71
} from "@xyo-network/payload-model";
72
```
73

74
**Sequence and Storage Types:**
75
```typescript
76
import {
77
  // Sequence types
78
  Sequence,
79
  LocalSequence,
80
  QualifiedSequence,
81
  Epoch,
82
  Nonce,
83
  
84
  // Storage metadata interfaces
85
  HashStorageMeta,
86
  DataHashStorageMeta,
87
  SequenceStorageMeta,
88
  
89
  // Constants
90
  SequenceConstants,
91
  LocalSequenceConstants,
92
  QualifiedSequenceConstants
93
} from "@xyo-network/payload-model";
94
```
95

96
For CommonJS:
97

98
```javascript
99
const { 
100
  // Core types
101
  Payload, 
102
  Schema, 
103
  isPayload, 
104
  isPayloadOfSchemaType,
105
  
106
  // Storage metadata
107
  StorageMeta,
108
  SequenceParser,
109
  
110
  // Validation
111
  PayloadValidationFunction,
112
  
113
  // Utilities
114
  PayloadBundle,
115
  Query,
116
  ModuleError
117
} = require("@xyo-network/payload-model");
118
```
119

120
## Basic Usage
121

122
```typescript
123
import { 
124
  Payload, 
125
  isPayload, 
126
  isPayloadOfSchemaType,
127
  Schema 
128
} from "@xyo-network/payload-model";
129

130
// Define a custom payload type
131
const MySchema = "network.example.my-payload" as const;
132
interface MyPayload extends Payload {
133
  data: string;
134
  timestamp: number;
135
  schema: typeof MySchema;
136
}
137

138
// Create a payload
139
const payload: MyPayload = {
140
  schema: MySchema,
141
  data: "hello world",
142
  timestamp: Date.now()
143
};
144

145
// Validate payload structure
146
if (isPayload([MySchema])(payload)) {
147
  console.log("Valid payload");
148
}
149

150
// Type-safe schema validation
151
const isMyPayload = isPayloadOfSchemaType<MyPayload>(MySchema);
152
if (isMyPayload(payload)) {
153
  // TypeScript knows this is MyPayload
154
  console.log(payload.data);
155
}
156
```
157

158
## Architecture
159

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

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

171
## Capabilities
172

173
### Core Payload Types
174

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

177
```typescript { .api }
178
type Payload<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = 
179
  (T extends WithSchema
180
    ? S extends Schema
181
      ? WithPayload<Omit<T, 'schema'> & { schema: S }>
182
      : WithPayload<T>
183
    : T extends object
184
      ? S extends Schema
185
        ? WithPayload<T & { schema: S }>
186
        : WithPayload<T & PayloadFields>
187
      : WithPayload<{
188
        schema: S extends Schema ? S : Schema
189
      }>) & Partial<PayloadMetaFields>;
190

191
type Schema = string;
192

193
interface PayloadFields extends SchemaField {
194
  schema: Schema;
195
}
196
```
197

198
[Core Payload Types](./core-payload-types.md)
199

200
### Type Guards and Validation
201

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

204
```typescript { .api }
205
function isPayload<T extends Payload>(schema: string[]): (value: unknown) => value is T;
206

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

211
function isAnyPayload(value: unknown): value is Payload;
212
```
213

214
[Type Guards and Validation](./type-guards.md)
215

216
### Storage Metadata
217

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

220
```typescript { .api }
221
interface StorageMeta extends SequenceStorageMeta, HashStorageMeta {
222
  _hash: Hash;
223
  _dataHash: Hash;
224
  _sequence: Sequence;
225
}
226

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

229
class SequenceParser {
230
  static from(sequence: Sequence, address?: Address): SequenceParser;
231
  get address(): Address;
232
  get epoch(): Epoch;
233
  get localSequence(): LocalSequence;
234
  get nonce(): Nonce;
235
  get qualifiedSequence(): QualifiedSequence;
236
}
237
```
238

239
[Storage Metadata](./storage-metadata.md)
240

241
### Payload Bundles and Queries
242

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

245
```typescript { .api }
246
interface PayloadBundleFields<T extends Payload = Payload> {
247
  payloads: T[];
248
  root: Hash;
249
}
250

251
type PayloadBundle = Payload<PayloadBundleFields, PayloadBundleSchema>;
252

253
interface QueryFields {
254
  address?: Address | Address[];
255
  budget?: number;
256
  maxFrequency?: 'once' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
257
  minBid?: number;
258
}
259

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

264
[Payload Bundles and Queries](./bundles-queries.md)
265

266
### Validation and Error Handling
267

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

270
```typescript { .api }
271
type PayloadValidationFunction<T extends Payload = Payload> = 
272
  SyncPayloadValidationFunction<T> | AsyncPayloadValidationFunction<T>;
273

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

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

278
interface ModuleError extends Payload {
279
  details?: JsonValue;
280
  message?: string;
281
  name?: string;
282
  query?: Hash | Schema;
283
  schema: ModuleErrorSchema;
284
}
285
```
286

287
[Validation and Error Handling](./validation-errors.md)
288

289
### Utility Types
290

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

293
```typescript { .api }
294
interface PayloadFindFilter {
295
  limit?: number;
296
  order?: 'desc' | 'asc';
297
  schema?: string | string[];
298
}
299

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

305
type PayloadValueExpression<T extends Payload = Payload, Key extends PayloadProperty<T> = PayloadProperty<T>, TValue = PayloadValue<T, Key>> = 
306
  (payload: T) => TValue;
307
```
308

309
[Utility Types](./utility-types.md)