core

Documentation

Overview

Sequence core primitives

DecodeSignature takes raw signature data and returns a Signature. A Signature can Recover the WalletConfig it represents. A WalletConfig describes the configuration of signers that control a wallet.

Index

• Variables
• func RegisterCore[C WalletConfig, S Signature[C]](core Core[C, S])
• func SigningOrchestrator(ctx context.Context, signers map[common.Address]uint16, sign SigningFunction) chan SignerSignature
• type Core
  • func GetCoreForWalletConfig[C WalletConfig]() (Core[C, Signature[C]], error)
• type Digest
  • func NewDigest(messages ...[]byte) Digest
  • func (d Digest) ApprovedImageHash() (ImageHash, error)
  • func (d Digest) Subdigest(wallet common.Address, chainID ...*big.Int) Subdigest
• type ImageHash
  • func (h ImageHash) Approval() Digest
• type ImageHashable
• type Signature
• type SignerSignature
• type SignerSignatureType
• type SignerSignatures
  • func (s SignerSignatures) Insert(signer common.Address, signature SignerSignature)
• type SigningFunction
• type Subdigest
  • func (s Subdigest) EthSignSubdigest() Subdigest
• type WalletConfig

Variables

var ErrSigningFunctionNotReady = fmt.Errorf("signing function not ready")

ErrSigningFunctionNotReady is returned when a signing function is not ready to sign and should be retried later.

Functions

func RegisterCore

func RegisterCore[C WalletConfig, S Signature[C]](core Core[C, S])

func SigningOrchestrator

func SigningOrchestrator(ctx context.Context, signers map[common.Address]uint16, sign SigningFunction) chan SignerSignature

Types

type Core

type Core[C WalletConfig, S Signature[C]] interface {
	// DecodeSignature takes raw signature data and returns a Signature that can Recover a WalletConfig.
	DecodeSignature(data []byte) (S, error)

	// DecodeWalletConfig takes a decoded JSON object and returns a WalletConfig.
	DecodeWalletConfig(object any) (C, error)
}

func GetCoreForWalletConfig

func GetCoreForWalletConfig[C WalletConfig]() (Core[C, Signature[C]], error)

type Digest

type Digest struct {
	common.Hash

	// Preimage is the preimage of the digest, nil if unknown.
	Preimage []byte
}

A Digest is a hash signed by a Sequence wallet. Used for type safety and preimage recovery.

func NewDigest

func NewDigest(messages ...[]byte) Digest

NewDigest creates a Digest from a list of messages.

func (Digest) ApprovedImageHash

func (d Digest) ApprovedImageHash() (ImageHash, error)

ApprovedImageHash recovers the ImageHash that the Digest approves for subsequent signatures, if known.

func (Digest) Subdigest

func (d Digest) Subdigest(wallet common.Address, chainID ...*big.Int) Subdigest

Subdigest derives the hash to be signed by the Sequence wallet's signers to validate the digest.

type ImageHash

type ImageHash struct {
	common.Hash

	// Preimage is the ImageHashable with this ImageHash, nil if unknown.
	Preimage ImageHashable
}

An ImageHash is a digest of an ImageHashable. Used for type safety and preimage recovery.

func (ImageHash) Approval

func (h ImageHash) Approval() Digest

Approval derives the digest that must be signed to approve the ImageHash for subsequent signatures.

type ImageHashable

type ImageHashable interface {
	// ImageHash is the digest of the object.
	ImageHash() ImageHash
}

An ImageHashable is an object with an ImageHash.

type Signature

type Signature[C WalletConfig] interface {
	// Threshold is the minimum signing weight required for a signature to be valid.
	Threshold() uint16

	// Checkpoint is the nonce of the wallet configuration that the signature applies to.
	Checkpoint() uint32

	// Recover derives the wallet configuration that the signature applies to.
	// Also returns the signature's weight.
	// If chainID is not provided, provider must be provided.
	// If provider is not provided, EIP-1271 signatures are assumed to be NOT valid and ignored.
	// If signerSignatures is provided, it will be populated with the valid signer signatures of this signature.
	Recover(ctx context.Context, digest Digest, wallet common.Address, chainID *big.Int, provider *ethrpc.Provider, signerSignatures ...SignerSignatures) (C, *big.Int, error)

	// Recover a signature but only using the subdigest
	RecoverSubdigest(ctx context.Context, subdigest Subdigest, provider *ethrpc.Provider, signerSignatures ...SignerSignatures) (C, *big.Int, error)

	// Reduce returns an equivalent optimized signature.
	Reduce(subdigest Subdigest) Signature[C]

	// Join joins two signatures into one.
	Join(subdigest Subdigest, other Signature[C]) (Signature[C], error)

	// Data is the raw signature data.
	Data() ([]byte, error)

	// Write writes the raw signature data to a Writer.
	Write(writer io.Writer) error
}

A Signature is a decoded signature that can Recover a WalletConfig.

type SignerSignature

type SignerSignature struct {
	Signer    common.Address
	Subdigest Subdigest
	Type      SignerSignatureType
	Signature []byte
}

type SignerSignatureType

type SignerSignatureType int

const (
	SignerSignatureTypeEIP712 SignerSignatureType = iota + 1
	SignerSignatureTypeEthSign
	SignerSignatureTypeEIP1271
)

type SignerSignatures

type SignerSignatures map[common.Address]map[common.Hash]SignerSignature

A SignerSignatures object stores signer signatures indexed by signer and subdigest.

func (SignerSignatures) Insert

func (s SignerSignatures) Insert(signer common.Address, signature SignerSignature)

type SigningFunction

type SigningFunction func(ctx context.Context, signer common.Address, signatures []SignerSignature) (SignerSignatureType, []byte, error)

type Subdigest

type Subdigest struct {
	common.Hash

	// Digest is the preimage of the subdigest, nil if unknown.
	Digest *Digest

	// Wallet is the target wallet of the subdigest, nil if unknown.
	Wallet *common.Address

	// ChainID is the target chain ID of the subdigest, nil if unknown.
	ChainID *big.Int

	// EthSignPreimage is the preimage of the eth_sign subdigest, nil if unknown.
	EthSignPreimage *Subdigest
}

A Subdigest is a hash signed by a Sequence wallet's signers. Used for type safety and preimage recovery.

func (Subdigest) EthSignSubdigest

func (s Subdigest) EthSignSubdigest() Subdigest

EthSignSubdigest derives the eth_sign subdigest of a subdigest.

type WalletConfig

type WalletConfig interface {
	ImageHashable

	// Threshold is the minimum signing weight required for a signature to be valid.
	Threshold() uint16

	// Checkpoint is the nonce of the wallet configuration.
	Checkpoint() uint32

	// Signers is the set of signers in the wallet configuration.
	Signers() map[common.Address]uint16

	// SignersWeight is the total weight of the signers passed to the function according to the wallet configuration.
	SignersWeight(signers []common.Address) uint16

	// IsUsable checks if it's possible to construct signatures that meet threshold.
	IsUsable() error
}

A WalletConfig is a configuration of signers that control a wallet.