oraclevm

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: 19 Imported by: 0

Documentation

Overview

Package oraclevm implements the Oracle Virtual Machine (O-Chain) for the Lux network. OracleVM provides decentralized oracle services for external data feeds.

Key features:

  • Observation: operators fetch data from external sources
  • Commit: signed observations submitted to chain
  • Aggregate: compute canonical output (median/TWAP/bounded deviation)
  • ZK aggregation proofs for correctness
  • Threshold attestation for compatibility fallback

Index

Constants

This section is empty.

Variables

View Source 
var (
	Version = &version.Semantic{
		Major: 1,
		Minor: 0,
		Patch: 0,
	}

	ErrNotInitialized     = errors.New("vm not initialized")
	ErrFeedNotFound       = errors.New("feed not found")
	ErrInvalidObservation = errors.New("invalid observation")
	ErrStaleObservation   = errors.New("stale observation")
	ErrInvalidAggregation = errors.New("invalid aggregation")
)
View Source 
var VMID = ids.ID{'o', 'r', 'a', 'c', 'l', 'e', 'v', 'm'}

VMID is the unique identifier for OracleVM (O-Chain)

Functions

func ComputeRequestID added in v1.23.0 

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

ComputeRequestID computes the deterministic request ID

func NewService 

func NewService(vm *VM) http.Handler

NewService creates a new OracleVM service

Types

type AggregatedValue 

type AggregatedValue struct {
	FeedID       ids.ID    `json:"feedId"`
	Epoch        uint64    `json:"epoch"`
	Value        []byte    `json:"value"`
	Timestamp    time.Time `json:"timestamp"`
	Observations int       `json:"observationCount"`
	AggProof     []byte    `json:"aggProof,omitempty"`
	QuorumCert   []byte    `json:"quorumCert,omitempty"`
}

AggregatedValue represents the canonical output for a feed

type Block 

type Block struct {
	ID_        ids.ID    `json:"id"`
	ParentID_  ids.ID    `json:"parentID"`
	Height_    uint64    `json:"height"`
	Timestamp_ time.Time `json:"timestamp"`

	// Oracle-specific data
	Observations []*Observation                 `json:"observations,omitempty"`
	Aggregations []*AggregatedValue             `json:"aggregations,omitempty"`
	FeedUpdates  []*Feed                        `json:"feedUpdates,omitempty"`
	Attestations []*artifacts.OracleAttestation `json:"attestations,omitempty"`
	// contains filtered or unexported fields
}

Block represents an OracleVM block

func (*Block) Accept 

func (blk *Block) Accept(ctx context.Context) error

func (*Block) Bytes 

func (blk *Block) Bytes() []byte

func (*Block) Height 

func (blk *Block) Height() uint64

func (*Block) ID 

func (blk *Block) ID() ids.ID

func (*Block) Parent 

func (blk *Block) Parent() ids.ID

func (*Block) ParentID 

func (blk *Block) ParentID() ids.ID

func (*Block) Reject 

func (blk *Block) Reject(ctx context.Context) error

func (*Block) Status 

func (blk *Block) Status() uint8

func (*Block) Timestamp 

func (blk *Block) Timestamp() time.Time

func (*Block) Verify 

func (blk *Block) Verify(ctx context.Context) error

type Config 

type Config struct {
	// Feed settings
	MaxFeedsPerBlock  int    `json:"maxFeedsPerBlock"`
	ObservationWindow string `json:"observationWindow"`
	MinObservers      int    `json:"minObservers"`

	// Aggregation settings
	AggregationMethod  string `json:"aggregationMethod"`  // median, twap, weighted
	DeviationThreshold uint64 `json:"deviationThreshold"` // basis points

	// ZK settings
	EnableZKAggregation bool   `json:"enableZkAggregation"`
	ZKProofSystem       string `json:"zkProofSystem"` // groth16, plonk

	// Attestation settings
	RequireQuorumCert bool `json:"requireQuorumCert"`
	QuorumThreshold   int  `json:"quorumThreshold"`
}

