@xyo-network/xl1-protocol-model 1.26.1

package/src/model/spec/fixtures/signedHydratedTransaction.ts

@@ -0,0 +1,58 @@
+export const signedHydratedTransactionWithHashMeta = [
+  {
+    schema: 'network.xyo.boundwitness',
+    addresses: [
+      'ae2966ff28d3b82e91dbec3fb1e285152ba2e782',
+    ],
+    payload_hashes: [
+      '7c4deb6830f9c2f45d61691467825dd1ec08c22b1ac178d8b0737af714a4a636',
+      'b0a65744aac6d5a1cc79af5e51d6631618c2b6672f294b1972760019a9b4e174',
+    ],
+    payload_schemas: [
+      'network.xyo.boundwitness',
+      'network.xyo.stock.market.tzero.snapshot',
+    ],
+    previous_hashes: [
+      null,
+    ],
+    $signatures: [
+      'fa229bc173704cdbe226f44e15f1f7a7df44fdfe575ffc96ce6f24574b21065f02c3a4d8f84beb01dfd26d70128ca0cb2f69b4f9ec912c2310e4ee5f999619d3',
+    ],
+    nbf: 250_042,
+    exp: 250_052,
+    fees: {
+      base: 'e8d4a51000',
+      gasLimit: '038d7ea4c68000',
+      gasPrice: '02540be400',
+      priority: '00',
+    },
+    chain: 'dd381fbb392c85160d8b0453e446757b12384046',
+    from: 'ae2966ff28d3b82e91dbec3fb1e285152ba2e782',
+    _dataHash: 'c3afe940115d0bc2581567d59586f42e5be3f2fe6b42520834a0ec3920dee98b',
+    _hash: 'f8b6222c9361e60ddff5982b4e88d3746c2e072edaf58611368b0ad651ee67c2',
+    _sequence: '00000000000000000000000051ee67c2',
+  },
+  [{
+    askPrice: 0.28,
+    askPriceRate: null,
+    askQtyBookTotal: 140_619,
+    askQuantity: 716,
+    bidPrice: 0.18,
+    bidPriceRate: null,
+    bidQtyBookTotal: 7688,
+    bidQuantity: 2,
+    high: null,
+    lastPrice: null,
+    lastQuantity: null,
+    low: null,
+    open: null,
+    prevClosePx: 0.28,
+    schema: 'network.xyo.stock.market.tzero.snapshot',
+    symbol: 'XYLB',
+    timestamp: '2026-01-19T17:22:02.108746148-05:00',
+    volume: 0,
+    _dataHash: 'b0a65744aac6d5a1cc79af5e51d6631618c2b6672f294b1972760019a9b4e174',
+    _hash: 'b0a65744aac6d5a1cc79af5e51d6631618c2b6672f294b1972760019a9b4e174',
+    _sequence: '0000019bd859cdf500000001a9b4e174',
+  }],
+]

package/src/model/spec/fixtures/unsignedHydratedTransaction.ts

