Documentation
¶
Overview ¶
Package workflows provides common utilities for CRE event watcher workflow development.
Key features:
- Configuration parsing (YAML/JSON workflow configs)
- Event processing (decode EVM logs, build consensus reports)
- Workflow initialization (wire up EVM log triggers with handlers)
- Testing utilities (mock runtime for unit testing)
Usage:
import workflows "github.com/smartcontractkit/crec-workflow-utils"
func OnLog(cfg *workflows.Config, rt cre.Runtime, payload *evm.Log) (string, error) {
// Decode and process event...
}
Index ¶
- Variables
- func BuildEVMEventFromLog(rt cre.Runtime, cfg *Config, payload *evm.Log) (*models.EVMEvent, error)
- func BuildVerifiableEventForEVMEvent(cfg *Config, ev *models.EVMEvent, service *string, name string, ...) (*models.VerifiableEvent, error)
- func CheckResponse(resp *httpcap.Response) (*httpcap.Response, error)
- func ComputeEventHash(encoded string) (common.Hash, error)
- func CursorFromPB(blockNumber *pb.BigInt, logIndex uint64, txHash string) string
- func DecodeEventParams(abiJSON, eventName string, log *evm.Log) (map[string]any, error)
- func DecodeVerifiableEvent(encoded string) (*models.VerifiableEvent, error)
- func EncodeVerifiableEvent(ve *models.VerifiableEvent) (string, error)
- func EnsureChainSelector(cfg *Config, fallback string) string
- func GetBlockTimestamp(rt cre.Runtime, chainSelector string, blockNumber *pb.BigInt) uint64
- func GetContractABI(cfg *Config, contractName string) (string, error)
- func GetCurrencyCode(currencyId uint8) string
- func GetEventNameFromLog(cfg *Config, payload *evm.Log, abiJSON string) (string, error)
- func GetEventSignature(cfg *Config, eventName string) string
- func InitEventListenerWorkflow(cfg *Config, handler LogHandler) (cre.Workflow[*Config], error)
- func MustEvent(abiJSON, eventName string) gethAbi.Event
- func NewEVMLogFilter(contractAddr string, eventSigHashes [][]byte) *evm.FilterLogTriggerRequest
- func PBToUint64(b *pb.BigInt) uint64
- func ParseChainSelector(chainSelectorStr *string) (*uint64, error)
- func PrepareTestingRuntime(t *testing.T) *testutils.TestRuntime
- func Retry[T any](logger *slog.Logger, name string, fn func() (T, error)) (T, error)
- func SanitiseJSON(v any) any
- func SignAndPostVerifiableEvent(cfg *Config, rt cre.Runtime, ve *models.VerifiableEvent) (string, error)
- func StopRetry(err error) error
- func TxHashFromLog(l *evm.Log) string
- type Config
- type ContractDef
- type ContractReaderConfig
- type DetectEventTriggerConfig
- type Fixed2
- type LogHandler
- type OffChainReferenceData
- type OffChainReferenceDataSource
- type OnChainReferenceData
- type OnChainReferenceDataSource
- type PaymentCallback
- type PaymentRequest
- type RawMessageType
- type ReferenceData
- type TypeAndValue
Constants ¶
This section is empty.
Variables ¶
var ( InitialRetryDelay = 5 * time.Second Attempts = 3 )
var CurrencyCodes = map[uint8]string{}/* 179 elements not displayed */
var ErrNilVerifiableEvent = errors.New("verifiable event cannot be nil")
Functions ¶
func BuildEVMEventFromLog ¶
BuildEVMEventFromLog constructs an EVMEvent from the given evm.Log payload, decoding parameters using the contract ABI specified in cfg.
func BuildVerifiableEventForEVMEvent ¶
func BuildVerifiableEventForEVMEvent( cfg *Config, ev *models.EVMEvent, service *string, name string, data *map[string]interface{}, ) (*models.VerifiableEvent, error)
BuildVerifiableEventForEVMEvent constructs a VerifiableEvent for the given EVMEvent, with the specified service (optional, can be nil for workflows not scoped to a service), name, and additional data.
func CheckResponse ¶
CheckResponse validates the httpcap response and returns it unchanged if acceptable.
func CursorFromPB ¶
CursorFromPB builds a "block-logIndex-txHash" cursor string from pb.BigInt block-number, a log-index, and an optional tx-hash. If txHash is empty, "0x" is used to match existing consumers.
func DecodeEventParams ¶
DecodeEventParams decodes an EVM log's topics/data into a named parameter map, using the provided ABI JSON and event-name. It returns parameters with snake_case keys and values sanitised via SanitiseJSON. It always returns a params map (possibly empty) even when an error occurs parsing ABI or event.
func DecodeVerifiableEvent ¶
func DecodeVerifiableEvent(encoded string) (*models.VerifiableEvent, error)
func EncodeVerifiableEvent ¶
func EncodeVerifiableEvent(ve *models.VerifiableEvent) (string, error)
func EnsureChainSelector ¶
EnsureChainSelector returns cfg.ChainSelector if set, otherwise returns the provided fallback.
func GetBlockTimestamp ¶
GetBlockTimestamp fetches the block timestamp via EVM HeaderByNumber; falls back to current UTC time if unavailable.
func GetContractABI ¶
GetContractABI returns the ABI string for the specified contract-name. Only the canonical "contractABI" field is supported.
func GetCurrencyCode ¶
func GetEventNameFromLog ¶
GetEventNameFromLog identifies the event name matching the log's topic hash by checking against the list of configured ContractEventNames and the ABI.
func GetEventSignature ¶
func InitEventListenerWorkflow ¶
InitEventListenerWorkflow wires the standard EVM Log trigger for event-listener workflows and attaches the provided handler. It resolves the event signatures from the ABI for all events in ContractEventNames and uses cfg.ChainSelector (required in the config).
func NewEVMLogFilter ¶
func NewEVMLogFilter(contractAddr string, eventSigHashes [][]byte) *evm.FilterLogTriggerRequest
NewEVMLogFilter returns a FilterLogTriggerRequest for a single-address subscription for one or more events, using FINALIZED confidence (common default across listeners). Includes wildcard slots for up to 3 indexed parameters.
func PBToUint64 ¶
PBToUint64 converts a protobuf BigInt (unsigned) to a uint64.
func ParseChainSelector ¶
ParseChainSelector validates and parses a chain_selector string parameter to uint64. Returns the parsed value or an error if the string is invalid.
func PrepareTestingRuntime ¶
func PrepareTestingRuntime(t *testing.T) *testutils.TestRuntime
PrepareTestingRuntime creates a test runtime with standard secrets configured.
func Retry ¶
Retry is a generic helper to retry operations up to a fixed number of times. It uses an exponential backoff strategy starting at 5 seconds. If the operation fails after all Attempts, it returns the last error wrapped with context. It stops retrying immediately if the function returns an error wrapped with StopRetry.
func SanitiseJSON ¶
SanitiseJSON transforms keys to snake_case and encodes []byte or base64-like strings as 0x-hex. big.Int is rendered as string to avoid 64-bit precision loss. Additionally, fixed-size byte arrays (e.g. [32]byte) are encoded as 0x-hex. For JSON-derived []interface{} representing byte arrays (length 20 or 32), encode as 0x-hex as well.
func SignAndPostVerifiableEvent ¶
func SignAndPostVerifiableEvent(cfg *Config, rt cre.Runtime, ve *models.VerifiableEvent) (string, error)
SignAndPostVerifiableEvent performs identical-consensus report generation and posts the signed event to the Courier /onchain-watcher-events endpoint. It returns the base64 verifiable event.
func TxHashFromLog ¶
TxHashFromLog returns the 0x-hex transaction hash from a log if present; otherwise "0x".
Types ¶
type Config ¶
type Config struct {
Network string `yaml:"network" json:"network"`
ChainID string `yaml:"chainID" json:"chainID"`
CourierURL string `yaml:"courierURL" json:"courierURL"`
Service *string `yaml:"service,omitempty" json:"service,omitempty"`
ApiKeySecret string `yaml:"apiKeySecret,omitempty" json:"apiKeySecret,omitempty"`
ChainSelector string `yaml:"chainSelector" json:"chainSelector"`
WatcherID string `yaml:"watcherID" json:"watcherID"`
WorkflowName string `yaml:"workflowName" json:"workflowName"`
DetectEventTriggerConfig DetectEventTriggerConfig `yaml:"detectEventTriggerConfig" json:"detectEventTriggerConfig"`
}
Config is the shared configuration for all event-detection workflows (YAML or JSON). It mirrors the structure produced by our existing config.tmpl files and remains compatible with server-side gomplate rendering used during e2e runs.
func ParseWorkflowConfig ¶
ParseWorkflowConfig accepts YAML or JSON and returns a Config. chainSelector is expected to be provided by the workflow config.
type ContractDef ¶
type ContractDef struct {
ContractABI any `yaml:"contractABI" json:"contractABI"`
}
ContractDef holds the ABI string in "contractABI".
type ContractReaderConfig ¶
type ContractReaderConfig struct {
Contracts map[string]ContractDef `yaml:"contracts" json:"contracts"`
}
ContractReaderConfig contains the contracts map. We only need contractABI for this workflow.
type DetectEventTriggerConfig ¶
type DetectEventTriggerConfig struct {
ContractName string `yaml:"contractName" json:"contractName"`
ContractAddress string `yaml:"contractAddress" json:"contractAddress"`
ContractEventNames []string `yaml:"contractEventNames" json:"contractEventNames"`
ContractReaderConfig ContractReaderConfig `yaml:"contractReaderConfig" json:"contractReaderConfig"`
}
DetectEventTriggerConfig matches the template data for the log trigger.
type Fixed2 ¶
type Fixed2 float64
Fixed2 represents a fixed-point decimal number with 2 decimal places, stored as a string.
func (Fixed2) MarshalJSON ¶
MarshalJSON marshals the Fixed2 value to a JSON string.
func (*Fixed2) UnmarshalJSON ¶
UnmarshalJSON unmarshals the Fixed2 value from a JSON string.
type LogHandler ¶
LogHandler is the function signature implemented by each event-listener workflow's per-project handler (e.g. OnLog, OnCoordinatorLog). It processes an EVM log and returns a base64-encoded verifiable event (or empty string) and an error.
type OffChainReferenceData ¶
type OffChainReferenceData struct {
Source OffChainReferenceDataSource `json:"source"` // The source of the off-chain reference data.
Data map[string]any `json:"data"` // The data returned from the source call.
}
OffChainReferenceData is a structured set of fields that can be used for reference data from off-chain sources.
func GetCurrencyCodeAsOffChainReferenceData ¶
func GetCurrencyCodeAsOffChainReferenceData(currencyId uint8) OffChainReferenceData
type OffChainReferenceDataSource ¶
type OffChainReferenceDataSource struct {
Type string `json:"type"` // The type of the off-chain reference data.
Identifier string `json:"identifier"` // Typically the URN for the off-chain source or identifier of the standardised data format.
}
OffChainReferenceDataSource is the source of the off-chain reference data.
type OnChainReferenceData ¶
type OnChainReferenceData struct {
Source OnChainReferenceDataSource `json:"source"` // The source of the on-chain reference data.
Data map[string]any `json:"data"` // The data returned from the source call.
}
OnChainReferenceData is a structured set of fields that can be used for reference data from on-chain sources.
type OnChainReferenceDataSource ¶
type OnChainReferenceDataSource struct {
ContractAddress string `json:"contract_address"` // The contract address to call.
ContractFunctionSignature string `json:"contract_function_signature"` // The function signature to call.
CallData string `json:"call_data"` // The call data to pass to the function.
Block string `json:"block"` // The block number to call the function at.
}
OnChainReferenceDataSource is the source of the on-chain reference data.
type PaymentCallback ¶
type PaymentCallback struct {
ContractAddress string `json:"contractAddress,omitempty"` // The contract address to call. If empty, uses ApplicationAddr from PaymentRequest.
FunctionName string `json:"functionName,omitempty"` // The name of the function to call.
FunctionSignature string `json:"functionSignature,omitempty"` // The ABI function signature to call (e.g., "fulfillPayment(bytes32,uint256)")
}
PaymentCallback specifies how to call back to the application after payment processing.
type PaymentRequest ¶
type PaymentRequest struct {
ApplicationType string `json:"applicationType"` // The type of the application that generates the payment request.
ApplicationAddr string `json:"applicationAddr"` // The application that generates the payment request.
E2EID string `json:"e2eId"` // The E2E ID of the payment request.
Sender string `json:"sender"` // The sender of the payment request.
Receiver string `json:"receiver"` // The receiver of the payment.
Currency string `json:"currency"` // The currency of the payment.
ChainID string `json:"chainId"` // The chain ID of the payment.
Amount Fixed2 `json:"amount"` // The amount of the payment in fixed-point decimal format with 2 decimal places.
Expiration *int64 `json:"expiration,omitempty"` // The expiration time of the payment request in seconds since epoch.
CustomCallback *PaymentCallback `json:"customCallback,omitempty"` // The custom callback to be used for the payment request.
}
PaymentRequest contains the details needed for an off-chain payment request.
type RawMessageType ¶
type RawMessageType string
const ( RawMessageTypePaymentRequest RawMessageType = "payment_request" RawMessageTypeReferenceData RawMessageType = "reference_data" )
const (
RawMessageTypeMap RawMessageType = "map"
)
type ReferenceData ¶
type ReferenceData struct {
OnChain []OnChainReferenceData `json:"on_chain,omitempty"` // The on-chain reference data.
OffChain []OffChainReferenceData `json:"off_chain,omitempty"` // The off-chain reference data.
Requests []TypeAndValue `json:"requests,omitempty"` // The requests to be forwarded to the off-chain applications.
}
ReferenceData is a structured set of fields that can be used for reference data from on-chain and off-chain sources as well as requests to be forwarded to off-chain applications.
func GetReferenceDataFromVerifiableEvent ¶
func GetReferenceDataFromVerifiableEvent(verifiableEvent models.VerifiableEvent) (*ReferenceData, error)
GetReferenceDataFromVerifiableEvent extracts the ReferenceData from the verifiable event data field if it exists.
type TypeAndValue ¶
type TypeAndValue struct {
Type RawMessageType `json:"type"`
Value json.RawMessage `json:"value"`
}
TypeAndValue is a type that holds a type and a value.