Config contains OracleVM configuration

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns default OracleVM configuration

type Factory 

type Factory struct{}

Factory creates new OracleVM instances

func (*Factory) New 

func (f *Factory) New(logger log.Logger) (interface{}, error)

New returns a new instance of the OracleVM

type Feed 

type Feed struct {
	ID          ids.ID            `json:"id"`
	Name        string            `json:"name"`
	Description string            `json:"description"`
	Sources     []string          `json:"sources"`
	UpdateFreq  time.Duration     `json:"updateFreq"`
	PolicyHash  [32]byte          `json:"policyHash"`
	Operators   []ids.NodeID      `json:"operators"`
	CreatedAt   time.Time         `json:"createdAt"`
	Status      string            `json:"status"`
	Metadata    map[string]string `json:"metadata"`
}

Feed represents an oracle data feed

type Genesis 

type Genesis struct {
	Version      int     `json:"version"`
	Message      string  `json:"message"`
	Timestamp    int64   `json:"timestamp"`
	InitialFeeds []*Feed `json:"initialFeeds,omitempty"`
}

Genesis represents the genesis state

type GetAttestationArgs 

type GetAttestationArgs struct {
	FeedID string `json:"feedId"`
	Epoch  uint64 `json:"epoch"`
}

GetAttestationArgs are arguments for GetAttestation

type GetAttestationReply 

type GetAttestationReply struct {
	Attestation []byte `json:"attestation"`
}

GetAttestationReply is the reply for GetAttestation

type GetFeedArgs 

type GetFeedArgs struct {
	FeedID string `json:"feedId"`
}

GetFeedArgs are arguments for GetFeed

type GetFeedReply 

type GetFeedReply struct {
	Feed *Feed `json:"feed"`
}

GetFeedReply is the reply for GetFeed

type GetValueArgs 

type GetValueArgs struct {
	FeedID string `json:"feedId"`
}

GetValueArgs are arguments for GetValue

type GetValueReply 

type GetValueReply struct {
	Value *AggregatedValue `json:"value"`
}

GetValueReply is the reply for GetValue

type HealthArgs 

type HealthArgs struct{}

HealthArgs are arguments for Health

type HealthReply 

type HealthReply struct {
	Healthy bool `json:"healthy"`
	Feeds   int  `json:"feeds"`
}

HealthReply is the reply for Health

type Observation 

type Observation struct {
	FeedID     ids.ID     `json:"feedId"`
	Value      []byte     `json:"value"`
	Timestamp  time.Time  `json:"timestamp"`
	SourceMeta [32]byte   `json:"sourceMetaHash"`
	OperatorID ids.NodeID `json:"operatorId"`
	Signature  []byte     `json:"signature"`
}

Observation represents a signed observation from an operator

type OracleCommit added in v1.23.0 

type OracleCommit struct {
	RequestID   [32]byte    `json:"requestId"`
	Kind        RequestKind `json:"kind"`
	Root        [32]byte    `json:"root"` // MerkleRoot(records)
	RecordCount uint32      `json:"recordCount"`
	Window      struct {
		Start uint64 `json:"start"`
		End   uint64 `json:"end"`
	} `json:"window"`
	CommittedAt time.Time `json:"committedAt"`
}

OracleCommit represents a Merkle root commitment for a request

type OracleRecord added in v1.23.0 

type OracleRecord struct {
	RequestID   [32]byte   `json:"requestId"`
	Executor    ids.NodeID `json:"executor"`
	Timestamp   uint64     `json:"timestamp"`
	Endpoint    string     `json:"endpoint"`    // Or compact endpoint ID
	BodyHash    [32]byte   `json:"bodyHash"`    // Hash of request/response body
	ResultCode  uint32     `json:"resultCode"`  // HTTP status or custom code
	ExternalRef []byte     `json:"externalRef"` // External system reference (txid, etc.)
	Signature   []byte     `json:"signature"`   // Executor's signature over record
}

OracleRecord represents a single execution record from an executor

type OracleRequest added in v1.23.0 