@@ -0,0 +1,62 @@
+export const unsignedHydratedTransactionWithHashMeta = [
+  {
+    $signatures: [],
+    addresses: [],
+    chain: '944ac6a2ffc27ab773f34193e43f20ab7542b0ea',
+    exp: 11,
+    fees: {
+      base: 'e8d4a51000',
+      gasLimit: '038d7ea4c68000',
+      gasPrice: '02540be400',
+      priority: '00',
+    },
+    from: 'c5c9d2a8e8d0b0eba521aec623ffcb9e0982f513',
+    nbf: 1,
+    payload_hashes: [
+      '01bbcd4c58fd88488882ba54e13e92603f13c34695eda64780502acc80c3fcc1',
+      'ff127a824dc672ff5b7a32d2c7deffcdde3cc417ad112510532f24a2e948516a',
+      '92693e6fefeed94eb80872ba9e2c86d7861fc84e4bc5b775ebe9966e68c26767',
+      '85009387d332dffa781bbf6fa107715f36f9d6b3294c5cc8fd1ce8ada207d2bb',
+    ],
+    payload_schemas: [
+      'network.xyo.hash',
+      'network.xyo.hash',
+      'network.xyo.id',
+      'network.xyo.id',
+    ],
+    previous_hashes: [],
+    schema: 'network.xyo.boundwitness',
+    script: [
+      'elevate|01bbcd4c58fd88488882ba54e13e92603f13c34695eda64780502acc80c3fcc1',
+      'elevate|ff127a824dc672ff5b7a32d2c7deffcdde3cc417ad112510532f24a2e948516a',
+    ],
+    _dataHash: '214029ca586455e66fea02896c6d69739e400917c08e4e8ec1e9818c4a19bb17',
+    _hash: '59aacdd66055a63e6a0686a33f155be5b6afca0630a9abfee7ae9e79f057eec8',
+  },
+  [
+    {
+      hash: '92693e6fefeed94eb80872ba9e2c86d7861fc84e4bc5b775ebe9966e68c26767',
+      schema: 'network.xyo.hash',
+      _dataHash: '01bbcd4c58fd88488882ba54e13e92603f13c34695eda64780502acc80c3fcc1',
+      _hash: '01bbcd4c58fd88488882ba54e13e92603f13c34695eda64780502acc80c3fcc1',
+    },
+    {
+      hash: '85009387d332dffa781bbf6fa107715f36f9d6b3294c5cc8fd1ce8ada207d2bb',
+      schema: 'network.xyo.hash',
+      _dataHash: 'ff127a824dc672ff5b7a32d2c7deffcdde3cc417ad112510532f24a2e948516a',
+      _hash: 'ff127a824dc672ff5b7a32d2c7deffcdde3cc417ad112510532f24a2e948516a',
+    },
+    {
+      salt: 'Hello from Sample 0 - 2026-01-15T22:41:36.587Z',
+      schema: 'network.xyo.id',
+      _dataHash: '92693e6fefeed94eb80872ba9e2c86d7861fc84e4bc5b775ebe9966e68c26767',
+      _hash: '92693e6fefeed94eb80872ba9e2c86d7861fc84e4bc5b775ebe9966e68c26767',
+    },
+    {
+      salt: 'Hello from Sample 1 - 2026-01-15T22:41:36.587Z',
+      schema: 'network.xyo.id',
+      _dataHash: '85009387d332dffa781bbf6fa107715f36f9d6b3294c5cc8fd1ce8ada207d2bb',
+      _hash: '85009387d332dffa781bbf6fa107715f36f9d6b3294c5cc8fd1ce8ada207d2bb',
+    },
+  ],
+]

package/src/model/version.ts

@@ -0,0 +1,10 @@
+/** XL1_PROTOCOL_VERSION_MAJOR constant. */
+export const XL1_PROTOCOL_VERSION_MAJOR = 1 as const
+/** XL1_PROTOCOL_VERSION_MINOR constant. */
+export const XL1_PROTOCOL_VERSION_MINOR = 2 as const
+/** XL1_PROTOCOL_VERSION_PATCH constant. */
+export const XL1_PROTOCOL_VERSION_PATCH = 0 as const
+/** XL1_PROTOCOL_VERSION_STRING constant. */
+export const XL1_PROTOCOL_VERSION_STRING = `${XL1_PROTOCOL_VERSION_MAJOR}.${XL1_PROTOCOL_VERSION_MINOR}.${XL1_PROTOCOL_VERSION_PATCH}` as const
+/** XL1_PROTOCOL_VERSION constant. */
+export const XL1_PROTOCOL_VERSION = XL1_PROTOCOL_VERSION_MAJOR * 1_000_000 + XL1_PROTOCOL_VERSION_MINOR * 1000 + XL1_PROTOCOL_VERSION_PATCH

package/src/payload/StepIdentityPayload.ts

