cre

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2026 License: MIT Imports: 15 Imported by: 7

Documentation

Index

Constants

View Source 
const (
	DefaultMaxResponseSizeBytes = 5 * 1024 * 1024 // 5 MB
	ResponseBufferTooSmall      = "response buffer too small"
	// proto encoder outputs a map with these keys so that user payload can be easily extracted
	ReportMetadataHeaderLength = 109
)

Variables

This section is empty.

Functions

func ConsensusCommonPrefixAggregation 

func ConsensusCommonPrefixAggregation[T any]() func() (ConsensusAggregation[[]T], error)

ConsensusCommonPrefixAggregation uses the longest common prefix across nodes. The aggregation tolerates up to F faulty nodes returning errors or different values for each element.

func ConsensusCommonSuffixAggregation 

func ConsensusCommonSuffixAggregation[T any]() func() (ConsensusAggregation[[]T], error)

ConsensusCommonSuffixAggregation uses the longest common suffix across nodes. The aggregation tolerates up to F faulty nodes returning errors or different values for each element.

func DonModeCallInNodeMode 

func DonModeCallInNodeMode() error

func NodeModeCallInDonMode 

func NodeModeCallInDonMode() error

func ParseJSON 

func ParseJSON[T any](bytes []byte) (*T, error)

ParseJSON parses a JSON byte slice into a struct of type *T.

Types

type ConsensusAggregation 

type ConsensusAggregation[T any] interface {
	// Descriptor is meant to be used by the Runtime
	Descriptor() *sdk.ConsensusDescriptor

	// Default returns the default value or nil when there is no default value
	Default() *T

	// Err is meant to be used by the Runtime
	Err() error

	// WithDefault returns a new ConsensusAggregation with the given default value
	// If consensus cannot be reached, the default value will be used if it is not nil instead of returning an error.
	WithDefault(t T) ConsensusAggregation[T]
}

ConsensusAggregation is an interface that informs consensus how to aggregate values. Workflow author do not need to implement this interface directly; instead the helper functions below can be used to create instances of this interface: - ConsensusMedianAggregation - ConsensusIdenticalAggregation - ConsensusCommonPrefixAggregation - ConsensusCommonSuffixAggregation - ConsensusAggregationFromTags By using this interface with capability SDKs or RunInNodeMode, you are assured that all aggregated values are Byzantine fault-tolerant.

func ConsensusAggregationFromTags 

func ConsensusAggregationFromTags[T any]() ConsensusAggregation[T]

ConsensusAggregationFromTags works with structs using the `consensus_aggregation` tag to define how to aggregate each field. It supports the following tags: - `median`: for numeric types, it will take the median in the same manner as `ConsensusMedianAggregation` does for numeric types, but for a field on a struct. - `identical`: for primitive types, it will check if all values are identical in the same manner as `ConsensusIdenticalAggregation` does for primitive types, but for a field on a struct. - `common_prefix`: for slices or arrays of primitive types, it will take the longest common prefix in the same manner as `ConsensusCommonPrefixAggregation` does for slices or arrays. - `common_suffix`: for slices or arrays of primitive types, it will take the longest common suffix in the same manner as `ConsensusCommonSuffixAggregation` does for slices or arrays. - `nested`: for nested structs, it will recursively parse the struct and aggregate its fields using the same rules as above. - `ignore`: to ignore a field in the struct. If a field is not tagged or is not a valid type for the tag, it will return an error.

func ConsensusIdenticalAggregation 

func ConsensusIdenticalAggregation[T any]() ConsensusAggregation[T]

ConsensusIdenticalAggregation is used when responses from each node are expected to be identical. The aggregation tolerates up to F faulty nodes returning errors or different values.

func ConsensusMedianAggregation 

func ConsensusMedianAggregation[T NumericType]() ConsensusAggregation[T]

ConsensusMedianAggregation takes a median of all node observations. The median is Byzantine fault-tolerant and is guaranteed to be within the range of valid observations.

type ExecutionHandler 

type ExecutionHandler[C, R any] interface {
	CapabilityID() string
	Method() string
	TriggerCfg() *anypb.Any
	Callback() func(config C, runtime R, payload *anypb.Any) (any, error)
}

ExecutionHandler defines a coupling of a Trigger and a callback function to be used by the SDK. The methods on the handler are meant to be used internally by the Runtime.

func Handler 

func Handler[C any, M proto.Message, T any, O any](trigger Trigger[M, T], callback func(config C, runtime Runtime, payload T) (O, error)) ExecutionHandler[C, Runtime]

Handler creates a coupling of a Trigger and a callback function to be used by the SDK. The coupling ensures that when the Trigger is invoked, the callback function is called with the appropriate parameters.

type NodeRuntime 

type NodeRuntime interface {
	RuntimeBase

	// IsNodeRuntime is a placeholder to differentiate NodeRuntime.
	IsNodeRuntime()
}

NodeRuntime provides access to Node capabilities It is not thread safe and must not be used concurrently.

type NumericType 

type NumericType interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64 | ~*big.Int | decimal.Decimal | time.Time
}

NumericType represents types that can be used numerically for consensus aggregation. It includes all go primitive numeric types, big.Int, decimal.Decimal, and time.Time.

