nodeapi

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: Nov 22, 2024 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Due to the (sometimes breaking) changes in the types used by different evolutions of oasis-core over the Cobalt, Damask, and Eden upgrades, Nexus defines its own set of internal types here.

The types that it exposes are mostly simplified versions of the types exposed by oasis-core Damask: The top-level type structs are defined in this file, and the types of their fields are almost universally directly the types exposed by oasis-core Damask. The reason is that as oasis-core evolves, Damask types are mostly able to represent all the information from Cobalt, plus some. However, there are a few exceptions where we use oasis-core Eden types instead, e.g. in the `governance` module. Over time, types should be migrated to newer versions, e.g. Eden or later, as needed.

Index

Constants

View Source 
const (
	KindInvalid         CommitteeKind = 0
	KindComputeExecutor CommitteeKind = 1
	KindStorage         CommitteeKind = 2

	// MaxCommitteeKind is a dummy value used for iterating all committee kinds.
	MaxCommitteeKind = 3

	KindInvalidName         = "invalid"
	KindComputeExecutorName = "executor"
	KindStorageName         = "storage"
)
View Source 
const EVMModuleName = "evm"

TODO: can we move this to oasis-sdk/client-sdk/go/modules/evm?

Variables

View Source 
var (
	// Known deterministic errors that may be cached
	// https://github.com/oasisprotocol/oasis-sdk/blob/runtime-sdk/v0.2.0/runtime-sdk/modules/evm/src/lib.rs#L123
	ErrSdkEVMExecutionFailed = errors.New(EVMModuleName, 2, "execution failed")
	// https://github.com/oasisprotocol/oasis-sdk/blob/runtime-sdk/v0.2.0/runtime-sdk/modules/evm/src/lib.rs#L147
	ErrSdkEVMReverted = errors.New(EVMModuleName, 8, "reverted")
)

Functions

This section is empty.

Types

type Account added in v0.3.2 

type Account staking.Account

.................... Staking ....................

type AddEscrowEvent 

type AddEscrowEvent staking.AddEscrowEvent // NOTE: NewShares field is available starting with Damask.

.................... Staking ....................

type Address 

type Address = staking.Address

type AllowanceChangeEvent 

type AllowanceChangeEvent staking.AllowanceChangeEvent

.................... Staking ....................

type BurnEvent 

type BurnEvent staking.BurnEvent

.................... Staking ....................

type Committee 

type Committee struct {
	Kind      CommitteeKind
	Members   []*scheduler.CommitteeNode
	RuntimeID coreCommon.Namespace
	ValidFor  beacon.EpochTime
}

type CommitteeKind added in v0.1.10 

type CommitteeKind uint8

Copy-pasted from Cobalt; Damask does not support the "storage" kind.

func (CommitteeKind) MarshalText added in v0.1.10 

func (k CommitteeKind) MarshalText() ([]byte, error)

MarshalText encodes a CommitteeKind into text form.

func (*CommitteeKind) UnmarshalText added in v0.1.10 

func (k *CommitteeKind) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a CommitteeKind.

type ConsensusApiLite 

type ConsensusApiLite interface {
	GetGenesisDocument(ctx context.Context, chainContext string) (*GenesisDocument, error)
	StateToGenesis(ctx context.Context, height int64) (*GenesisDocument, error)
	GetConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)
	GetBlock(ctx context.Context, height int64) (*consensus.Block, error)
	GetTransactionsWithResults(ctx context.Context, height int64) ([]TransactionWithResults, error)
	GetEpoch(ctx context.Context, height int64) (beacon.EpochTime, error)
	RegistryEvents(ctx context.Context, height int64) ([]Event, error)
	StakingEvents(ctx context.Context, height int64) ([]Event, error)
	GovernanceEvents(ctx context.Context, height int64) ([]Event, error)
	RoothashEvents(ctx context.Context, height int64) ([]Event, error)
	RoothashLastRoundResults(ctx context.Context, height int64, runtimeID coreCommon.Namespace) (*roothash.RoundResults, error)
	GetValidators(ctx context.Context, height int64) ([]Validator, error)
	GetNodes(ctx context.Context, height int64) ([]Node, error)
	GetCommittees(ctx context.Context, height int64, runtimeID coreCommon.Namespace) ([]Committee, error)
	GetProposal(ctx context.Context, height int64, proposalID uint64) (*Proposal, error)
	GetAccount(ctx context.Context, height int64, address Address) (*Account, error)
	DelegationsTo(ctx context.Context, height int64, address Address) (map[Address]*Delegation, error)
	Close() error
	// Exposes the underlying gRPC connection, if applicable. Implementations may return nil.
	// NOTE: Intended only for debugging purposes, e.g. one-off testing of gRPC methods that
	//       are not exposed via one of the above wrappers.
	GrpcConn() connections.GrpcConn
}