type OracleRequest struct {
	RequestID      [32]byte      `json:"requestId"` // Deterministic: H(service_id || session_id || step || retry || txid)
	ServiceID      ids.ID        `json:"serviceId"`
	SessionID      ids.ID        `json:"sessionId"`
	Step           uint32        `json:"step"`
	Retry          uint32        `json:"retry"`
	TxID           ids.ID        `json:"txId"`           // Originating PlatformVM tx
	Kind           RequestKind   `json:"kind"`           // WRITE or READ
	Target         []byte        `json:"target"`         // Opaque target spec (url template id, chain id, etc.)
	PayloadHash    [32]byte      `json:"payloadHash"`    // For WRITE: hash of payload to send
	SchemaHash     [32]byte      `json:"schemaHash"`     // For READ: expected response schema
	DeadlineHeight uint64        `json:"deadlineHeight"` // Block height deadline
	Executors      []ids.NodeID  `json:"executors"`      // Assigned executor committee
	CreatedAt      time.Time     `json:"createdAt"`
	Status         RequestStatus `json:"status"`
}

OracleRequest represents a deterministic request from PlatformVM request_id = H(service_id || session_id || step || retry_index || txid)

type RegisterFeedArgs 

type RegisterFeedArgs struct {
	Name        string            `json:"name"`
	Description string            `json:"description"`
	Sources     []string          `json:"sources"`
	UpdateFreq  string            `json:"updateFreq"`
	Operators   []string          `json:"operators"`
	Metadata    map[string]string `json:"metadata"`
}

RegisterFeedArgs are arguments for RegisterFeed

type RegisterFeedReply 

type RegisterFeedReply struct {
	FeedID string `json:"feedId"`
}

RegisterFeedReply is the reply for RegisterFeed

type RequestKind added in v1.23.0 

type RequestKind uint8

RequestKind indicates whether this is a write or read request 

const (
	RequestKindWrite RequestKind = iota
	RequestKindRead
)

type RequestStatus added in v1.23.0 

type RequestStatus uint8

RequestStatus tracks the lifecycle of an oracle request 

const (
	RequestStatusPending RequestStatus = iota
	RequestStatusExecuting
	RequestStatusCommitted
	RequestStatusExpired
	RequestStatusFailed
)

type Service 

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

Service provides RPC access to the OracleVM

func (*Service) GetAttestation 

func (s *Service) GetAttestation(r *http.Request, args *GetAttestationArgs, reply *GetAttestationReply) error

GetAttestation returns an oracle attestation

func (*Service) GetFeed 

func (s *Service) GetFeed(r *http.Request, args *GetFeedArgs, reply *GetFeedReply) error

GetFeed returns a feed by ID

func (*Service) GetValue 

func (s *Service) GetValue(r *http.Request, args *GetValueArgs, reply *GetValueReply) error

GetValue returns the latest value for a feed

func (*Service) Health 

func (s *Service) Health(r *http.Request, args *HealthArgs, reply *HealthReply) error

Health returns health status

func (*Service) RegisterFeed 

func (s *Service) RegisterFeed(r *http.Request, args *RegisterFeedArgs, reply *RegisterFeedReply) error

RegisterFeed registers a new oracle feed

func (*Service) SubmitObservation 

func (s *Service) SubmitObservation(r *http.Request, args *SubmitObservationArgs, reply *SubmitObservationReply) error

SubmitObservation submits an observation

type SubmitObservationArgs 

type SubmitObservationArgs struct {
	FeedID    string `json:"feedId"`
	Value     []byte `json:"value"`
	Signature []byte `json:"signature"`
}

SubmitObservationArgs are arguments for SubmitObservation

type SubmitObservationReply 

type SubmitObservationReply struct {
	Success bool `json:"success"`
}

SubmitObservationReply is the reply for SubmitObservation

type VM 

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

VM implements the Oracle Virtual Machine

func (*VM) BuildBlock 

func (vm *VM) BuildBlock(ctx context.Context) (chain.Block, error)

func (*VM) CommitRecords added in v1.23.0 

func (vm *VM) CommitRecords(requestID [32]byte) (*OracleCommit, error)

