nodeapi

Documentation

Index

• type AddEscrowEvent
• type Address
• type AllowanceChangeEvent
• type BurnEvent
• type Committee
• type ConsensusApiLite
• type DebondingStartEscrowEvent
• type EntityEvent
• type Event
• type ExecutorCommittedEvent
• type NodeEvent
• type NodeUnfrozenEvent
• type Proposal
• type ProposalExecutedEvent
• type ProposalFinalizedEvent
• type ProposalSubmittedEvent
• type ReclaimEscrowEvent
• type RuntimeApiLite
• type RuntimeBlockHeader
• type RuntimeEvent
• type RuntimeRegisteredEvent
• type RuntimeTransactionWithResults
• type TakeEscrowEvent
• type TransactionWithResults
• type TransferEvent
• type TxError
• type TxResult
  • func (r *TxResult) IsSuccess() bool
• type UniversalRuntimeApiLite
  • func NewUniversalRuntimeApiLite(runtimeID coreCommon.Namespace, grpcConn *grpc.ClientConn, ...) *UniversalRuntimeApiLite
  • func (rc *UniversalRuntimeApiLite) Close() error
  • func (rc *UniversalRuntimeApiLite) EVMGetCode(ctx context.Context, round uint64, address []byte) ([]byte, error)
  • func (rc *UniversalRuntimeApiLite) EVMSimulateCall(ctx context.Context, round uint64, gasPrice []byte, gasLimit uint64, ...) ([]byte, error)
  • func (rc *UniversalRuntimeApiLite) GetBlockHeader(ctx context.Context, round uint64) (*RuntimeBlockHeader, error)
  • func (rc *UniversalRuntimeApiLite) GetEventsRaw(ctx context.Context, round uint64) ([]RuntimeEvent, error)
  • func (rc *UniversalRuntimeApiLite) GetNativeBalance(ctx context.Context, round uint64, addr Address) (*common.BigInt, error)
  • func (rc *UniversalRuntimeApiLite) GetTransactionsWithResults(ctx context.Context, round uint64) ([]RuntimeTransactionWithResults, error)
• type Validator
• type VoteEvent

Types

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 scheduler.Committee

type ConsensusApiLite

type ConsensusApiLite interface {
	// TODO: Introduce internal, stripped-down version of `genesis.Document`.
	GetGenesisDocument(ctx context.Context, chainContext string) (*genesis.Document, error)
	StateToGenesis(ctx context.Context, height int64) (*genesis.Document, 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)
	GetValidators(ctx context.Context, height int64) ([]Validator, error)
	GetCommittees(ctx context.Context, height int64, runtimeID coreCommon.Namespace) ([]Committee, error)
	GetProposal(ctx context.Context, height int64, proposalID uint64) (*Proposal, error)
	Close() error
}

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 DebondingStartEscrowEvent

type DebondingStartEscrowEvent staking.DebondingStartEscrowEvent

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

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

	RegistryRuntimeRegistered *RuntimeRegisteredEvent
	RegistryEntity            *EntityEvent
	RegistryNode              *NodeEvent
	RegistryNodeUnfrozen      *NodeUnfrozenEvent

	RoothashExecutorCommitted *ExecutorCommittedEvent

	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 {
	NodeID *signature.PublicKey // Available starting in Damask.
}

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 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) ([]byte, 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)
	GetNativeBalance(ctx context.Context, round uint64, addr Address) (*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 RuntimeRegisteredEvent

type RuntimeRegisteredEvent 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"
}

RuntimeRegisteredEvent 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 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 *grpc.ClientConn, 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) ([]byte, 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) GetNativeBalance

func (rc *UniversalRuntimeApiLite) GetNativeBalance(ctx context.Context, round uint64, addr Address) (*common.BigInt, 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"
}