ConsensusApiLite provides low-level access to the consensus API of one or more (versions of) Oasis nodes.

Each method of this corresponds to a gRPC method of the node. In this sense, this is a reimplementation of convenience gRPC wrapers in oasis-core. However, this interface ONLY supports methods needed by Nexus, and the return values (events, genesis doc, ...) are converted to simplified internal types that mirror oasis-core types but contain only the fields relevant to Nexus.

Since the types are simpler and fewer, their structure is, in places, flattened compared to their counterparts in oasis-core.

type ConsensusParameters added in v0.3.2 

type ConsensusParameters struct {
	MaxBlockGas  uint64 `json:"max_block_gas"`
	MaxBlockSize uint64 `json:"max_block_size"`
}

A lightweight subset of `consensus.Parameters`.

type DebondingStartEscrowEvent 

type DebondingStartEscrowEvent staking.DebondingStartEscrowEvent

.................... Staking ....................

type Delegation added in v0.3.2 

type Delegation staking.Delegation

.................... Staking ....................

type DeterministicError added in v0.1.14 

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

DeterministicError mirrors known errors that may be returned by the node. This struct is necessary because cbor serde requires a concrete type, not just the `error` interface.

func (DeterministicError) Error added in v0.1.14 

func (e DeterministicError) Error() string

type EntityEvent 

type EntityEvent registry.EntityEvent

type Event 

type Event struct {
	Height int64
	TxHash hash.Hash

	// The body of the Event struct as it was received from oasis-core. For most
	// event types, a summary of the event (containing only nexus-relevant fields)
	// will be present in one of the fields below (StakingTransfer, StakingBurn, etc.).
	// For event types that Nexus doesn't process beyond logging, only this
	// field will be populated.
	// We convert to JSON and effectively erase the type here in order to decouple
	// oasis-core types (which vary between versions) from Nexus.
	RawBody json.RawMessage

	// Called "Kind" in oasis-core but "Type" in Nexus APIs and DBs.
	Type apiTypes.ConsensusEventType

	StakingTransfer             *TransferEvent
	StakingBurn                 *BurnEvent
	StakingAddEscrow            *AddEscrowEvent
	StakingTakeEscrow           *TakeEscrowEvent
	StakingEscrowDebondingStart *DebondingStartEscrowEvent
	StakingReclaimEscrow        *ReclaimEscrowEvent
	StakingDebondingStart       *DebondingStartEscrowEvent // Available starting in Damask.
	StakingAllowanceChange      *AllowanceChangeEvent

	RegistryRuntimeStarted   *RuntimeStartedEvent
	RegistryRuntimeSuspended *RuntimeSuspendedEvent // Available starting with Eden.
	RegistryEntity           *EntityEvent
	RegistryNode             *NodeEvent
	RegistryNodeUnfrozen     *NodeUnfrozenEvent

	RoothashMisc              *RoothashEvent
	RoothashExecutorCommitted *ExecutorCommittedEvent
	RoothashMessage           *MessageEvent // Available only in Cobalt.

	GovernanceProposalSubmitted *ProposalSubmittedEvent
	GovernanceProposalExecuted  *ProposalExecutedEvent
	GovernanceProposalFinalized *ProposalFinalizedEvent
	GovernanceVote              *VoteEvent
}

A lightweight version of "consensus/api/transactions/results".Event.

NOTE: Not all types of events are expressed as sub-structs, only those that Nexus actively inspects (as opposed to just logging them) to perform dead reckoning or similar state updates.

type ExecutorCommittedEvent 

type ExecutorCommittedEvent struct {
	// RuntimeID is RuntimeID from the roothash/api `Event` that would be
	// around this event body. We're flattening it in here to preserve it.
	RuntimeID coreCommon.Namespace
	Round     uint64
	NodeID    *signature.PublicKey // Available starting in Damask.
	Messages  []message.Message
}

type FallibleResponse added in v0.1.14 

type FallibleResponse struct {
	Ok               []byte
	DeterministicErr *DeterministicError
}

FallibleResponse stores the response to a node query. Currently only used by EvmSimulateCall. If we use this for other node queries with different return types, consider adding generics.

type GenesisDocument added in v0.3.2 

