universe

package
v0.5.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Nov 27, 2024 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultTimeout is the default timeout we use for RPC and database
	// operations.
	DefaultTimeout = 30 * time.Second
)
View Source 
const (
	// DefaultUniverseRPCPort is the default port that the universe RPC is
	// hosted on.
	DefaultUniverseRPCPort = 10029
)
View Source 
const (
	// MaxPageSize is the maximum page size that can be used when querying
	// for asset roots and leaves.
	MaxPageSize = 16384
)
View Source 
const Subsystem = "UNIV"

Subsystem defines the logging code for this subsystem.

Variables

View Source 
var (
	// ErrNoUniverseRoot is returned when no universe root is found.
	ErrNoUniverseRoot = fmt.Errorf("no universe root found")

	// ErrNoUniverseServers is returned when no active Universe servers are
	// found in the DB.
	ErrNoUniverseServers = fmt.Errorf("no active federation servers")

	// ErrDuplicateUniverse is returned when the Universe server being added
	// to the DB already exists.
	ErrDuplicateUniverse = fmt.Errorf("universe server already added")

	// ErrNoUniverseProofFound is returned when a user attempts to look up
	// a key in the universe that actually points to the empty leaf.
	ErrNoUniverseProofFound = fmt.Errorf("no universe proof found")
)
View Source 
var (
	// ErrUnsupportedSync is returned when a syncer is asked to async in a
	// way that it does not support.
	ErrUnsupportedSync = fmt.Errorf("unsupported sync type")
)

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

func ValidateProofUniverseType added in v0.3.0 

func ValidateProofUniverseType(a *asset.Asset, uniID Identifier) error

ValidateProofUniverseType validates that the proof type matches the universe identifier proof type.

Types

type AggregateStats 

type AggregateStats struct {
	// NumTotalAssets is the total number of assets in the Universe.
	NumTotalAssets uint64

	// NumTotalGroups is the total number of groups in the Universe.
	NumTotalGroups uint64

	// NumTotalSyncs is the total number of syncs that have been performed
	// in the Universe.
	NumTotalSyncs uint64

	// NumTotalProofs is the total number of proofs that have been inserted
	// into the Universe.
	NumTotalProofs uint64
}

AggregateStats is a set of aggregate stats for a given Universe.

type Archive added in v0.3.1 

type Archive struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Archive is a persistence implementation of the universe interface. This is used by minting sub-systems to upsert new universe issuance proofs each time an asset is created. It can also be used to synchronize state amongst disparate universe instances, and also to serve as initial bootstrap for users wishing to send/receive assets.

TODO(roasbeef): erect universe in front of?

func NewArchive added in v0.3.1 

func NewArchive(cfg ArchiveConfig) *Archive

NewArchive creates a new universe archive based on the passed config.

func (*Archive) Close added in v0.3.3 

func (a *Archive) Close() error

Close closes the archive, stopping all goroutines and freeing all resources.

func (*Archive) DeleteRoot added in v0.3.1 

func (a *Archive) DeleteRoot(ctx context.Context,
	id Identifier) (string, error)

DeleteRoot deletes all universe leaves, and the universe root, for the specified base universe.

func (*Archive) FetchProofLeaf added in v0.3.1 

func (a *Archive) FetchProofLeaf(ctx context.Context, id Identifier,
	key LeafKey) ([]*Proof, error)

FetchProofLeaf attempts to fetch a proof leaf for the target leaf key and given a universe identifier (assetID/groupKey).

func (*Archive) MintingLeaves added in v0.3.1 

func (a *Archive) MintingLeaves(ctx context.Context,
	id Identifier) ([]Leaf, error)

MintingLeaves returns the set of minting leaves known for the specified base universe.

func (*Archive) MultiverseRoot added in v0.4.0 

func (a *Archive) MultiverseRoot(ctx context.Context, proofType ProofType,
	filterByIDs []Identifier) (fn.Option[MultiverseRoot], error)

MultiverseRoot returns the root node of the multiverse for the specified proof type. If the given list of universe IDs is non-empty, then the root will be calculated just for those universes.

func (*Archive) RootNode added in v0.3.1 

func (a *Archive) RootNode(ctx context.Context,
	id Identifier) (Root, error)

RootNode returns the root node of the base universe corresponding to the passed ID.

func (*Archive) RootNodes added in v0.3.1 

func (a *Archive) RootNodes(ctx context.Context,
	q RootNodesQuery) ([]Root, error)

RootNodes returns the set of root nodes for all known base universes assets.

func (*Archive) UniverseLeafKeys added in v0.3.1 

func (a *Archive) UniverseLeafKeys(ctx context.Context,
	q UniverseLeafKeysQuery) ([]LeafKey, error)

UniverseLeafKeys returns the set of leaf keys known for the specified universe identifier.

func (*Archive) UpsertProofLeaf added in v0.3.1 

func (a *Archive) UpsertProofLeaf(ctx context.Context, id Identifier,
	key LeafKey, leaf *Leaf) (*Proof, error)

UpsertProofLeaf attempts to upsert a proof for an asset issuance or transfer event. This method will return an error if the passed proof is invalid. If the leaf is already known, then no action is taken and the existing commitment proof returned.

func (*Archive) UpsertProofLeafBatch added in v0.3.1 

func (a *Archive) UpsertProofLeafBatch(ctx context.Context,
	items []*Item) error

UpsertProofLeafBatch inserts a batch of proof leaves within the target universe tree. We assume the proofs within the batch have already been checked that they don't yet exist in the local database.

type ArchiveConfig added in v0.3.1 

