core

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 16, 2026 License: BSD-3-Clause Imports: 3 Imported by: 0

Documentation

Overview

Package core provides shared types and utilities for the session layer. These types are imported by both on-chain (lux/node VMs) and off-chain (sessiond) code.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BytesToUint32 

func BytesToUint32(b []byte) uint32

BytesToUint32 converts big-endian bytes to uint32.

func BytesToUint64 

func BytesToUint64(b []byte) uint64

BytesToUint64 converts big-endian bytes to uint64.

func Uint32ToBytes 

func Uint32ToBytes(v uint32) []byte

Uint32ToBytes converts a uint32 to big-endian bytes.

func Uint64ToBytes 

func Uint64ToBytes(v uint64) []byte

Uint64ToBytes converts a uint64 to big-endian bytes.

Types

type ID 

type ID [32]byte

ID is a 32-byte identifier used throughout the session layer. This is the canonical ID type - all other ID types derive from this.

func ComputeRequestID 

func ComputeRequestID(serviceID, sessionID, txID ID, step, retry uint32) ID

ComputeRequestID computes a deterministic oracle request ID. H("LUX:OracleRequest:v1" || service_id || session_id || step || retry || tx_id)

func ComputeSessionID 

func ComputeSessionID(serviceID ID, epoch uint64, txID ID) ID

ComputeSessionID computes a deterministic session ID. H("LUX:Session:v1" || service_id || epoch || tx_id)

func Hash 

func Hash(data []byte) ID

Hash computes the SHA256 hash of the input and returns it as an ID.

func HashMulti 

func HashMulti(parts ...[]byte) ID

HashMulti computes a hash over multiple byte slices.

func HashWithDomain 

func HashWithDomain(domain string, data []byte) ID

HashWithDomain computes a domain-separated hash. domain || data → SHA256

func IDFromBytes 

func IDFromBytes(b []byte) ID

IDFromBytes creates an ID from a byte slice.

func (ID) Bytes 

func (id ID) Bytes() []byte

Bytes returns the ID as a byte slice.

func (ID) Empty 

func (id ID) Empty() bool

Empty returns true if the ID is all zeros.

func (ID) String 

func (id ID) String() string

String returns a hex representation of the ID.

type Session 

type Session struct {
	// ID is the unique session identifier: H("LUX:Session:v1" || service_id || epoch || tx_id)
	ID ID `json:"id"`

	// ServiceID identifies the service being executed
	ServiceID ID `json:"serviceId"`

	// Epoch in which this session was created
	Epoch uint64 `json:"epoch"`

	// TxID is the transaction that created this session
	TxID ID `json:"txId"`

	// Committee assigned to execute this session (node IDs)
	Committee []ID `json:"committee"`

	// State is the current session state
	State SessionState `json:"state"`

	// CurrentStep is the current step index
	CurrentStep uint32 `json:"currentStep"`

	// Steps are the step records for this session
	Steps []*Step `json:"steps"`

	// OutputHash is the final output hash (set when finalized)
	OutputHash ID `json:"outputHash,omitempty"`

	// OracleRoot is the Merkle root of all oracle observations
	OracleRoot ID `json:"oracleRoot,omitempty"`

	// ReceiptsRoot is the Merkle root of all relay receipts
	ReceiptsRoot ID `json:"receiptsRoot,omitempty"`

	// CreatedAt is when the session was created
	CreatedAt time.Time `json:"createdAt"`

	// FinalizedAt is when the session was finalized (if applicable)
	FinalizedAt time.Time `json:"finalizedAt,omitempty"`

	// Error message if session failed
	Error string `json:"error,omitempty"`
}

Session represents a private permissionless session. This is the canonical session type shared by on-chain and off-chain code.

func NewSession 

func NewSession(serviceID ID, epoch uint64, txID ID, committee []ID) *Session

NewSession creates a new session in the pending state.

type SessionState 

type SessionState uint8

SessionState represents the state of a session. 

const (
	// SessionStatePending - session created but not started
	SessionStatePending SessionState = iota
	// SessionStateRunning - session actively executing
	SessionStateRunning
	// SessionStateWaitingIO - session waiting for external I/O completion
	SessionStateWaitingIO
	// SessionStateFinalized - session completed successfully
	SessionStateFinalized
	// SessionStateFailed - session failed
	SessionStateFailed
)

func (SessionState) String 

func (s SessionState) String() string

type Step 

type Step struct {
	// StepIndex is the step number (0-indexed)
	StepIndex uint32 `json:"stepIndex"`

	// Kind indicates the step type
	Kind StepKind `json:"kind"`

	// RequestID for external I/O steps (oracle/write or oracle/read)
	RequestID ID `json:"requestId,omitempty"`

	// RetryIndex for retry attempts
	RetryIndex uint32 `json:"retryIndex"`

	// TxID that triggered this step
	TxID ID `json:"txId"`

	// InputHash is the hash of step inputs
	InputHash ID `json:"inputHash"`

	// OutputHash is the hash of step outputs (set when completed)
	OutputHash ID `json:"outputHash,omitempty"`

	// OracleCommitRoot is the Merkle root from OracleVM (for I/O steps)
	OracleCommitRoot ID `json:"oracleCommitRoot,omitempty"`

	// AttestationID is the QuantumVM attestation over the oracle commit
	AttestationID ID `json:"attestationId,omitempty"`

	// State of this step
	State StepState `json:"state"`

	// StartedAt is when the step started
	StartedAt time.Time `json:"startedAt"`

	// CompletedAt is when the step completed
	CompletedAt time.Time `json:"completedAt,omitempty"`
}

Step represents a single execution step in a session.

func NewOracleStep 

func NewOracleStep(index uint32, kind StepKind, serviceID, sessionID, txID, inputHash ID, retry uint32) *Step

NewOracleStep creates a new step that requires oracle interaction.

func NewStep 

func NewStep(index uint32, kind StepKind, txID ID, inputHash ID) *Step

NewStep creates a new step.

type StepKind 

type StepKind uint8

StepKind indicates the type of step. 

const (
	// StepKindCompute - internal computation step (no external I/O)
	StepKindCompute StepKind = iota
	// StepKindWriteExternal - external write (oracle/write)
	StepKindWriteExternal
	// StepKindReadExternal - external read (oracle/read)
	StepKindReadExternal
)

func (StepKind) RequiresOracle 

func (k StepKind) RequiresOracle() bool

RequiresOracle returns true if this step kind requires oracle interaction.

func (StepKind) String 

func (k StepKind) String() string

type StepState 

type StepState uint8

StepState represents the state of a step. 

const (
	StepStatePending   StepState = iota // Not yet started
	StepStateExecuting                  // Currently executing
	StepStateWaiting                    // Waiting for oracle/attestation
	StepStateCompleted                  // Successfully completed
	StepStateFailed                     // Failed
)

func (StepState) String 

func (s StepState) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.