@@ -0,0 +1,25 @@
+import { AsObjectFactory } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfZodType } from '@xyo-network/sdk-js'
+import type { z } from 'zod'
+
+import { StepIdentityZod } from '../Step/index.ts'
+
+/** Schema identifier for step identity payloads. */
+export const StepIdentitySchema = asSchema('network.xyo.chain.step.identity', true)
+/** Schema type for StepIdentity payloads. */
+export type StepIdentitySchema = typeof StepIdentitySchema
+
+/** Fields for a step identity, inferred from the StepIdentityZod schema. */
+export type StepIdentityFields = z.infer<typeof StepIdentityZod>
+
+/**
+ * A Step Identity Payload
+ */
+export type StepIdentityPayload = Payload<StepIdentityFields, StepIdentitySchema>
+
+/** Type guard that checks whether a value is a StepIdentityPayload. */
+export const isStepIdentityPayload = isPayloadOfZodType<StepIdentityPayload>(StepIdentityZod, StepIdentitySchema)
+
+/** Casts a value to StepIdentityPayload or returns undefined if it does not match. */
+export const asStepIdentityPayload = AsObjectFactory.create(isStepIdentityPayload)

package/src/payload/elevatable/Bridge/BridgeCompletion.ts

@@ -0,0 +1,28 @@
+import type { Hash } from '@xylabs/sdk-js'
+
+/**
+ * Final confirmation tying the intent and the observation together.
+ */
+export interface BridgeCompletionFields {
+
+  /**
+   * Block number, event ID, or timestamp when the bridge was completed
+   */
+  completedAt?: Hash
+
+  /**
+   * Reference to observed destination confirmation hash
+   */
+  destObservation: Hash
+
+  /**
+   * Reference to source intent hash
+   */
+  srcIntent?: Hash
+
+  /**
+   * Reference to observed source confirmation hash
+   */
+  srcObservation: Hash
+
+}

package/src/payload/elevatable/Bridge/BridgeDestinationObservation.ts

@@ -0,0 +1,38 @@
+import { AsObjectFactory, HexZod } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfZodType } from '@xyo-network/sdk-js'
+import type { z } from 'zod'
+
+import { BridgeDetailsFieldsZod } from './BridgeDetails.ts'
+
+/** Schema identifier for BridgeDestinationObservation payloads. */
+export const BridgeDestinationObservationSchema = asSchema('network.xyo.chain.bridge.observation.destination', true)
+/** Schema type for BridgeDestinationObservation payloads. */
+export type BridgeDestinationObservationSchema = typeof BridgeDestinationObservationSchema
+
+/**
+ * Represents an observation that confirms a bridge action occurred on the destination chain.
+ */
+export const BridgeDestinationObservationFieldsZod = BridgeDetailsFieldsZod.extend({
+  /**
+   * Destination chain confirmation
+   */
+  destConfirmation: HexZod.optional().describe('Destination chain confirmation'),
+})
+
+/** BridgeDestinationObservationFields type. */
+export type BridgeDestinationObservationFields = z.infer<typeof BridgeDestinationObservationFieldsZod>
+
+/**
+ * Represents an observation that confirms a bridge action occurred on the destination chain.
+ */
+export type BridgeDestinationObservation = Payload<BridgeDestinationObservationFields, BridgeDestinationObservationSchema>
+
+/** Type guard that checks if a value is a valid BridgeDestinationObservation. */
+export const isBridgeDestinationObservation = isPayloadOfZodType<BridgeDestinationObservation>(
+  BridgeDestinationObservationFieldsZod,
+  BridgeDestinationObservationSchema,
+)
+
+/** Converts a value to BridgeDestinationObservation, throwing if invalid. */
+export const asBridgeDestinationObservation = AsObjectFactory.create(isBridgeDestinationObservation)

package/src/payload/elevatable/Bridge/BridgeDetails.ts