type ArchiveConfig struct {
	// NewBaseTree returns a new base universe backend for the given
	// identifier. This method always returns a new universe instance, even
	// if the identifier has never been seen before.
	NewBaseTree func(id Identifier) BaseBackend

	// HeaderVerifier is used to verify the validity of the header for a
	// genesis proof.
	HeaderVerifier proof.HeaderVerifier

	// MerkleVerifier is used to verify the validity of the transaction
	// merkle proof.
	MerkleVerifier proof.MerkleVerifier

	// GroupVerifier is used to verify the validity of the group key for a
	// genesis proof.
	GroupVerifier proof.GroupVerifier

	// Multiverse is used to interact with the set of known base
	// universe trees, and also obtain associated metadata and statistics.
	Multiverse MultiverseArchive

	// UniverseStats is used to export statistics related to the set of
	// external/internal queries to the base universe instance.
	UniverseStats Telemetry

	// ChainLookupGenerator is the main interface for generating a chain
	// lookup interface that is required to validate proofs.
	ChainLookupGenerator proof.ChainLookupGenerator
}

ArchiveConfig is the main config for the archive. This includes all the items required to interact with the set of relevant universes.

type AssetSyncDiff 

type AssetSyncDiff struct {
	// OldUniverseRoot is the root of the universe before the sync.
	OldUniverseRoot Root

	// NewUniverseRoot is the new root of the Universe after the sync.
	NewUniverseRoot Root

	// NewAssetLeaves is the set of new leaf proofs that were added to the
	// Universe.
	NewLeafProofs []*Leaf
}

AssetSyncDiff is the result of a success Universe sync. The diff contains the Universe root, and the set of assets that were added to the Universe.

type AssetSyncSnapshot 

type AssetSyncSnapshot struct {
	// AssetID is the ID of the asset.
	AssetID asset.ID

	// GroupKey is the optional group key of the asset.
	GroupKey *btcec.PublicKey

	// GroupSupply is the total supply of the whole asset group. This is
	// only set for grouped assets.
	GroupSupply uint64

	// GenesisPoint is the first previous output that created the asset.
	GenesisPoint wire.OutPoint

	// AssetName is the name of the asset.
	AssetName string

	// AssetType is the type of the asset.
	AssetType asset.Type

	// TotalSupply is the total supply of the asset.
	TotalSupply uint64

	// GenesisHeight is the height of the block that the asset was created
	// in.
	GenesisHeight uint32

	// TotalSyncs is the total number of syncs that have been performed for
	// the target asset.
	TotalSyncs uint64

	// TotalProofs is the total number of proofs that have been inserted
	// for the asset.
	TotalProofs uint64

	// AnchorPoint is the outpoint of the transaction that created the
	// asset.
	AnchorPoint wire.OutPoint
}

AssetSyncSnapshot is a snapshot of the sync activity for a given asset.

type AssetSyncStats 

type AssetSyncStats struct {
	// Query is the original query that was used to generate the stats.
	Query SyncStatsQuery

	// SyncStats is the set of sync stats generated by the query.
	SyncStats []AssetSyncSnapshot
}

AssetSyncStats is the response to a SyncStatsQuery request. It contains the original query, and the set of sync stats generated by the query.

type BaseBackend 

type BaseBackend interface {
	// RootNode returns the root node for a given base universe.
	RootNode(context.Context) (mssmt.Node, string, error)

	// RegisterIssuance inserts a new minting leaf within the universe
	// tree, stored at the base key. The metaReveal type is purely
	// optional, and should be specified if the genesis proof committed to
	// a non-zero meta hash.
	RegisterIssuance(ctx context.Context, key LeafKey, leaf *Leaf,
		metaReveal *proof.MetaReveal) (*Proof, error)

	// FetchIssuanceProof returns an issuance proof for the target key. If
	// the key doesn't have a script key specified, then all the proofs for
	// the minting outpoint will be returned. If neither are specified,
	// then proofs for all the inserted leaves will be returned.
	//
	// TODO(roasbeef): can eventually do multi-proofs for the SMT
	FetchIssuanceProof(ctx context.Context,
		key LeafKey) ([]*Proof, error)

	// MintingKeys returns all the keys inserted in the universe.
	MintingKeys(ctx context.Context,
		q UniverseLeafKeysQuery) ([]LeafKey, error)

	// MintingLeaves returns all the minting leaves inserted into the
	// universe.
	MintingLeaves(ctx context.Context) ([]Leaf, error)

	// DeleteUniverse deletes all leaves, and the root, for a given base
	// universe.
	DeleteUniverse(ctx context.Context) (string, error)
}

BaseBackend is the backend storage interface for a base universe. The backend can be used to store issuance profs, retrieve them, and also fetch the set of keys and leaves stored within the universe.

TODO(roasbeef): gRPC service to match this, think about the REST mapping

type BatchRegistrar added in v0.3.0 

type BatchRegistrar interface {
	Registrar

	// UpsertProofLeafBatch inserts a batch of proof leaves within the
	// target universe tree. We assume the proofs within the batch have
	// already been checked that they don't yet exist in the local database.
	UpsertProofLeafBatch(ctx context.Context, items []*Item) error
}

BatchRegistrar is an interface that allows a caller to register a batch of proof items within a universe.

type Canonical 

type Canonical interface {
	BaseBackend

	// Query returns a fully proved response for the target base key.
	Query(context.Context, LeafKey) (*CommittedIssuanceProof, error)

	// LatestCommitment returns the latest chain commitment.
	LatestCommitment() (*Commitment, error)

	// UpdateChainCommitment takes in a series of chain commitments and
	// updates the commitment on chain.
	UpdateChainCommitment(chainCommits ...ChainCommitter) (*Commitment, error)
}

Canonical is an interface that allows a caller to query for the latest canonical Universe information related to an asset.

TODO(roasbeef): sync methods too, divide into read/write?

