Help us shape the future of Go! Take the 2026 Go Developer Survey

oraclevm

package
v1.24.29 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: BSD-3-Clause Imports: 22 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 FeedRoundKey added in v1.24.29 

type FeedRoundKey struct {
	FeedID ids.ID
	Round  uint64
}

FeedRoundKey is the conflict key for the Oracle VM: (feedID, round/epoch). Same feed+round conflicts; different feeds commute.

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 OracleVertex added in v1.24.29 

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

OracleVertex represents a DAG vertex in the Oracle chain.

func (*OracleVertex) Accept added in v1.24.29 

func (v *OracleVertex) Accept(ctx context.Context) error

func (*OracleVertex) Bytes added in v1.24.29 

func (v *OracleVertex) Bytes() []byte

func (*OracleVertex) Conflicts added in v1.24.29 

func (v *OracleVertex) Conflicts(other *OracleVertex) bool

Conflicts returns true if this vertex and other share any (feedID, round) pair.

func (*OracleVertex) ConflictsVertex added in v1.24.29 

func (v *OracleVertex) ConflictsVertex(other vertex.Vertex) bool

ConflictsVertex performs the same check against the vertex.Vertex interface.

func (*OracleVertex) Epoch added in v1.24.29 

func (v *OracleVertex) Epoch() uint32

func (*OracleVertex) Height added in v1.24.29 

func (v *OracleVertex) Height() uint64

func (*OracleVertex) ID added in v1.24.29 

func (v *OracleVertex) ID() ids.ID

func (*OracleVertex) Parents added in v1.24.29 

func (v *OracleVertex) Parents() []ids.ID

func (*OracleVertex) Reject added in v1.24.29 

func (v *OracleVertex) Reject(ctx context.Context) error

func (*OracleVertex) Status added in v1.24.29 

func (v *OracleVertex) Status() choices.Status

func (*OracleVertex) Txs added in v1.24.29 

func (v *OracleVertex) Txs() []ids.ID

func (*OracleVertex) Verify added in v1.24.29 

func (v *OracleVertex) Verify(ctx context.Context) error

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) BuildVertex added in v1.24.29 

func (vm *VM) BuildVertex(ctx context.Context) (vertex.Vertex, error)

BuildVertex creates a vertex from pending observations and aggregations.

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) ParseVertex added in v1.24.29 

func (vm *VM) ParseVertex(ctx context.Context, b []byte) (vertex.Vertex, error)

ParseVertex deserializes a vertex from bytes.

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.