@@ -0,0 +1,69 @@
+import { HexZod } from '@xylabs/sdk-js'
+import { z } from 'zod'
+
+/**
+ * Represents a transfer destination
+ */
+export const BridgeDetailsDestinationFieldsZod = z.object({
+  /**
+   * Destination network
+   */
+  dest: HexZod.describe('The destination network identifier'),
+  /**
+   * Destination address (EOA or contract)
+   */
+  destAddress: HexZod.describe('The destination address (EOA or contract)'),
+  /**
+   * Token amount to bridge to destination
+   */
+  destAmount: HexZod.describe('The token amount to bridge to destination'),
+  /**
+   * Token being bridged to
+   */
+  destToken: HexZod.describe('The token being bridged to'),
+})
+
+/**
+ * Represents a transfer destination
+ */
+export type BridgeDetailsDestinationFields = z.infer<typeof BridgeDetailsDestinationFieldsZod>
+
+/**
+ * Represents a transfer source
+ */
+export const BridgeDetailsSourceFieldsZod = z.object({
+  /**
+   * Source network
+   */
+  src: HexZod.describe('The source network identifier'),
+
+  /**
+   * Source address (EOA or contract)
+   */
+  srcAddress: HexZod.describe('The source address (EOA or contract)'),
+  /**
+   * Token amount to bridge from source
+   */
+  srcAmount: HexZod.describe('The token amount to bridge from source'),
+  /**
+   * Token being bridged from
+   */
+  srcToken: HexZod.describe('The token being bridged from'),
+})
+
+/**
+ * Represents a transfer source
+ */
+export type BridgeDetailsSourceFields = z.infer<typeof BridgeDetailsSourceFieldsZod>
+
+/**
+ * Represents a transfer from a source chain/token/address/amount to a destination chain/token/address/amount.
+ */
+export const BridgeDetailsFieldsZod = BridgeDetailsSourceFieldsZod.extend(
+  BridgeDetailsDestinationFieldsZod.shape,
+)
+
+/**
+ * Represents a transfer from a source chain/token/address/amount to a destination chain/token/address/amount.
+ */
+export type BridgeDetailsFields = z.infer<typeof BridgeDetailsFieldsZod>

package/src/payload/elevatable/Bridge/BridgeIntent.ts

@@ -0,0 +1,36 @@
+import { AsObjectFactory } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfZodType } from '@xyo-network/sdk-js'
+import { z } from 'zod'
+
+import { BridgeDetailsFieldsZod } from './BridgeDetails.ts'
+
+/** Schema identifier for BridgeIntent payloads. */
+export const BridgeIntentSchema = asSchema('network.xyo.chain.bridge.intent', true)
+/** Schema type for BridgeIntent payloads. */
+export type BridgeIntentSchema = typeof BridgeIntentSchema
+
+/**
+ * Represents an Address's intent to initiate a token bridge.
+ */
+export const BridgeIntentFieldsZod = BridgeDetailsFieldsZod.extend({
+  /**
+   * Unique identifier for replay protection
+   */
+  nonce: z.string().describe('Unique identifier for replay protection'),
+})
+
+/** BridgeIntentFields type. */
+export type BridgeIntentFields = z.infer<typeof BridgeIntentFieldsZod>
+
+/** BridgeIntent type. */
+export type BridgeIntent = Payload<BridgeIntentFields, BridgeIntentSchema>
+
+/** Type guard that checks if a value is a valid BridgeIntent. */
+export const isBridgeIntent = isPayloadOfZodType<BridgeIntent>(
+  BridgeIntentFieldsZod,
+  BridgeIntentSchema,
+)
+
+/** Converts a value to BridgeIntent, throwing if invalid. */
+export const asBridgeIntent = AsObjectFactory.create(isBridgeIntent)

package/src/payload/elevatable/Bridge/BridgeSourceObservation.ts

