notary

README

Notary

What's the context for the notary

In some scenarios, the Vega network needs to be able to express a decision taken by the network (meaning in our case by all the validator nodes), in a way which can be understood by a foreign entity/foreign network (e.g ethereum).

To do so, all Vega nodes must be started with wallets recognised by these foreign entities, and which would represent the Vega node in that network. Currently all Vega nodes require these - in future the requirement could be changed to only include validators. These wallets are recognised by both Vega and the foreign network, which allows the node to sign messages with a signatures that can be verified by both parties.

The notary is here to keep track of all the signatures, and of the minimum amount of signatures required for the decision to be valid. The notary also exposes a service and API which allows a user to retrieve the aggregated signatures in order to use them outside of Vega.

Network events that require notarisation

• Approval of a new asset
• Approval of a withdrawal

Extra events coming soon

• Adding a new validator

Example use case.

In the context of submitting a Governance proposal for a new erc20 token to be used in Vega, when the proposal has been approved by the token holders, Vega needs to inform the erc20 token bridge contract that the new token needs to be enabled.

To do so, at the end of the governance process all nodes will sign a message which can be verified by the bridge contract on the Ethereum network. All of these signatures will be aggregated by the notary, which them makes them available for an end user to provide when executing the Vega Bridge contract to enable the asset to be deposited in to the system.

Documentation

Index

• Variables
• type Broker
• type Commander
• type Config
  • func NewDefaultConfig() Config
• type Notary
  • func New(log *logging.Logger, cfg Config, top ValidatorTopology, broker Broker, ...) (n *Notary)
  • func (n *Notary) IsSigned(ctx context.Context, resource string, kind commandspb.NodeSignatureKind) ([]commandspb.NodeSignature, bool)
  • func (n *Notary) OnDefaultValidatorsVoteRequiredUpdate(ctx context.Context, d num.Decimal) error
  • func (n *Notary) OnTick(ctx context.Context, t time.Time)
  • func (n *Notary) RegisterSignature(ctx context.Context, pubKey string, ns commandspb.NodeSignature) error
  • func (n *Notary) ReloadConf(cfg Config)
  • func (n *Notary) StartAggregate(resource string, kind commandspb.NodeSignatureKind, signature []byte)
• type SnapshotNotary
  • func NewWithSnapshot(log *logging.Logger, cfg Config, top ValidatorTopology, broker Broker, ...) *SnapshotNotary
  • func (n *SnapshotNotary) GetState(k string) ([]byte, []types.StateProvider, error)
  • func (n *SnapshotNotary) Keys() []string
  • func (n *SnapshotNotary) LoadState(ctx context.Context, payload *types.Payload) ([]types.StateProvider, error)
  • func (n *SnapshotNotary) Namespace() types.SnapshotNamespace
  • func (n *SnapshotNotary) OfferSignatures(kind types.NodeSignatureKind, f func(resource string) []byte)
  • func (n *SnapshotNotary) RegisterSignature(ctx context.Context, pubKey string, ns v1.NodeSignature) error
  • func (n *SnapshotNotary) StartAggregate(resource string, kind v1.NodeSignatureKind, signature []byte)
  • func (n *SnapshotNotary) Stopped() bool
• type ValidatorTopology

Variables

var (
	ErrAggregateSigAlreadyStartedForResource = errors.New("aggregate signature already started for resource")
	ErrUnknownResourceID                     = errors.New("unknown resource ID")
	ErrNotAValidatorSignature                = errors.New("not a validator signature")
)

Types

type Broker

type Broker interface {
	Send(event events.Event)
	SendBatch(events []events.Event)
}

Broker needs no mocks.

type Commander

type Commander interface {
	Command(ctx context.Context, cmd txn.Command, payload proto.Message, f func(string, error), bo *backoff.ExponentialBackOff)
	CommandSync(ctx context.Context, cmd txn.Command, payload proto.Message, f func(string, error), bo *backoff.ExponentialBackOff)
}

type Config

type Config struct {
	// logging level
	Level encoding.LogLevel `long:"log-level"`
}

Config represents governance specific configuration.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates an instance of the package specific configuration.

type Notary

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

Notary will aggregate all signatures of a node for a specific Command e.g: asset withdrawal, asset allowlisting, etc.

func New

func New(
	log *logging.Logger,
	cfg Config,
	top ValidatorTopology,
	broker Broker,
	cmd Commander,
) (n *Notary)

func (*Notary) IsSigned

func (n *Notary) IsSigned(
	ctx context.Context,
	resource string,
	kind commandspb.NodeSignatureKind,
) ([]commandspb.NodeSignature, bool)

func (*Notary) OnDefaultValidatorsVoteRequiredUpdate

func (n *Notary) OnDefaultValidatorsVoteRequiredUpdate(ctx context.Context, d num.Decimal) error

func (*Notary) OnTick

func (n *Notary) OnTick(ctx context.Context, t time.Time)

onTick is only use to trigger resending transaction.

func (*Notary) RegisterSignature

func (n *Notary) RegisterSignature(
	ctx context.Context,
	pubKey string,
	ns commandspb.NodeSignature,
) error

func (*Notary) ReloadConf

func (n *Notary) ReloadConf(cfg Config)

ReloadConf updates the internal configuration.

func (*Notary) StartAggregate

func (n *Notary) StartAggregate(
	resource string,
	kind commandspb.NodeSignatureKind,
	signature []byte,
)

StartAggregate will register a new signature to be sent for a validator, or just ignore the signature and start aggregating signature for now validators, nil for the signature is OK for non-validators.

type SnapshotNotary

type SnapshotNotary struct {
	*Notary
	// contains filtered or unexported fields
}

func NewWithSnapshot

func NewWithSnapshot(
	log *logging.Logger,
	cfg Config,
	top ValidatorTopology,
	broker Broker,
	cmd Commander,
) *SnapshotNotary

NewWithSnapshot returns an "extended" Notary type which contains the ability to take engine snapshots.

func (*SnapshotNotary) GetState

func (n *SnapshotNotary) GetState(k string) ([]byte, []types.StateProvider, error)

func (*SnapshotNotary) Keys

func (n *SnapshotNotary) Keys() []string

func (*SnapshotNotary) LoadState

func (n *SnapshotNotary) LoadState(ctx context.Context, payload *types.Payload) ([]types.StateProvider, error)

func (*SnapshotNotary) Namespace

func (n *SnapshotNotary) Namespace() types.SnapshotNamespace

func (*SnapshotNotary) OfferSignatures

func (n *SnapshotNotary) OfferSignatures(
	kind types.NodeSignatureKind,

	f func(resource string) []byte,
)

func (*SnapshotNotary) RegisterSignature

func (n *SnapshotNotary) RegisterSignature(
	ctx context.Context,
	pubKey string,
	ns v1.NodeSignature,
) error

RegisterSignature is a wrapper to Notary's RegisterSignature which also manages the snapshot state.

func (*SnapshotNotary) StartAggregate

func (n *SnapshotNotary) StartAggregate(
	resource string,
	kind v1.NodeSignatureKind,
	signature []byte,
)

StartAggregate is a wrapper to Notary's StartAggregate which also manages the snapshot state.

func (*SnapshotNotary) Stopped

func (n *SnapshotNotary) Stopped() bool

type ValidatorTopology

type ValidatorTopology interface {
	IsValidator() bool
	IsValidatorVegaPubKey(string) bool
	IsTendermintValidator(string) bool
	SelfVegaPubKey() string
	Len() int
}

ValidatorTopology...