type ChainCommitter 

type ChainCommitter interface {
	// CommitUniverse takes a Universe and returns a new commitment to that
	// Universe in the main chain.
	CommitUniverse(universe BaseBackend) (*Commitment, error)
}

ChainCommitter is used to commit a Universe backend in the chain.

type Commitment 

type Commitment struct {
	// BlockHeight is the height of the block that the commitment is
	// contained within.
	BlockHeight uint32

	// BlockHeader is the block header that commits to the transaction.
	BlockHeader wire.BlockHeader

	// MerkleProof is a merkle proof for the above transaction that the
	// anchor output was included.
	MerkleProof *proof.TxMerkleProof

	// UniverseRoot is the full Universe root for this commitment.
	UniverseRoot mssmt.Node
}

Commitment is an on chain universe commitment. This includes the merkle proof for a transaction which anchors the target universe root.

type CommittedIssuanceProof 

type CommittedIssuanceProof struct {
	// ChainProof is the on chain proof that shows the Universe root has
	// been stamped in the chain.
	ChainProof *Commitment

	// TaprootAssetProof is a proof of new asset issuance.
	TaprootAssetProof *Proof
}

CommittedIssuanceProof couples together a Bitcoin level merkle proof commitment with an issuance proof. This allows remote callers to verify that their responses re actually committed to within the chain.

type DiffEngine 

type DiffEngine interface {
	// RootNode returns the root node for a given base universe.
	RootNode(ctx context.Context, id Identifier) (Root, error)

	// RootNodes returns the set of root nodes for all known universes.
	RootNodes(ctx context.Context, q RootNodesQuery) ([]Root, error)

	// UniverseLeafKeys returns all the keys inserted in the universe.
	UniverseLeafKeys(ctx context.Context,
		q UniverseLeafKeysQuery) ([]LeafKey, error)

	// FetchProofLeaf attempts to fetch a proof leaf for the target leaf key
	// and given a universe identifier (assetID/groupKey).
	//
	// TODO(roasbeef): actually add this somewhere else?  * rn kinda
	// asymmetric, as just need this to complete final portion
	// of diff
	FetchProofLeaf(ctx context.Context, id Identifier,
		key LeafKey) ([]*Proof, error)

	// Close is used to shutdown the active diff engine instance.
	Close() error
}

DiffEngine is a Universe diff engine that can be used to compare the state of two universes and find the set of assets that are different between them.

type FedGlobalSyncConfig added in v0.3.0 

type FedGlobalSyncConfig struct {
	// ProofTypes represents the configuration target universe proof type.
	ProofType ProofType

	// AllowSyncExport is a boolean that indicates whether leaves from
	// universes of the given proof type have may be inserted via federation
	// sync.
	AllowSyncInsert bool

	// AllowSyncExport is a boolean that indicates whether leaves from
	// universes of the given proof type have may be exported via federation
	// sync.
	AllowSyncExport bool
}

FedGlobalSyncConfig is a config that can be used to specify the global (default) federation sync behavior.

type FedUniSyncConfig added in v0.3.0 

type FedUniSyncConfig struct {
	// UniverseID is the ID of the Universe that the config applies to.
	UniverseID Identifier

	// AllowSyncInsert is a boolean that indicates whether leaves from the
	// target universe may be inserted via federation sync.
	AllowSyncInsert bool

	// AllowSyncExport is a boolean that indicates whether leaves from the
	// target universe may be exported via federation sync.
	AllowSyncExport bool
}

FedUniSyncConfig is a config that can be used to specify the federation sync behavior for a given Universe.

type FederationConfig 

type FederationConfig struct {
	// FederationDB is used for CRUD operations related to federation sync
	// config and tracked servers.
	FederationDB FederationDB

	// UniverseSyncer is used to synchronize with the federation
	// periodically.
	UniverseSyncer Syncer

	// NewRemoteRegistrar is a function that returns a new register instance
	// to the target remote Universe. This'll be used to optimistically push
	// out new updates to Universe servers.
	NewRemoteRegistrar func(ServerAddr) (Registrar, error)

	// LocalRegistrar is the local register. This'll be used to add new
	// leaves (minting events) to our local server before pushing them out
	// to the federation.
	LocalRegistrar BatchRegistrar

	// SyncInterval is the period that we'll use to synchronize with the
	// set of Universe servers.
	SyncInterval time.Duration

	// ErrChan is the main error channel the custodian will report back
	// critical errors to the main server.
	ErrChan chan<- error

	// StaticFederationMembers is a set of static federation members
	// that'll be added on start up, and used to sync and push out proofs
	// with.
	StaticFederationMembers []string

	// ServerChecker is a function that can be used to check if a server is
	// operational and not the local daemon.
	ServerChecker func(ServerAddr) error
}

FederationConfig is a config that the FederationEnvoy will use to synchronize new updates between the current set of federated Universe nodes.

type FederationDB added in v0.3.0 

type FederationDB interface {
	FederationLog
	FederationProofSyncLog
	FederationSyncConfigDB
}

FederationDB is used for CRUD operations related to federation logs and configuration.

type FederationEnvoy 

type FederationEnvoy struct {
	*fn.ContextGuard
	// contains filtered or unexported fields
}

FederationEnvoy is used to manage synchronization between the set of federated Universe servers. It handles the periodic sync between universe servers, and can also be used to push out new locally created proofs to the federation.

func NewFederationEnvoy 

func NewFederationEnvoy(cfg FederationConfig) *FederationEnvoy

NewFederationEnvoy creates a new federation envoy from the passed config.

func (*FederationEnvoy) AddServer 

func (f *FederationEnvoy) AddServer(addrs ...ServerAddr) error

AddServer adds a new set of servers to the federation, then immediately performs a new background sync.

