session

package
v1.23.0 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: BSD-3-Clause Imports: 6 Imported by: 0

Documentation

Overview

Package session implements the session-ready architecture for private permissionless workloads. It provides: - Session state machine (pending → running → waiting_io → finalized) - Oracle request creation with deterministic request_id - Step management with QuantumVM attestation verification - Integration with OracleVM and RelayVM

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeOracleRequestID 

func ComputeOracleRequestID(serviceID ids.ID, sessionID [32]byte, step, retry uint32, txID ids.ID) [32]byte

ComputeOracleRequestID computes a deterministic oracle request ID This matches the OracleVM.ComputeRequestID format

func ComputeSessionID 

func ComputeSessionID(serviceID ids.ID, epoch uint64, txID ids.ID) [32]byte

ComputeSessionID computes a deterministic session ID

func ValidateAttestationForStep 

func ValidateAttestationForStep(
	step *Step,
	attestationDomain string,
	attestationSubjectID [32]byte,
	attestationCommitRoot [32]byte,
) error

ValidateAttestationForStep validates that an attestation is valid for a step This should be called before CompleteStep to verify the attestation

Types

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages sessions and coordinates with OracleVM and ThresholdVM

func NewManager 

func NewManager() *Manager

NewManager creates a new session manager

func (*Manager) CompleteStep 

func (m *Manager) CompleteStep(
	sessionID [32]byte,
	stepIndex uint32,
	oracleCommitRoot [32]byte,
	attestationID [32]byte,
	outputHash [32]byte,
) error

CompleteStep marks a step as complete with QuantumVM attestation verification This is called when PlatformVM receives attestation over oracle commit

func (*Manager) CreateOracleRequest 

func (m *Manager) CreateOracleRequest(sessionID [32]byte, kind StepKind, txID ids.ID, inputHash [32]byte) ([32]byte, error)

CreateOracleRequest creates an oracle request for an external I/O step Returns the deterministic request_id that should be submitted to OracleVM

func (*Manager) CreateSession 

func (m *Manager) CreateSession(serviceID ids.ID, epoch uint64, txID ids.ID, committee []ids.NodeID) (*Session, error)

CreateSession creates a new session

func (*Manager) FailSession 

func (m *Manager) FailSession(sessionID [32]byte, err string) error

FailSession marks a session as failed

func (*Manager) FinalizeSession 

func (m *Manager) FinalizeSession(
	sessionID [32]byte,
	outputHash [32]byte,
	oracleRoot [32]byte,
	receiptsRoot [32]byte,
	attestationID [32]byte,
) error

FinalizeSession marks a session as finalized This requires a QuantumVM attestation over the session completion

func (*Manager) GetPendingRequestsForSession 

func (m *Manager) GetPendingRequestsForSession(sessionID [32]byte) []*OracleRequestRef

GetPendingRequestsForSession returns all pending oracle requests for a session

func (*Manager) GetSession 

func (m *Manager) GetSession(sessionID [32]byte) (*Session, error)

GetSession retrieves a session by ID

func (*Manager) StartSession 

func (m *Manager) StartSession(sessionID [32]byte) error

StartSession transitions a session from pending to running

type OracleRequestRef 

type OracleRequestRef struct {
	RequestID [32]byte
	SessionID [32]byte
	StepIndex uint32
	Kind      StepKind
	CreatedAt time.Time
}

OracleRequestRef tracks a pending oracle request

type Session 

type Session struct {
	// SessionID is the unique identifier
	SessionID [32]byte `json:"sessionId"`

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

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

	// Committee assigned to execute this session
	Committee []ids.NodeID `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 [32]byte `json:"outputHash,omitempty"`

	// OracleRoot is the Merkle root of all oracle observations
	OracleRoot [32]byte `json:"oracleRoot,omitempty"`

	// ReceiptsRoot is the Merkle root of all relay receipts
	ReceiptsRoot [32]byte `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

type SessionState 

type SessionState string

SessionState represents the state of a session 

const (
	// StatePending - session created but not started
	StatePending SessionState = "pending"
	// StateRunning - session actively executing
	StateRunning SessionState = "running"
	// StateWaitingIO - session waiting for external I/O completion
	StateWaitingIO SessionState = "waiting_io"
	// StateFinalized - session completed successfully
	StateFinalized SessionState = "finalized"
	// StateFailed - session failed
	StateFailed SessionState = "failed"
)

type Step 

type Step struct {
	// StepIndex is the step number
	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 [32]byte `json:"requestId,omitempty"`

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

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

	// InputHash is the hash of step inputs
	InputHash [32]byte `json:"inputHash"`

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

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

	// AttestationID is the QuantumVM attestation over the oracle commit
	AttestationID [32]byte `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

type StepKind 

type StepKind uint8

StepKind indicates the type of step 

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

type StepState 

type StepState string

StepState represents the state of a step 

const (
	StepStatePending   StepState = "pending"
	StepStateExecuting StepState = "executing"
	StepStateWaiting   StepState = "waiting" // Waiting for oracle/attestation
	StepStateCompleted StepState = "completed"
	StepStateFailed    StepState = "failed"
)

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.