@@ -0,0 +1,37 @@
+import { AsObjectFactory, HexZod } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfZodType } from '@xyo-network/sdk-js'
+import type { z } from 'zod'
+
+import { BridgeDetailsFieldsZod } from './BridgeDetails.ts'
+
+/** Schema identifier for BridgeSourceObservation payloads. */
+export const BridgeSourceObservationSchema = asSchema('network.xyo.chain.bridge.observation.source', true)
+/** Schema type for BridgeSourceObservation payloads. */
+export type BridgeSourceObservationSchema = typeof BridgeSourceObservationSchema
+
+/**
+ * Represents an observation that confirms a bridge action occurred on the source chain.
+ */
+export const BridgeSourceObservationFieldsZod = BridgeDetailsFieldsZod.extend({
+  /**
+   * Source chain confirmation
+   */
+  srcConfirmation: HexZod.optional().describe('Source chain confirmation'),
+})
+
+/** BridgeSourceObservationFields type. */
+export type BridgeSourceObservationFields = z.infer<typeof BridgeSourceObservationFieldsZod>
+/**
+ * Represents an observation that confirms a bridge action occurred on the source chain.
+ */
+export type BridgeSourceObservation = Payload<BridgeSourceObservationFields, BridgeSourceObservationSchema>
+
+/** Type guard that checks if a value is a valid BridgeSourceObservation. */
+export const isBridgeSourceObservation = isPayloadOfZodType<BridgeSourceObservation>(
+  BridgeSourceObservationFieldsZod,
+  BridgeSourceObservationSchema,
+)
+
+/** Converts a value to BridgeSourceObservation, throwing if invalid. */
+export const asBridgeSourceObservation = AsObjectFactory.create(isBridgeSourceObservation)

package/src/payload/elevatable/Bridge/index.ts

@@ -0,0 +1,5 @@
+export * from './BridgeCompletion.ts'
+export * from './BridgeDestinationObservation.ts'
+export * from './BridgeDetails.ts'
+export * from './BridgeIntent.ts'
+export * from './BridgeSourceObservation.ts'

package/src/payload/elevatable/ChainStakeIntent.ts

@@ -0,0 +1,45 @@
+import { AsObjectFactory } from '@xylabs/sdk-js'
+import type { Payload, WithStorageMeta } from '@xyo-network/sdk-js'
+import {
+  asSchema, isPayloadOfSchemaType, isStorageMeta,
+} from '@xyo-network/sdk-js'
+
+import type { BlockDuration } from '../../fields/index.ts'
+import type { FromFields } from './Executable.ts'
+
+/** Schema identifier for chain stake intent payloads. */
+export const ChainStakeIntentSchema = asSchema('network.xyo.chain.stake.intent', true)
+/** Schema type for ChainStakeIntent payloads. */
+export type ChainStakeIntentSchema = typeof ChainStakeIntentSchema
+
+/** The type of staking intent, currently limited to 'producer'. */
+export type Intent = 'producer' // | 'bank'
+
+/** Fields for a chain stake intent, including the staking intent type and source address. */
+export interface ChainStakeIntentFields extends BlockDuration, FromFields {
+  /*
+  * The intent of the staking
+  */
+  intent: Intent
+}
+
+/** A payload representing an intent to stake on the chain. */
+export type ChainStakeIntent = Payload<ChainStakeIntentFields, ChainStakeIntentSchema>
+
+/** Type guard that checks whether a value is a valid ChainStakeIntent with non-negative nbf and exp. */
+export const isChainStakeIntent = (x?: unknown | null): x is ChainStakeIntent => {
+  return isPayloadOfSchemaType<ChainStakeIntent>(ChainStakeIntentSchema)(x)
+    && asNonNegativeInteger(x.nbf) !== undefined
+    && asNonNegativeInteger(x.exp) !== undefined
+}
+/** Casts a value to ChainStakeIntent or returns undefined if it does not match. */
+export const asChainStakeIntent = AsObjectFactory.create(isChainStakeIntent)
+
+/** Type guard that checks whether a value is a ChainStakeIntent with storage metadata. */
+export const isChainStakeIntentWithStorageMeta = (x?: unknown | null): x is WithStorageMeta<ChainStakeIntent> => {
+  return isChainStakeIntent(x) && isStorageMeta(x)
+}
+
+const asNonNegativeInteger = (num: number) => {
+  return (Number.isInteger(num) && num >= 0) ? num : undefined
+}

package/src/payload/elevatable/Executable.ts