func (*FederationEnvoy) Close added in v0.3.3 

func (f *FederationEnvoy) Close() error

Close frees up any ephemeral resources allocated by the envoy.

func (*FederationEnvoy) EnableAssetSync added in v0.3.1 

func (f *FederationEnvoy) EnableAssetSync(ctx context.Context,
	groupInfo *asset.AssetGroup) error

EnableAssetSync updates the sync config for the given asset to that we sync future issuance proofs.

func (*FederationEnvoy) QuerySyncConfigs added in v0.3.0 

func (f *FederationEnvoy) QuerySyncConfigs(
	ctx context.Context) (*SyncConfigs, error)

QuerySyncConfigs returns the current sync configs for the federation.

func (*FederationEnvoy) SetConfigSyncAllAssets added in v0.4.0 

func (f *FederationEnvoy) SetConfigSyncAllAssets() error

SetConfigSyncAllAssets sets the global (default) sync config to sync all assets.

func (*FederationEnvoy) Start 

func (f *FederationEnvoy) Start() error

Start launches all goroutines needed to interact with the envoy.

func (*FederationEnvoy) Stop 

func (f *FederationEnvoy) Stop() error

Stop stops all active goroutines.

func (*FederationEnvoy) SyncAssetInfo added in v0.3.1 

func (f *FederationEnvoy) SyncAssetInfo(ctx context.Context,
	assetID *asset.ID) error

SyncAssetInfo queries the universes in our federation for genesis and asset group information about the given asset ID.

func (*FederationEnvoy) SyncServers added in v0.3.0 

func (f *FederationEnvoy) SyncServers(serverAddrs []ServerAddr) error

func (*FederationEnvoy) UpsertProofLeaf added in v0.3.1 

func (f *FederationEnvoy) UpsertProofLeaf(_ context.Context, id Identifier,
	key LeafKey, leaf *Leaf) (*Proof, error)

UpsertProofLeaf upserts a proof leaf within the target universe tree. This can be used to first push out a new update to the local registrar, ultimately queuing it to also be sent to the set of active universe servers.

NOTE: This is part of the universe.Registrar interface.

func (*FederationEnvoy) UpsertProofLeafBatch added in v0.3.1 

func (f *FederationEnvoy) UpsertProofLeafBatch(_ context.Context,
	items []*Item) error

UpsertProofLeafBatch inserts a batch of proof leaves within the target universe tree. We assume the proofs within the batch have already been checked that they don't yet exist in the local database.

NOTE: This is part of the universe.BatchRegistrar interface.

type FederationLog 

type FederationLog interface {
	// UniverseServers returns the set of servers in the federation.
	UniverseServers(ctx context.Context) ([]ServerAddr, error)

	// AddServers adds a slice of servers to the federation.
	AddServers(ctx context.Context, addrs ...ServerAddr) error

	// RemoveServers removes a set of servers from the federation.
	RemoveServers(ctx context.Context, addrs ...ServerAddr) error

	// LogNewSyncs logs a new sync event for each server. This can be used
	// to keep track of the last time we synced with a remote server.
	LogNewSyncs(ctx context.Context, addrs ...ServerAddr) error
}

FederationLog is used to keep track of the set Universe servers that comprise our current federation. This'll be used by the AutoSyncer to periodically push and sync new proof events against the federation.

type FederationProofBatchPushReq added in v0.3.1 

type FederationProofBatchPushReq struct {
	Batch []*Item
	// contains filtered or unexported fields
}

FederationProofBatchPushReq is used to push out a batch of universe proof leaves to all or some members of the federation.

type FederationProofSyncLog added in v0.3.3 

type FederationProofSyncLog interface {
	// UpsertFederationProofSyncLog upserts a federation proof sync log
	// entry for a given universe server and proof.
	UpsertFederationProofSyncLog(ctx context.Context, uniID Identifier,
		leafKey LeafKey, addr ServerAddr, syncDirection SyncDirection,
		syncStatus ProofSyncStatus,
		bumpSyncAttemptCounter bool) (int64, error)

	// QueryFederationProofSyncLog queries the federation proof sync log and
	// returns the log entries which correspond to the given universe proof
	// leaf.
	QueryFederationProofSyncLog(ctx context.Context, uniID Identifier,
		leafKey LeafKey, syncDirection SyncDirection,
		syncStatus ProofSyncStatus) ([]*ProofSyncLogEntry, error)

	// FetchPendingProofsSyncLog queries the federation proof sync log and
	// returns all log entries with sync status pending.
	FetchPendingProofsSyncLog(ctx context.Context,
		syncDirection *SyncDirection) ([]*ProofSyncLogEntry, error)

	// DeleteProofsSyncLogEntries deletes proof sync log entries.
	DeleteProofsSyncLogEntries(ctx context.Context,
		servers ...ServerAddr) error
}

FederationProofSyncLog is used for CRUD operations relating to the federation proof sync log.

type FederationPushReq 

type FederationPushReq struct {
	// ID identifies the Universe tree to push this new update out to.
	ID Identifier

	// Key is the leaf key in the Universe that the new leaf should be
	// added to.
	Key LeafKey

	// Leaf is the new leaf to add.
	Leaf *Leaf

	// LogProofSync is a boolean that indicates, if true, that the proof
	// leaf sync attempt should be logged and actively managed to ensure
	// that the federation push procedure is repeated in the event of a
	// failure.
	LogProofSync bool
	// contains filtered or unexported fields
}

FederationPushReq is used to push out new updates to all or some members of the federation.

type FederationSyncConfigDB added in v0.3.0 

