universe

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
}

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

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

	// 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
}

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
}

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
}

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
}

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)
}

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
}

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)
}

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

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
}

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
}

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
}

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
}

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
}

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
}

type FederationDB interface {
	FederationLog
	FederationProofSyncLog
	FederationSyncConfigDB
}

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

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
}

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

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
}

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
}

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
}

type GenesisWithGroup struct {
	asset.Genesis

	*asset.GroupKey
}

type GroupedStats struct {
	AggregateStats

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

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
}

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
}

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
}

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
}

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
}

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)
}

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

	mssmt.Node
}

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
}

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
}

type ProofSyncStatus string

type ProofType uint8

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
}

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
}

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

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

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
}

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

type SortDirection uint8

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

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

type SyncDirection string

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
}

type SyncStatsSort uint8

type SyncType uint8

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)
}

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)
}

type UniverseKey [32]byte

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