@@ -0,0 +1,35 @@
+import type { Address, EmptyObject } from '@xylabs/sdk-js'
+import { isAnyPayload } from '@xyo-network/sdk-js'
+
+/** FromFields interface. */
+export interface FromFields {
+  // the address that is treated as the source of this action
+  from: Address
+}
+
+/** hasFrom constant. */
+export const hasFrom = (value: unknown): value is FromFields => {
+  return (value as FromFields).from !== undefined
+}
+
+/** ExecutableFields interface. */
+export interface ExecutableFields {
+  script: string[]
+}
+
+/** Executable type. */
+export type Executable<T extends EmptyObject = EmptyObject> = T & ExecutableFields
+/** OptionalExecutable type. */
+export type OptionalExecutable<T extends EmptyObject = EmptyObject> = T & Partial<ExecutableFields>
+
+/** Type guard that checks if a value is a valid Executable. */
+export const isExecutable = <T extends EmptyObject>(value: T | undefined): value is Executable<T> => {
+  return isAnyPayload(value) && Array.isArray((value as unknown as ExecutableFields).script)
+}
+
+/** Converts a value to Executable, throwing if invalid. */
+export const asExecutable = <T extends EmptyObject>(value: T | undefined): Executable<T> | undefined => {
+  return isExecutable(value)
+    ? value as unknown as Executable<T>
+    : undefined
+}

package/src/payload/elevatable/Hash.ts

@@ -0,0 +1,25 @@
+import type { Hash } from '@xylabs/sdk-js'
+import { AsObjectFactory } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfSchemaType } from '@xyo-network/sdk-js'
+
+/** Schema identifier for hash payloads. */
+export const HashSchema = asSchema('network.xyo.hash', true)
+/** Schema type for Hash payloads. */
+export type HashSchema = typeof HashSchema
+
+/** Fields for a hash payload containing a single hash value. */
+export interface HashFields {
+  hash: Hash
+}
+
+/** A payload containing a hash value. */
+export type HashPayload = Payload<HashFields, HashSchema>
+
+/** Type guard that checks whether a value is a HashPayload. */
+export const isHashPayload = isPayloadOfSchemaType<HashPayload>(HashSchema)
+
+/** Casts a value to HashPayload or returns undefined if it does not match. */
+export const asHashPayload = AsObjectFactory.create(isHashPayload)
+/** Casts a value to HashPayload with storage metadata or returns undefined. */
+export const asHashPayloadWithStorageMeta = AsObjectFactory.create(isHashPayload)

package/src/payload/elevatable/StepComplete.ts

@@ -0,0 +1,31 @@
+import type { Hash } from '@xylabs/sdk-js'
+import { AsObjectFactory } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+import { asSchema, isPayloadOfSchemaType } from '@xyo-network/sdk-js'
+
+import type { FromFields } from './Executable.ts'
+
+/** Schema identifier for StepComplete payloads. */
+export const StepCompleteSchema = asSchema('network.xyo.chain.step.complete', true)
+/** Schema type for StepComplete payloads. */
+export type StepCompleteSchema = typeof StepCompleteSchema
+
+/* This records the completion of a step in the network - needed for network staking rewards */
+/* We will only write these for steps that are eligible for rewards  Step 3 (2311) */
+
+export interface StepCompleteFields extends FromFields {
+  block: number /* The block number on the XL1 network */
+  hash: Hash /* The Step Hash */
+  size: number /* The size of the step */
+  stakeBlock: number /* The block number on ethereum or other staking system */
+}
+
+// if this payload is included in a boundwitness, it needs to be available for inspection to be included in block
+/** StepComplete type. */
+export type StepComplete = Payload<StepCompleteFields, StepCompleteSchema>
+
+/** Type guard that checks if a value is a valid StepComplete. */
+export const isStepComplete = isPayloadOfSchemaType<StepComplete>(StepCompleteSchema)
+
+/** Converts a value to StepComplete, throwing if invalid. */
+export const asStepComplete = AsObjectFactory.create(isStepComplete)

package/src/payload/elevatable/Time.ts