type FederationSyncConfigDB interface {
	// QueryFederationSyncConfigs returns the global and universe specific
	// federation sync configs.
	QueryFederationSyncConfigs(ctx context.Context) ([]*FedGlobalSyncConfig,
		[]*FedUniSyncConfig, error)

	// UpsertFederationSyncConfig upserts both global and universe specific
	// federation sync configs.
	UpsertFederationSyncConfig(
		ctx context.Context, globalSyncConfigs []*FedGlobalSyncConfig,
		uniSyncConfigs []*FedUniSyncConfig) error
}

FederationSyncConfigDB is used to manage the set of Universe servers as part of a federation.

type GenesisWithGroup 

type GenesisWithGroup struct {
	asset.Genesis

	*asset.GroupKey
}

GenesisWithGroup is a two tuple that groups the genesis of an asset with the group key it's associated with (if that exists).

type GroupedStats added in v0.2.3 

type GroupedStats struct {
	AggregateStats

	// Date is the string formatted date (YYYY-MM-DD) that the stats are
	// for.
	Date string
}

GroupedStats is a type for aggregated stats grouped by day.

type GroupedStatsQuery added in v0.2.3 

type GroupedStatsQuery struct {
	// StartTime is the start time to use when querying for stats.
	StartTime time.Time

	// EndTime is the end time to use when querying for stats.
	EndTime time.Time
}

GroupedStatsQuery packages a set of query parameters to retrieve event based stats.

type Identifier 

type Identifier struct {
	// AssetID is the asset ID for the universe.
	//
	// TODO(roasbeef): make both pointers?
	AssetID asset.ID

	// GroupKey is the group key for the universe.
	GroupKey *btcec.PublicKey

	// ProofType is the type of proof that should be stored in the universe.
	ProofType ProofType
}

Identifier is the identifier for a universe.

func NewUniIDFromAsset added in v0.3.3 

func NewUniIDFromAsset(a asset.Asset) Identifier

NewUniIDFromAsset creates a new universe ID from an asset.

func NewUniIDFromRawArgs added in v0.3.3 

func NewUniIDFromRawArgs(assetIDBytes []byte, groupKeyBytes []byte,
	proofTypeStr string) (Identifier, error)

NewUniIDFromRawArgs creates a new universe ID from the raw arguments. The asset ID bytes and group key bytes are mutually exclusive. If the group key bytes are set, then the asset ID bytes will be ignored. This function is useful in deriving a universe ID from the data stored in the database.

func (*Identifier) Bytes added in v0.3.0 

func (i *Identifier) Bytes() [32]byte

Bytes returns a bytes representation of the ID.

func (*Identifier) IsEqual added in v0.4.0 

func (i *Identifier) IsEqual(other Identifier) bool

IsEqual returns true if the two identifiers are equal.

func (*Identifier) Key 

func (i *Identifier) Key() IdentifierKey

Key returns a bytes representation of the ID with the proof type appended to the end. This contains the same information as the String method, but in a way more compact form (42 bytes less), so it can be used as a map key.

func (*Identifier) String 

func (i *Identifier) String() string

String returns a string representation of the ID.

func (*Identifier) StringForLog added in v0.2.1 

func (i *Identifier) StringForLog() string

StringForLog returns a string representation of the ID for logging.

type IdentifierKey 

type IdentifierKey [33]byte

IdentifierKey is the compact representation of a universe identifier that can be used as a map key.

type Item added in v0.3.1 

type Item struct {
	// ID is the identifier of the asset (group) specific universe.
	ID Identifier

	// Key is the key that the leaf is or will be stored at.
	Key LeafKey

	// Leaf is the proof leaf which will be stored at the key.
	Leaf *Leaf

	// MetaReveal is the meta reveal associated with the given proof leaf.
	MetaReveal *proof.MetaReveal

	// LogProofSync is a boolean that indicates, if true, that the proof
	// leaf sync attempt should be logged and actively managed to ensure
	// that the federation push procedure is repeated in the event of a
	// failure.
	LogProofSync bool
}

Item contains the data fields necessary to insert/update a proof leaf within a multiverse and the related asset (group) specific universe.

type Leaf added in v0.3.0 

type Leaf struct {
	GenesisWithGroup

	// RawProof is either an issuance proof or a transfer proof associated
	// with/ the issuance or spend event which this leaf represents.
	RawProof proof.Blob

	// Asset is the asset that the leaf is associated with.
	Asset *asset.Asset

	// Amt is the amount of units associated with the coin.
	Amt uint64
}

Leaf is a leaf node in the SMT that represents an asset issuance or transfer. For each asset issued or transferred for a given universe, a new leaf is created.

func (*Leaf) SmtLeafNode added in v0.3.0 

func (m *Leaf) SmtLeafNode() *mssmt.LeafNode

SmtLeafNode returns the SMT leaf node for the given leaf.

type LeafKey added in v0.3.0 

type LeafKey struct {
	// OutPoint is the outpoint at which the asset referenced by this key
	// resides.
	OutPoint wire.OutPoint

	// ScriptKey is the script key of the base asset. If this isn't
	// specified, then the caller is attempting to query for all the script
	// keys at that minting outpoint.
	ScriptKey *asset.ScriptKey
}

LeafKey is the top level leaf key for a universe. This will be used to key into a universe's MS-SMT data structure. The final serialized key is: sha256(mintingOutpoint || scriptKey). This ensures that all leaves for a given asset will be uniquely keyed in the universe tree.

func (LeafKey) UniverseKey added in v0.3.0 

func (b LeafKey) UniverseKey() [32]byte

UniverseKey is the key for a universe.

type MultiverseArchive added in v0.3.0 