type Primitive 

type Primitive interface {
	NumericType | ~string | ~bool
}

Primitive represents any `NumericType`, string, or bool.

type Promise 

type Promise[T any] interface {
	// Await blocks until the computation is complete and returns the result or an error.
	Await() (T, error)
}

Promise allows for asynchronous computation, where the result can be awaited later.

func NewBasicPromise 

func NewBasicPromise[T any](await func() (T, error)) Promise[T]

NewBasicPromise is meant to be used by Runtime implementations. It creates a new Promise that executes the provided function once awaited. This provides asynchronous callbacks in single-threaded guest environments as the host can execute while the guest continues to run.

func PromiseFromResult 

func PromiseFromResult[T any](result T, err error) Promise[T]

PromiseFromResult creates a Promise that immediately returns the provided result and error.

func RunInNodeMode 

func RunInNodeMode[C, T any](
	config C,
	runtime Runtime,
	fn func(config C, nodeRuntime NodeRuntime) (T, error),
	ca ConsensusAggregation[T],
) Promise[T]

func Then 

func Then[I, O any](p Promise[I], fn func(I) (O, error)) Promise[O]

Then allows chaining of promises, upon success, the result of the first promise is passed to the provided function. Note that the callback in `fn` will not be executed until Await is called on the returned Promise.

func ThenPromise 

func ThenPromise[I, O any](p Promise[I], fn func(I) Promise[O]) Promise[O]

ThenPromise allows chaining of promises, similar to Then, but the provided function returns a Promise. This is useful when the next step in the chain is also asynchronous.

type Report added in v0.4.0 

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

Report contains a signed report from the CRE workflow DON. Reports contain metadata, including the workflow ID, workflow owner, and execution ID, alongside the encoded payload, and signatures from F+1 nodes in the workflow DON. They can be used to prove that data came from a specific workflow, or author. Blockchains integrated with the CRE have forwarder contracts that can verify a report's integrity. Chainlink will provide helpers to verify reports offline in at a later date.

func X_GeneratedCodeOnly_WrapReport added in v0.4.0 

func X_GeneratedCodeOnly_WrapReport(report *sdk.ReportResponse) (*Report, error)

X_GeneratedCodeOnly_WrapReport is meant to be used by the code generator only.

func (*Report) X_GeneratedCodeOnly_Unwrap added in v0.4.0 

func (r *Report) X_GeneratedCodeOnly_Unwrap() *sdk.ReportResponse

X_GeneratedCodeOnly_Unwrap is meant to be used by the code generator only.

type ReportRequest added in v0.6.0 

type ReportRequest = sdk.ReportRequest

type Runner 

type Runner[C any] interface {
	// Run creates the workflow and starts it.
	// Upon registration of a workflow, a run is used to register to `Trigger`s.
	// Upon receiving a trigger, the appropriate handler's callback is invoked.
	Run(initFn func(config C, logger *slog.Logger, secretsProvider SecretsProvider) (Workflow[C], error))
}

Runner is the entry point to running a CRE workflow.

type Runtime 

type Runtime interface {
	RuntimeBase

	// RunInNodeMode is meant to be used by the helper method RunInNodeMode
	RunInNodeMode(fn func(nodeRuntime NodeRuntime) *sdk.SimpleConsensusInputs) Promise[values.Value]

	// GenerateReport is used to generate a report for a given ReportRequest.
	GenerateReport(*ReportRequest) Promise[*Report]
	SecretsProvider
}

Runtime provides access to DON capabilities and allows NodeRuntime use with consensus. It is not thread safe and must not be used concurrently.

type RuntimeBase 

type RuntimeBase interface {
	// CallCapability is meant to be called by generated code
	CallCapability(request *sdk.CapabilityRequest) Promise[*sdk.CapabilityResponse]

	// Rand provides access to a random number generator for the mode the runtime operates in.
	// Attempting to use the returned generator outside the correct scope will panic.
	Rand() (*rand.Rand, error)

	// Now provides the current time, with the mechanism for doing so based on the current mode.
	Now() time.Time

	// Logger provides a logger that can be used to log messages.
	Logger() *slog.Logger
}

RuntimeBase provides the basic functionality of a CRE runtime. It is not thread safe and must not be used concurrently.

type Secret added in v0.5.0 

type Secret = sdk.Secret

type SecretRequest added in v0.5.0 

type SecretRequest = sdk.SecretRequest

type SecretsProvider 

type SecretsProvider interface {
	// GetSecret retrieves a secret by its request.
	GetSecret(*SecretRequest) Promise[*Secret]
}

SecretsProvider provides access to secrets.

type Trigger 

type Trigger[M proto.Message, T any] interface {
	Adapt(m M) (T, error)
	// contains filtered or unexported methods
}

Trigger is a capability that initiates a workflow execution. This interface is meant for internal use by the Runner To obtain an implementation, use the SDKs for the capability you want to utilize.

type Workflow 

type Workflow[C any] []ExecutionHandler[C, Runtime]

Workflow is a sequence of ExecutionHandlers that define the logic of a CRE application.

Source Files

View all Source files

Directories

Path Synopsis
registry

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.