type GenesisDocument struct {
	// Height is the block height at which the document was generated.
	Height int64 `json:"height"`
	// Time is the time the genesis block was constructed.
	Time time.Time `json:"genesis_time"`
	// ChainID is the ID of the chain.
	ChainID string `json:"chain_id"`
	// BaseEpoch is the base epoch for the chain.
	BaseEpoch uint64 `json:"base_epoch"`
	// Registry is the registry genesis state.
	Registry registry.Genesis `json:"registry"`
	// RootHash is the roothash genesis state.
	Staking staking.Genesis `json:"staking"`
	// Governance is the governance genesis state.
	Governance governance.Genesis `json:"governance"`
}

GenesisDocument is a stripped-down version of `genesis.Document`.

type MessageEvent added in v0.2.10 

type MessageEvent struct {
	// RuntimeID is RuntimeID from the roothash/api `Event` that would be
	// around this event body. We're flattening it in here to preserve it.
	RuntimeID coreCommon.Namespace
	Module    string
	Code      uint32
	Index     uint32
}

type Node added in v0.1.16 

type Node node.Node

type NodeEvent 

type NodeEvent struct {
	NodeID             signature.PublicKey
	EntityID           signature.PublicKey
	Expiration         uint64 // Epoch in which the node expires.
	RuntimeIDs         []coreCommon.Namespace
	VRFPubKey          *signature.PublicKey
	TLSAddresses       []string // TCP addresses of the node's TLS-enabled gRPC endpoint.
	TLSPubKey          signature.PublicKey
	TLSNextPubKey      signature.PublicKey
	P2PID              signature.PublicKey
	P2PAddresses       []string // TCP addresses of the node's P2P endpoint.
	ConsensusID        signature.PublicKey
	ConsensusAddresses []string // TCP addresses of the node's tendermint endpoint.
	Roles              []string // enum: "compute", "key-manager", "validator", "consensus-rpc", "storage-rpc"
	SoftwareVersion    string
	IsRegistration     bool
}

type NodeUnfrozenEvent 

type NodeUnfrozenEvent registry.NodeUnfrozenEvent

type Proposal 

type Proposal governance.Proposal

type ProposalExecutedEvent 

type ProposalExecutedEvent governance.ProposalExecutedEvent

type ProposalFinalizedEvent 

type ProposalFinalizedEvent governance.ProposalFinalizedEvent

type ProposalSubmittedEvent 

type ProposalSubmittedEvent governance.ProposalSubmittedEvent

type ReclaimEscrowEvent 

type ReclaimEscrowEvent staking.ReclaimEscrowEvent

.................... Staking ....................

type RoothashEvent added in v0.2.10 

type RoothashEvent struct {
	// RuntimeID is RuntimeID from the roothash/api `Event` that would be
	// around this event body. We're flattening it in here to preserve it.
	RuntimeID coreCommon.Namespace
	Round     *uint64
}

RoothashEvent is a subset of various roothash.(...)Event subfields. Contains just the attributes we care to expose via the API in a parsed form. Used to represent events of disparate types; depending on the type of the event, not all fields are populated.

type RuntimeApiLite 

type RuntimeApiLite interface {
	GetEventsRaw(ctx context.Context, round uint64) ([]RuntimeEvent, error)
	EVMSimulateCall(ctx context.Context, round uint64, gasPrice []byte, gasLimit uint64, caller []byte, address []byte, value []byte, data []byte) (*FallibleResponse, error)
	EVMGetCode(ctx context.Context, round uint64, address []byte) ([]byte, error)
	GetBlockHeader(ctx context.Context, round uint64) (*RuntimeBlockHeader, error)
	GetTransactionsWithResults(ctx context.Context, round uint64) ([]RuntimeTransactionWithResults, error)
	GetBalances(ctx context.Context, round uint64, addr Address) (map[sdkTypes.Denomination]common.BigInt, error)
	Close() error
}

Like ConsensusApiLite, but for the runtime API.

type RuntimeBlockHeader 

type RuntimeBlockHeader struct {
	Version   uint16
	Namespace coreCommon.Namespace
	Round     uint64
	Timestamp time.Time
	// Hash of the raw header struct as received from the node API.
	// The `PreviousHash` of the next round's block should match this.
	Hash           hash.Hash
	PreviousHash   hash.Hash
	IORoot         hash.Hash
	StateRoot      hash.Hash
	MessagesHash   hash.Hash
	InMessagesHash hash.Hash // NOTE: Available starting in Damask.
}

Derived from oasis-core: roothash/api/block/header.go Expanded to include the precomputed hash of the header; we mustn't compute it on the fly because depending on the node version, this header struct might not be the exact struct returned from the node, so its real hash will differ.

type RuntimeEvent 

type RuntimeEvent sdkTypes.Event