type MultiverseArchive interface {
	// RootNodes returns the complete set of known root nodes for the set
	// of assets tracked in the base Universe.
	RootNodes(ctx context.Context, q RootNodesQuery) ([]Root, error)

	// UpsertProofLeaf upserts a proof leaf within the multiverse tree and
	// the universe tree that corresponds to the given key.
	UpsertProofLeaf(ctx context.Context, id Identifier, key LeafKey,
		leaf *Leaf,
		metaReveal *proof.MetaReveal) (*Proof, error)

	// UpsertProofLeafBatch upserts a proof leaf batch within the multiverse
	// tree and the universe tree that corresponds to the given key(s).
	UpsertProofLeafBatch(ctx context.Context, items []*Item) error

	// FetchProofLeaf returns a proof leaf for the target key. If the key
	// doesn't have a script key specified, then all the proof leafs for the
	// minting outpoint will be returned. If neither are specified, then all
	// inserted proof leafs will be returned.
	FetchProofLeaf(ctx context.Context, id Identifier,
		key LeafKey) ([]*Proof, error)

	// DeleteUniverse deletes all leaves, and the root, for given universe.
	DeleteUniverse(ctx context.Context, id Identifier) (string, error)

	// UniverseRootNode returns the Universe root node for the given asset
	// ID.
	UniverseRootNode(ctx context.Context, id Identifier) (Root, error)

	// UniverseLeafKeys returns the set of leaf keys for the given
	// universe.
	UniverseLeafKeys(ctx context.Context,
		q UniverseLeafKeysQuery) ([]LeafKey, error)

	// FetchLeaves returns the set of multiverse leaves that satisfy the set
	// of universe targets. If the set of targets is empty, all leaves for
	// the given proof type will be returned.
	FetchLeaves(ctx context.Context, universeTargets []MultiverseLeafDesc,
		proofType ProofType) ([]MultiverseLeaf, error)

	// MultiverseRootNode returns the Multiverse root node for the given
	// proof type.
	MultiverseRootNode(ctx context.Context,
		proofType ProofType) (fn.Option[MultiverseRoot], error)
}

MultiverseArchive is an interface used to keep track of the set of universe roots that we know of. The BaseBackend interface is used to interact with a particular base universe, while this is used to obtain aggregate information about the universes.

type MultiverseLeaf added in v0.4.0 

type MultiverseLeaf struct {
	// ID contains the information to uniquely identify the multiverse
	// root: assetID/groupKey and the proof type.
	ID Identifier

	*mssmt.LeafNode
}

MultiverseLeaf is the leaf within a Multiverse, this stores a value which is derived from the root of a normal Universe tree.

type MultiverseLeafDesc added in v0.4.0 

type MultiverseLeafDesc = fn.Either[asset.ID, btcec.PublicKey]

MultiverseLeafDesc can be used to uniquely identify a Multiverse leave (which is a Universe root). A leaf for a given Universe tree (proof type assumed) can be identified by either the asset ID or the target group key.

type MultiverseRoot added in v0.3.0 

type MultiverseRoot struct {
	// ProofType is the types of proofs that've been stored in the
	// multiverse.
	ProofType ProofType

	mssmt.Node
}

MultiverseRoot is the ms-smt root for a multiverse. This root can be used to authenticate any leaf proofs.

type Proof added in v0.3.0 

type Proof struct {
	// Leaf is the leaf node for the asset within the universe tree.
	Leaf *Leaf

	// LeafKey is the universe leaf key for the asset issuance or spend.
	LeafKey LeafKey

	// UniverseRoot is the root of the universe that the asset is located
	// within.
	UniverseRoot mssmt.Node

	// UniverseInclusionProof is the universe inclusion proof for the asset
	// within the universe tree.
	UniverseInclusionProof *mssmt.Proof

	// MultiverseRoot is the root of the multiverse tree that the asset is
	// located within.
	MultiverseRoot mssmt.Node

	// MultiverseInclusionProof is the inclusion proof for the asset within
	// the multiverse tree.
	MultiverseInclusionProof *mssmt.Proof
}

Proof associates a universe leaf (and key) with its corresponding multiverse and universe inclusion proofs.

These inclusion proofs can be used to verify that a valid asset exists (based on the proof in the leaf), and that the asset is committed to within the universe root and multiverse root.

func (*Proof) VerifyRoot added in v0.3.0 

func (i *Proof) VerifyRoot(expectedRoot mssmt.Node) bool

VerifyRoot verifies that the inclusion proof for the root node matches the specified root. This is useful for sanity checking an issuance proof against the purported root, and the included leaf.

type ProofSyncLogEntry added in v0.3.3 

type ProofSyncLogEntry struct {
	// Timestamp is the timestamp of the log entry.
	Timestamp time.Time

	// SyncStatus is the status of the sync.
	SyncStatus ProofSyncStatus

	// SyncDirection is the direction of the sync.
	SyncDirection SyncDirection

	// AttemptCounter is the number of times the sync has been attempted.
	AttemptCounter int64

	// ServerAddr is the address of the sync counterparty server.
	ServerAddr ServerAddr

	// UniID is the identifier of the universe associated with the sync event.
	UniID Identifier

	// LeafKey is the leaf key associated with the sync event.
	LeafKey LeafKey

	// Leaf is the leaf associated with the sync event.
	Leaf Leaf
}

ProofSyncLogEntry is a log entry for a proof sync.

type ProofSyncStatus added in v0.3.3 

type ProofSyncStatus string

ProofSyncStatus is the status of a proof sync. 

const (
	// ProofSyncStatusPending indicates that the sync is pending.
	ProofSyncStatusPending ProofSyncStatus = "pending"

	// ProofSyncStatusComplete indicates that the sync is complete.
	ProofSyncStatusComplete ProofSyncStatus = "complete"
)

func ParseStrProofSyncStatus added in v0.3.3 

func ParseStrProofSyncStatus(s string) (ProofSyncStatus, error)