@@ -0,0 +1,61 @@
+import { AsObjectFactory, HashZod } from '@xylabs/sdk-js'
+import {
+  asSchema, isPayloadOfSchemaType, PayloadZodOfSchema,
+} from '@xyo-network/sdk-js'
+import { z } from 'zod'
+
+// xl1 = xl1 block number, epoch = epoch number, ethereum = ethereum block number
+/** Supported time domains: xl1 block number, epoch timestamp, or ethereum block number. */
+export type TimeDomain = 'xl1' | 'epoch' | 'ethereum'
+
+/** Schema identifier for time payloads. */
+export const TimeSchema = asSchema('network.xyo.time', true)
+/** Schema type for Time payloads. */
+export type TimeSchema = typeof TimeSchema
+
+/** Zod schema for XL1 time fields including block number and hash. */
+export const XL1TimeFieldsZod = z.object({
+  // block number
+  xl1: z.number().optional(),
+  // block hash
+  xl1Hash: HashZod.optional(),
+})
+
+/** Zod schema for Ethereum time fields including block number and hash. */
+export const EthereumTimeFieldsZod = z.object({
+  // block number
+  ethereum: z.number().optional(),
+  // block hash
+  ethereumHash: HashZod.optional(),
+})
+
+/** Zod schema for epoch time fields in milliseconds. */
+export const EpochTimeFieldsZod = z.object({
+  // in milliseconds
+  epoch: z.number(),
+})
+
+/** Combined Zod schema for all time fields across XL1, Ethereum, and epoch domains. */
+export const TimeFieldsZod = XL1TimeFieldsZod.extend(XL1TimeFieldsZod.shape).extend(EthereumTimeFieldsZod.shape).extend(EpochTimeFieldsZod.shape)
+
+/** Zod schema for a complete time payload including schema and all time fields. */
+export const TimePayloadZod = PayloadZodOfSchema(TimeSchema).extend(TimeFieldsZod.shape)
+
+/** A payload containing time information across multiple domains. */
+export type TimePayload = z.infer<typeof TimePayloadZod>
+
+// to prevent scaling problems, we use double the current time as a max safe epoch
+/** Checks whether a value is a safe epoch timestamp (less than double the current time). */
+export const isSafeEpoch = (value: unknown): value is number => {
+  return typeof value === 'number' && value < 2 * Date.now()
+}
+
+/** Type guard that checks whether a value is a valid TimePayload with a safe epoch. */
+export const isTimePayload = (value: unknown): value is TimePayload => {
+  return isPayloadOfSchemaType<TimePayload>(TimeSchema)(value) && isSafeEpoch(value.epoch)
+}
+
+/** Casts a value to TimePayload or returns undefined if it does not match. */
+export const asTimePayload = AsObjectFactory.create(isTimePayload)
+/** Casts a value to TimePayload with storage metadata or returns undefined. */
+export const asTimePayloadWithStorageMeta = AsObjectFactory.create(isTimePayload)

package/src/payload/elevatable/index.ts

@@ -0,0 +1,6 @@
+export * from './Bridge/index.ts'
+export * from './ChainStakeIntent.ts'
+export * from './Executable.ts'
+export * from './Hash.ts'
+export * from './StepComplete.ts'
+export * from './Time.ts'

package/src/payload/index.ts

@@ -0,0 +1,2 @@
+export * from './elevatable/index.ts'
+export * from './StepIdentityPayload.ts'

package/src/provider/Provider.ts

@@ -0,0 +1,6 @@
+import type { ProviderMoniker } from './ProviderMoniker.ts'
+
+/** Provider interface. */
+export interface Provider<T extends ProviderMoniker> {
+  moniker: T
+}

package/src/provider/ProviderMoniker.ts

@@ -0,0 +1,15 @@
+import { assertEx, isString } from '@xylabs/sdk-js'
+
+/** Type literal for the Provider provider moniker. */
+export type ProviderMoniker = string
+
+/** Moniker identifier for the asProvider provider. */
+export const asProviderMoniker = <T>(value: T) => {
+  const moniker = isString(value) ? (value as unknown as ProviderMoniker) : undefined
+  return assertEx(moniker)
+}
+
+/** Moniker identifier for the DefaultProvider provider. */
+export const DefaultProviderMoniker = 'Provider' as const
+/** Type literal for the DefaultProvider provider moniker. */
+export type DefaultProviderMoniker = typeof DefaultProviderMoniker

package/src/provider/index.ts

@@ -0,0 +1,2 @@
+export * from './Provider.ts'
+export * from './ProviderMoniker.ts'