CommitRecords creates a Merkle root commitment for a request's records

func (*VM) Connected 

func (vm *VM) Connected(ctx context.Context, nodeID ids.NodeID, nodeVersion *chain.VersionInfo) error

Connected notifies the VM about connected nodes

func (*VM) CreateAttestation 

func (vm *VM) CreateAttestation(feedID ids.ID, epoch uint64) (*artifacts.OracleAttestation, error)

CreateAttestation creates an OracleAttestation artifact

func (*VM) CreateHandlers 

func (vm *VM) CreateHandlers(ctx context.Context) (map[string]http.Handler, error)

CreateHandlers returns HTTP handlers

func (*VM) Disconnected 

func (vm *VM) Disconnected(ctx context.Context, nodeID ids.NodeID) error

Disconnected notifies the VM about disconnected nodes

func (*VM) GenerateInclusionProof added in v1.23.0 

func (vm *VM) GenerateInclusionProof(requestID [32]byte, recordIndex int) ([][]byte, error)

GenerateInclusionProof generates a Merkle inclusion proof for a record

func (*VM) GetBlock 

func (vm *VM) GetBlock(ctx context.Context, id ids.ID) (chain.Block, error)

func (*VM) GetBlockIDAtHeight 

func (vm *VM) GetBlockIDAtHeight(ctx context.Context, height uint64) (ids.ID, error)

func (*VM) GetCommit added in v1.23.0 

func (vm *VM) GetCommit(requestID [32]byte) (*OracleCommit, error)

GetCommit returns a commit by request ID

func (*VM) GetFeed 

func (vm *VM) GetFeed(feedID ids.ID) (*Feed, error)

GetFeed returns a feed by ID

func (*VM) GetLatestValue 

func (vm *VM) GetLatestValue(feedID ids.ID) (*AggregatedValue, error)

GetLatestValue returns the latest aggregated value for a feed

func (*VM) GetRequest added in v1.23.0 

func (vm *VM) GetRequest(requestID [32]byte) (*OracleRequest, error)

GetRequest returns a request by ID

func (*VM) HealthCheck 

func (vm *VM) HealthCheck(ctx context.Context) (*chain.HealthResult, error)

func (*VM) Initialize 

func (vm *VM) Initialize(ctx context.Context, init vmcore.Init) error

Initialize initializes the VM with the unified Init struct

func (*VM) LastAccepted 

func (vm *VM) LastAccepted(ctx context.Context) (ids.ID, error)

func (*VM) NewHTTPHandler 

func (vm *VM) NewHTTPHandler(ctx context.Context) (http.Handler, error)

func (*VM) ParseBlock 

func (vm *VM) ParseBlock(ctx context.Context, bytes []byte) (chain.Block, error)

func (*VM) RegisterFeed 

func (vm *VM) RegisterFeed(feed *Feed) error

RegisterFeed registers a new oracle feed

func (*VM) RegisterRequest added in v1.23.0 

func (vm *VM) RegisterRequest(req *OracleRequest) error

RegisterRequest registers a new oracle request from PlatformVM The request_id must be deterministic and verifiable

func (*VM) SetPreference 

func (vm *VM) SetPreference(ctx context.Context, id ids.ID) error

func (*VM) SetState 

func (vm *VM) SetState(ctx context.Context, state uint32) error

func (*VM) Shutdown 

func (vm *VM) Shutdown(ctx context.Context) error

Shutdown shuts down the VM

func (*VM) SubmitObservation 

func (vm *VM) SubmitObservation(obs *Observation) error

SubmitObservation submits an observation for a feed

func (*VM) SubmitRecord added in v1.23.0 

func (vm *VM) SubmitRecord(record *OracleRecord) error

SubmitRecord submits an execution record from an assigned executor Only assigned executors can submit records for a request

func (*VM) Version 

func (vm *VM) Version(ctx context.Context) (string, error)

func (*VM) WaitForEvent 

func (vm *VM) WaitForEvent(ctx context.Context) (vmcore.Message, error)

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.