ParseStrProofSyncStatus parses a string into a ProofSyncStatus.

type ProofType added in v0.3.0 

type ProofType uint8

ProofType is an enum that describes the type of proof which can be stored in a given universe. 

const (
	// ProofTypeUnspecified signifies an unspecified proof type.
	ProofTypeUnspecified ProofType = iota

	// ProofTypeIssuance corresponds to the issuance proof type.
	ProofTypeIssuance

	// ProofTypeTransfer corresponds to the transfer proof type.
	ProofTypeTransfer
)

func NewProofTypeFromAsset added in v0.3.1 

func NewProofTypeFromAsset(a *asset.Asset) (ProofType, error)

NewProofTypeFromAsset returns the proof type for the given asset proof.

func ParseStrProofType added in v0.3.0 

func ParseStrProofType(typeStr string) (ProofType, error)

ParseStrProofType returns the proof type corresponding to the given string.

func (ProofType) String added in v0.3.0 

func (t ProofType) String() string

String returns a human-readable string representation of the proof type.

type Registrar 

type Registrar interface {
	// UpsertProofLeaf upserts a proof leaf within the target universe tree.
	UpsertProofLeaf(ctx context.Context, id Identifier, key LeafKey,
		leaf *Leaf) (*Proof, error)

	// Close is used to shutdown the active registrar instance.
	Close() error
}

Registrar is an interface that allows a caller to upsert a proof leaf in a local/remote universe instance.

type Root added in v0.3.1 

type Root struct {
	ID Identifier

	mssmt.Node

	// AssetName is the name of the asset. This might not always be set for
	// performance reasons.
	AssetName string

	// GroupedAssets is an optional map of asset IDs to the minted amount.
	// This is only set for grouped assets.
	GroupedAssets map[asset.ID]uint64
}

Root is the ms-smt root for a universe. This root can be used to compare against other trackers of a universe to find discrepancies (unknown issuance events, etc).

type RootNodesQuery added in v0.3.1 

type RootNodesQuery struct {
	WithAmountsById bool
	SortDirection   SortDirection
	Offset          int32
	Limit           int32
}

type ServerAddr 

type ServerAddr struct {
	// ID is the unique identifier of the remote universe.
	ID int64
	// contains filtered or unexported fields
}

ServerAddr wraps the reachable network address of a remote universe server.

func NewServerAddr 

func NewServerAddr(i int64, s string) ServerAddr

NewServerAddr creates a new server address from both the universe addr ID and the host name string.

func NewServerAddrFromStr 

func NewServerAddrFromStr(s string) ServerAddr

NewServerAddrFromStr creates a new server address from a string that is the host name of the remote universe server.

func (*ServerAddr) Addr 

func (s *ServerAddr) Addr() (net.Addr, error)

Addr returns the net.addr the universe is hosted at.

func (*ServerAddr) HostStr 

func (s *ServerAddr) HostStr() string

HostStr returns the host string of the remote universe server.

type SimpleSyncCfg 

type SimpleSyncCfg struct {
	// LocalDiffEngine is the diff engine tied to a local Universe
	// instance.
	LocalDiffEngine DiffEngine

	// NewRemoteDiffEngine is a function that returns a new diff engine
	// tied to the remote Universe instance we want to sync with.
	NewRemoteDiffEngine func(ServerAddr) (DiffEngine, error)

	// LocalRegistrar is the registrar tied to a local Universe instance.
	// This is used to insert new proof into the local DB as a result of
	// the diff operation.
	LocalRegistrar BatchRegistrar

	// SyncBatchSize is the number of items to sync in a single batch.
	SyncBatchSize int
}

SimpleSyncCfg contains all the configuration needed to create a new SimpleSyncer.

type SimpleSyncer 

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

SimpleSyncer is a simple implementation of the Syncer interface. It's based on a set difference operation between the local and remote Universe.

func NewSimpleSyncer 

func NewSimpleSyncer(cfg SimpleSyncCfg) *SimpleSyncer

NewSimpleSyncer creates a new SimpleSyncer instance.

func (*SimpleSyncer) SyncUniverse 

func (s *SimpleSyncer) SyncUniverse(ctx context.Context, host ServerAddr,
	syncType SyncType, syncConfigs SyncConfigs,
	idsToSync ...Identifier) ([]AssetSyncDiff, error)

SyncUniverse attempts to synchronize the local universe with the remote universe, governed by the sync type and the set of universe IDs to sync.

type SortDirection added in v0.3.0 

type SortDirection uint8

SortDirection is an enum used to specify the sort direction of the returned. 

const (
	// SortAscending is a sentinel value that indicates that the sort
	// should be in ascending order.
	SortAscending SortDirection = iota

	// SortDescending is a sentinel value that indicates that the sort
	// should be in descending order.
	SortDescending
)

type SyncConfigs added in v0.3.0 

type SyncConfigs struct {
	// GlobalSyncConfigs are the global proof type specific configs.
	GlobalSyncConfigs []*FedGlobalSyncConfig

	// UniSyncConfigs are the universe specific configs.
	UniSyncConfigs []*FedUniSyncConfig
}

SyncConfigs is a set of configs that are used to control which universes to synchronize with the federation.

func (*SyncConfigs) IsSyncExportEnabled added in v0.3.0 

func (s *SyncConfigs) IsSyncExportEnabled(id Identifier) bool

IsSyncExportEnabled returns true if the given universe is configured to allow export (from this server) synchronization with the federation.

func (*SyncConfigs) IsSyncInsertEnabled added in v0.3.0 

func (s *SyncConfigs) IsSyncInsertEnabled(id Identifier) bool

IsSyncInsertEnabled returns true if the given universe is configured to allow insert (into this server) synchronization with the federation.