type RuntimeStartedEvent added in v0.1.18 

type RuntimeStartedEvent struct {
	ID          coreCommon.Namespace
	EntityID    signature.PublicKey   // The Entity controlling the runtime.
	Kind        string                // enum: "compute", "keymanager"
	KeyManager  *coreCommon.Namespace // Key manager runtime ID.
	TEEHardware string                // enum: "invalid" (= no TEE), "intel-sgx"
}

RuntimeStartedEvent signifies new runtime registration. This is a stripped-down version of an unfortunately named `registry.RuntimeEvent` (in Cobalt and Damask). Post-Damask, this is replaced by registry.RuntimeStartedEvent.

type RuntimeSuspendedEvent added in v0.1.18 

type RuntimeSuspendedEvent struct {
	RuntimeID coreCommon.Namespace
}

type RuntimeTransactionWithResults 

type RuntimeTransactionWithResults sdkClient.TransactionWithResults

type TakeEscrowEvent 

type TakeEscrowEvent staking.TakeEscrowEvent

.................... Staking ....................

type TransactionWithResults 

type TransactionWithResults struct {
	Transaction consensusTransaction.SignedTransaction
	Result      TxResult
}

A lightweight subset of `consensus.TransactionsWithResults`.

type TransferEvent 

type TransferEvent staking.TransferEvent // NOTE: NewShares field is available starting with Damask.

.................... Staking ....................

type TxError 

type TxError consensusResults.Error

type TxResult 

type TxResult struct {
	Error  TxError
	Events []Event
}

func (*TxResult) IsSuccess 

func (r *TxResult) IsSuccess() bool

IsSuccess returns true if transaction execution was successful.

type UniversalRuntimeApiLite 

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

Implementation of `RuntimeApiLite` that supports all versions of the node ABI and all versions of the oasis-sdk ABI. (SDK events are CBOR-encoded according to the SDK ABI, then embedded into the node's `Event` type, which is fetched using the node ABI.)

There are very few differences in the ABIs that RuntimeApiLite cares about, so we implement support for all (= both) versions here, using trial-and-error decoding where needed, rather than creating a new RuntimeApiLite implementation for every ABI version combination.

func NewUniversalRuntimeApiLite 

func NewUniversalRuntimeApiLite(runtimeID coreCommon.Namespace, grpcConn connections.GrpcConn, sdkClient *connection.RuntimeClient) *UniversalRuntimeApiLite

func (*UniversalRuntimeApiLite) Close 

func (rc *UniversalRuntimeApiLite) Close() error

func (*UniversalRuntimeApiLite) EVMGetCode 

func (rc *UniversalRuntimeApiLite) EVMGetCode(ctx context.Context, round uint64, address []byte) ([]byte, error)

func (*UniversalRuntimeApiLite) EVMSimulateCall 

func (rc *UniversalRuntimeApiLite) EVMSimulateCall(ctx context.Context, round uint64, gasPrice []byte, gasLimit uint64, caller []byte, address []byte, value []byte, data []byte) (*FallibleResponse, error)

EVMSimulateCall simulates an evm call at a given height. If the node returns a successful response, it is stored in `FallibleResponse.Ok`. If the node returns a deterministic error, eg call_reverted, the error is stored in `FallbileResponse.deterministicErr`. If the call fails due to a nondeterministic error, the error is returned. Note: FallibleResponse should _not_ store transient errors or any error that is not a valid node response.

func (*UniversalRuntimeApiLite) GetBalances added in v0.3.0 

func (rc *UniversalRuntimeApiLite) GetBalances(ctx context.Context, round uint64, addr Address) (map[sdkTypes.Denomination]common.BigInt, error)

func (*UniversalRuntimeApiLite) GetBlockHeader 

func (rc *UniversalRuntimeApiLite) GetBlockHeader(ctx context.Context, round uint64) (*RuntimeBlockHeader, error)

func (*UniversalRuntimeApiLite) GetEventsRaw 

func (rc *UniversalRuntimeApiLite) GetEventsRaw(ctx context.Context, round uint64) ([]RuntimeEvent, error)

func (*UniversalRuntimeApiLite) GetTransactionsWithResults 

func (rc *UniversalRuntimeApiLite) GetTransactionsWithResults(ctx context.Context, round uint64) ([]RuntimeTransactionWithResults, error)

type Validator 

type Validator scheduler.Validator

type VoteEvent 

type VoteEvent struct {
	ID        uint64
	Submitter staking.Address
	Vote      string // enum: "yes", "no", "abstain"
}

Source Files

View all Source files

Directories

Path Synopsis

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.