chains

Documentation

Index

• Variables
• type ChainService
• type ChainSet
  • func NewChainSet[I ID, C Config, N Node, S ChainService[C]](opts ChainSetOpts[I, C, N, S], formatID func(I) string) (ChainSet[I, C, N, S], error)
• type ChainSetOpts
• type ChainsORM
• type Config
• type DBChain
• type DBChainSet
• type DBNodeSet
• type ID
• type Node
• type NodesORM
• type ORM
  • func NewORM[I ID, C Config, N Node](q pg.Q, prefix string, nodeCols ...string) ORM[I, C, N]

Examples

• NewORM

Variables

var (
	// ErrChainIDEmpty is returned when chain is required but was empty.
	ErrChainIDEmpty = errors.New("chain id empty")
	// ErrChainIDInvalid is returned when a chain id does not match any configured chains.
	ErrChainIDInvalid = errors.New("chain id does not match any local chains")
)

Types

type ChainService

type ChainService[C Config] interface {
	services.ServiceCtx
	UpdateConfig(C)
}

ChainService is a live, runtime chain instance, with supporting services.

type ChainSet

type ChainSet[I ID, C Config, N Node, S ChainService[C]] interface {
	services.ServiceCtx

	DBChainSet[I, C]

	DBNodeSet[I, N]

	// Chain returns the ChainService for this ID (if a configuration is available), creating one if necessary.
	Chain(context.Context, I) (S, error)
}

ChainSet manages a live set of ChainService instances.

func NewChainSet

func NewChainSet[I ID, C Config, N Node, S ChainService[C]](
	opts ChainSetOpts[I, C, N, S], formatID func(I) string,
) (ChainSet[I, C, N, S], error)

NewChainSet returns a new ChainSet for the given ChainSetOpts.

type ChainSetOpts

type ChainSetOpts[I ID, C Config, N Node, S ChainService[C]] interface {
	Validate() error
	NewChain(DBChain[I, C]) (S, error)
	ORMAndLogger() (ORM[I, C, N], logger.Logger)
}

ChainSetOpts holds options for configuring a ChainSet via NewChainSet.

type ChainsORM

type ChainsORM[I ID, CFG Config, C DBChain[I, CFG]] interface {
	Chain(I, ...pg.QOpt) (C, error)
	Chains(offset, limit int, qopts ...pg.QOpt) ([]C, int, error)
	CreateChain(id I, config CFG, qopts ...pg.QOpt) (C, error)
	UpdateChain(id I, enabled bool, config CFG, qopts ...pg.QOpt) (C, error)
	DeleteChain(id I, qopts ...pg.QOpt) error
	GetChainsByIDs(ids []I) (chains []C, err error)
	EnabledChains(...pg.QOpt) ([]C, error)
}

type Config

type Config interface {
	sql.Scanner
	driver.Valuer
}

Config types should have fields for chain configuration, and implement sql.Scanner and driver.Valuer for persistence in JSON format.

type DBChain

type DBChain[I ID, C Config] struct {
	ID        I
	Cfg       C
	CreatedAt time.Time
	UpdatedAt time.Time
	Enabled   bool
}

DBChain is a generic DB chain for an ID and Config.

A DBChain type alias can be used for convenience:

type DBChain = chains.DBChain[string, pkg.ChainCfg]

type DBChainSet

type DBChainSet[I ID, C Config] interface {
	Add(ctx context.Context, id I, cfg C) (DBChain[I, C], error)
	Show(id I) (DBChain[I, C], error)
	Configure(ctx context.Context, id I, enabled bool, cfg C) (DBChain[I, C], error)
	Remove(id I) error
	Index(offset, limit int) ([]DBChain[I, C], int, error)
}

DBChainSet is a generic interface for DBChain[I, C] configuration.

type DBNodeSet

type DBNodeSet[I ID, N Node] interface {
	GetNodes(ctx context.Context, offset, limit int) (nodes []N, count int, err error)
	GetNodesForChain(ctx context.Context, chainID I, offset, limit int) (nodes []N, count int, err error)
	CreateNode(context.Context, N) (N, error)
	DeleteNode(context.Context, int32) error
}

DBNodeSet is a generic interface for Node configuration.

type ID

type ID any

ID types represent unique identifiers within a particular chain type. Using string is recommended.

type Node

type Node any

Node types should be a struct including these default fields:

ID        int32
Name      string
CreatedAt time.Time
UpdatedAt time.Time

type NodesORM

type NodesORM[I ID, N Node] interface {
	CreateNode(N, ...pg.QOpt) (N, error)
	DeleteNode(int32, ...pg.QOpt) error
	GetNodesByChainIDs(chainIDs []I, qopts ...pg.QOpt) (nodes []N, err error)
	Node(int32, ...pg.QOpt) (N, error)
	NodeNamed(string, ...pg.QOpt) (N, error)
	Nodes(offset, limit int, qopts ...pg.QOpt) (nodes []N, count int, err error)
	NodesForChain(chainID I, offset, limit int, qopts ...pg.QOpt) (nodes []N, count int, err error)
}

type ORM

type ORM[I ID, C Config, N Node] interface {
	ChainsORM[I, C, DBChain[I, C]]

	NodesORM[I, N]

	StoreString(chainID I, key, val string) error
	Clear(chainID I, key string) error

	// SetupNodes is a shim to help with configuring multiple nodes via ENV.
	// All existing nodes are dropped, and any missing chains are automatically created.
	// Then all nodes are inserted, and conflicts are ignored.
	SetupNodes(nodes []N, chainIDs []I) error
}

ORM manages chains and nodes.

func NewORM

func NewORM[I ID, C Config, N Node](q pg.Q, prefix string, nodeCols ...string) ORM[I, C, N]

NewORM returns an ORM backed by q, for the tables <prefix>_chains and <prefix>_nodes with column <prefix>_chain_id. Additional Node fields should be included in nodeCols.

Example

package main

import (
	"database/sql/driver"
	"encoding/json"
	"time"

	"github.com/pkg/errors"
	"gopkg.in/guregu/null.v4"

	"github.com/smartcontractkit/chainlink/core/chains"
	"github.com/smartcontractkit/chainlink/core/services/pg"
)

type Config struct {
	Foo null.String
}

func (c *Config) Scan(value any) error {
	b, ok := value.([]byte)
	if !ok {
		return errors.New("type assertion to []byte failed")
	}

	return json.Unmarshal(b, c)
}

func (c *Config) Value() (driver.Value, error) {
	return json.Marshal(c)
}

func main() {
	type Node = struct {
		ID             int32
		Name           string
		ExampleChainID string
		URL            string
		Bar            null.Int
		CreatedAt      time.Time
		UpdatedAt      time.Time
	}
	var q pg.Q
	_ = chains.NewORM[string, *Config, Node](q, "example", "url", "bar")

}