type SyncDirection added in v0.3.3 

type SyncDirection string

SyncDirection is the direction of a proof sync. 

const (
	// SyncDirectionPush indicates that the sync is a push sync (from the local
	// server to the remote server).
	SyncDirectionPush SyncDirection = "push"

	// SyncDirectionPull indicates that the sync is a pull sync (from the remote
	// server to the local server).
	SyncDirectionPull SyncDirection = "pull"
)

func ParseStrSyncDirection added in v0.3.3 

func ParseStrSyncDirection(s string) (SyncDirection, error)

ParseStrSyncDirection parses a string into a SyncDirection.

type SyncStatsQuery 

type SyncStatsQuery struct {
	// AssetNameFilter can be used to filter for stats for a given asset name.
	AssetNameFilter string

	// AssetIDFilter can be used to filter for stats for a given asset ID.
	AssetIDFilter asset.ID

	// AssetTypeFilter can be used to filter for stats for a given asset
	// type.
	AssetTypeFilter *asset.Type

	// SortBy is the sort order to use when returning the stats.
	SortBy SyncStatsSort

	// SortDirection is the sort direction to use when returning the stats.
	SortDirection SortDirection

	// Offset is the offset to use when returning the stats. This can be
	// used to paginate the response.
	Offset int

	// Limit is the maximum number of stats to return. This can be used to
	// paginate the response.
	Limit int
}

SyncStatsQuery packages a set of query parameters to retrieve stats related to the sync activity of a given Universe. Any of the filters can be specified, however only a single sort by value should be specified. The offset and limit fields can be used to implement pagination.

type SyncStatsSort 

type SyncStatsSort uint8

SyncStatsSort is an enum used to specify the sort order of the returned sync stats. 

const (
	// SortByNone is a sentinel value that indicates that no sorting should
	// be done.
	SortByNone SyncStatsSort = iota

	// SortByAssetName sorts the returned stats by the asset name.
	SortByAssetName

	// SortByAssetType sorts the returned stats by the asset type.
	SortByAssetType

	// SortByAssetID sorts the returned stats by the asset ID.
	SortByAssetID

	// SortByTotalSyncs sorts the returned stats by the total number of
	// syncs.
	SortByTotalSyncs

	// SortByTotalProofs sorts the returned stats by the total number of
	// proofs.
	SortByTotalProofs

	// SortByGenesisHeight sorts the returned stats by the genesis height.
	SortByGenesisHeight

	// SortByTotalSupply sorts the returned stats by the total supply.
	SortByTotalSupply
)

type SyncType 

type SyncType uint8

SyncType is an enum that describes the type of sync that should be performed between a local and remote universe. 

const (
	// SyncIssuance is a sync that will only sync new asset issuance events.
	SyncIssuance SyncType = iota

	// SyncFull is a sync that will sync all the assets in the universe.
	SyncFull
)

func (SyncType) String 

func (s SyncType) String() string

String returns a human-readable string representation of the sync type.

type Syncer 

type Syncer interface {
	// SyncUniverse attempts to synchronize the local universe with the
	// remote universe, governed by the sync type and the set of universe
	// IDs to sync.
	SyncUniverse(ctx context.Context, host ServerAddr,
		syncType SyncType, syncConfigs SyncConfigs,
		idsToSync ...Identifier) ([]AssetSyncDiff, error)
}

Syncer is used to synchronize the state of two Universe instances: a local instance and a remote instance. As a Universe is a tree based structure, tree based bisection can be used to find the point of divergence with syncing happening once that's found.

type Telemetry 

type Telemetry interface {
	// AggregateSyncStats returns stats aggregated over all assets within
	// the Universe.
	AggregateSyncStats(ctx context.Context) (AggregateStats, error)

	// LogSyncEvent logs a sync event for the target universe.
	//
	// TODO(roasbeef): log based on a given leaf, or entire tree?
	//  * rn main entrypoint is in RPC server, which is leaf based
	//  * alternatively, can log when a set of leaves are queried, as
	//    that's still a sync event, but can be a noop
	LogSyncEvent(ctx context.Context, uniID Identifier,
		key LeafKey) error

	// LogSyncEvents logs sync events for the target universe.
	LogSyncEvents(ctx context.Context, uniIDs ...Identifier) error

	// LogNewProofEvent logs a new proof insertion event for the target
	// universe.
	LogNewProofEvent(ctx context.Context, uniID Identifier,
		key LeafKey) error

	// LogNewProofEvents logs new proof insertion events for the target
	// universe.
	LogNewProofEvents(ctx context.Context, uniIDs ...Identifier) error

	// QuerySyncStats attempts to query the stats for the target universe.
	// For a given asset ID, tag, or type, the set of universe stats is
	// returned which lists information such as the total number of syncs
	// and known proofs for a given Universe server instance.
	QuerySyncStats(ctx context.Context,
		q SyncStatsQuery) (*AssetSyncStats, error)

	// QueryAssetStatsPerDay returns the stats for all assets grouped by
	// day.
	QueryAssetStatsPerDay(ctx context.Context,
		q GroupedStatsQuery) ([]*GroupedStats, error)
}

Telemetry it a type used by the Universe syncer and base universe to export telemetry information about the sync process. This logs events of new proofs, and also sync events for entire asset trees.

TODO(roasbeef): prob want to add a wrapper around multiple instances, eg: to the main db and also prometheus or w/e

type UniverseKey added in v0.3.0 

type UniverseKey [32]byte

UniverseKey represents the key used to locate an item within a universe.

type UniverseLeafKeysQuery added in v0.3.1 

type UniverseLeafKeysQuery struct {
	Id            Identifier
	SortDirection SortDirection
	Offset        int32
	Limit         int32
}

Source Files

View all Source files

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.