address

type AddrWithKeyInfo struct {
	*Tap

	// ScriptKeyTweak houses the wallet specific information related to a
	// tweak key. This includes the raw key desc information along with the
	// tweak used to create the address.
	ScriptKeyTweak asset.TweakedScriptKey

	// InternalKeyDesc is the key desc for the internal key.
	InternalKeyDesc keychain.KeyDescriptor

	// TaprootOutputKey is the tweaked taproot output key that assets must
	// be sent to on chain to be received.
	TaprootOutputKey btcec.PublicKey

	// CreationTime is the time the address was created in the database.
	CreationTime time.Time

	// ManagedAfter is the time at which the address was imported into the
	// wallet.
	ManagedAfter time.Time
}

type AssetOutput struct {
	// Amount is the amount of this asset output.
	Amount uint64

	// ScriptKey is the serialized script key that can be used to spend the
	// output.
	ScriptKey asset.ScriptKey
}

type AssetSyncer interface {
	// SyncAssetInfo queries the universes in our federation for genesis
	// and asset group information about the given asset.
	SyncAssetInfo(ctx context.Context, specifier asset.Specifier) error

	// EnableAssetSync updates the sync config for the given asset so that
	// we sync future issuance proofs.
	EnableAssetSync(ctx context.Context, groupInfo *asset.AssetGroup) error
}

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

type BookConfig struct {
	// Store holds the set of created addresses.
	Store Storage

	// Syncer allows the address.Book to sync issuance information for
	// assets from universe servers in our federation.
	Syncer AssetSyncer

	// KeyRing points to an active key ring instance.
	KeyRing KeyRing

	// Chain points to the chain the address.Book is active on.
	Chain ChainParams

	// StoreTimeout is the default timeout to use for any storage
	// interaction.
	StoreTimeout time.Duration
}

type ChainParams struct {
	*chaincfg.Params

	// TapHRP is the HRP to use for Taproot Asset addresses for the target
	// network.
	TapHRP string
}

type DelegationKeyChecker interface {
	// HasDelegationKey checks if we control the delegation key for the
	// given asset ID. Returns true if we have the private key for the
	// asset's delegation key, false otherwise.
	HasDelegationKey(ctx context.Context, assetID asset.ID) (bool, error)
}

type ErrorTestCase struct {
	Address *TestAddress `json:"address"`
	Error   string       `json:"error"`
	Comment string       `json:"comment"`
}

type Event struct {
	// ID is the database primary key ID of the address event.
	ID int64

	// CreationTime is the time the event was first created.
	CreationTime time.Time

	// Addr is the Taproot Asset address that was used to receive the
	// assets.
	Addr *AddrWithKeyInfo

	// Status represents the current status of the incoming assets.
	Status Status

	// Outpoint is the on-chain transaction outpoint that contains the
	// Taproot Asset commitment for the incoming asset transfer.
	Outpoint wire.OutPoint

	// Amt is the amount of satoshis that were transferred in the Bitcoin
	// on-chain transaction. This is independent of the asset amount, which
	// can be looked up through the Addr field.
	Amt btcutil.Amount

	// InternalKey is the key used as the internal key for the on-chain
	// Taproot output. The internal key tweaked with the Taproot Asset
	// commitment (when NO tapscript sibling if present) is equal to the
	// TaprootOutputKey of the Addr.
	InternalKey *btcec.PublicKey

	// The map of asset ID to AssetOutput that contains the amount and
	// script key of each asset output that was sent as part of the incoming
	// asset transfer.
	Outputs map[asset.ID]AssetOutput

	// ConfirmationHeight is the block height at which the incoming asset
	// transfer transaction was first confirmed.
	ConfirmationHeight uint32

	// HasAllProofs indicates that a proof for each output of this transfer
	// was imported. We don't keep a reference to them in memory as the
	// proofs themselves can be large. The proofs can be fetched by the
	// script keys of the address.
	HasAllProofs bool
}

type EventQueryParams struct {
	// AddrTaprootOutputKey is the optional 32-byte x-only serialized
	// Taproot output key of the address to filter by. Must be set to nil
	// to return events for all addresses.
	AddrTaprootOutputKey []byte

	// StatusFrom is the smallest status to query for (inclusive). Can be
	// set to nil to return events of all states.
	StatusFrom *Status

	// StatusTo is the largest status to query for (inclusive). Can be
	// set to nil to return events of all states.
	StatusTo *Status

	// CreationTimeFrom is the earliest creation time to query for
	// (inclusive). Can be set to nil to return events of all creation
	// times.
	CreationTimeFrom *time.Time

	// CreationTimeTo is the latest creation time to query for
	// (inclusive). Can be set to nil to return events of all creation
	// times.
	CreationTimeTo *time.Time
}

type EventStorage interface {
	// GetOrCreateEvent creates a new address event for the given status,
	// address and transaction. If an event for that address and transaction
	// already exists, then the status and transaction information is
	// updated instead.
	GetOrCreateEvent(ctx context.Context, status Status,
		transfer IncomingTransfer) (*Event, error)

	// QueryAddrEvents returns a list of event that match the given query
	// parameters.
	QueryAddrEvents(ctx context.Context, params EventQueryParams) ([]*Event,
		error)

	// QueryEvent returns a single address event by its address and
	// outpoint.
	QueryEvent(ctx context.Context, addr *AddrWithKeyInfo,
		outpoint wire.OutPoint) (*Event, error)

	// CompleteEvent updates an address event as being complete and links it
	// with the proof and asset that was imported/created for it.
	CompleteEvent(ctx context.Context, event *Event, status Status,
		anchorPoint wire.OutPoint) error
}

type IncomingTransfer struct {
	// Addr is the Taproot Asset address that was used to receive the
	// assets.
	Addr *AddrWithKeyInfo

	// Tx is the on-chain transaction that contains the Taproot Asset
	// commitment for the incoming asset transfer.
	Tx *wire.MsgTx

	// OutputIdx is the index of the output in the transaction that contains
	// the Taproot Asset commitment for the incoming asset transfer.
	OutputIdx uint32

	// CommitmentVersion is the version of the Taproot Asset commitment
	// that was used to create the Taproot Asset address.
	CommitmentVersion commitment.TapCommitmentVersion

	// TaprootAssetRoot is the root of the Taproot Asset commitment tree
	// that was used to create the Taproot Asset address.
	TaprootAssetRoot [sha256.Size]byte

	// BlockHeight is the height of the block that contains the transaction.
	BlockHeight uint32

	// BlockHash is the hash of the block that contains the transaction.
	BlockHash *chainhash.Hash

	// Outputs is a map of asset IDs to the outputs that are being sent.
	Outputs map[asset.ID]AssetOutput
}

type KeyRing interface {
	// DeriveNextTaprootAssetKey attempts to derive the *next* key within
	// the TaprootAsset key family.
	DeriveNextTaprootAssetKey(context.Context) (keychain.KeyDescriptor,
		error)

	// DeriveNextKey attempts to derive the *next* key within the key
	// family (account in BIP43) specified. This method should return the
	// next external child within this branch.
	DeriveNextKey(context.Context,
		keychain.KeyFamily) (keychain.KeyDescriptor, error)

	// IsLocalKey returns true if the key is under the control of the wallet
	// and can be derived by it.
	IsLocalKey(ctx context.Context, desc keychain.KeyDescriptor) bool
}

type NewAddrOpt func(*newAddrOptions)

type NewAddressParams struct {
	// Version is the version of the address to create.
	Version Version

	// ChainParams is the chain parameters that the address will be used on.
	ChainParams *ChainParams

	// Amount is the number of asset units being requested by the receiver.
	// The amount is allowed to be zero for V2 addresses, where the sender
	// can choose the amount to send.
	Amount uint64

	// Genesis is the asset genesis metadata that this address is created
	// for. This is used to derive the asset ID of the address and is
	// optional for V2 addresses that have a group key set.
	Genesis asset.Genesis

	// GroupKey is the asset group key that is used to receive assets. For
	// V0/V1 addresses, this is purely informational and is not used. For V2
	// addresses this must be used for assets that belong to a group, as
	// receiving through just a single asset ID is not desired for grouped
	// assets.
	GroupKey *btcec.PublicKey

	// GroupWitness is the witness that proves the group key is valid. This
	// must only be set if the GroupKey is set.
	GroupWitness wire.TxWitness

	// ScriptKey is the Taproot output key that is used to lock the assets
	// received to this address.
	ScriptKey btcec.PublicKey

	// InternalKey is the on-chain Taproot internal key that is used to
	// derive the Taproot output key for the address.
	InternalKey btcec.PublicKey

	// TapscriptSibling is the tapscript sibling preimage of the script that
	// will be committed to alongside the assets received through this
	// address. This is optional and can be nil if no tapscript sibling is
	// desired. If set, it must be a valid tapscript sibling that is not a
	// Taproot Asset commitment.
	TapscriptSibling *commitment.TapscriptPreimage

	// ProofCourierAddr is the address of the proof courier that will be
	// used to distribute related proofs for this address.
	ProofCourierAddr url.URL
}

type QueryParams struct {
	// CreatedAfter if set, only addresses created after the time will be
	// returned.
	CreatedAfter time.Time

	// CreatedBefore is set, only the addresses created before the time
	// will be returned.
	CreatedBefore time.Time

	// Limit if set, only this many addresses will be returned.
	Limit int32

	// Offset if set, then the final result will be offset by this many
	// addresses.
	Offset int32

	// UnmanagedOnly is a boolean pointer indicating whether only addresses
	// should be returned that are not yet managed by the wallet.
	UnmanagedOnly bool
}

type Status uint8

type Storage interface {
	EventStorage

	// InsertAddrs inserts a series of addresses into the database.
	InsertAddrs(ctx context.Context, addrs ...AddrWithKeyInfo) error

	// QueryAddrs attempts to query for a set of addresses.
	QueryAddrs(ctx context.Context,
		params QueryParams) ([]AddrWithKeyInfo, error)

	// QueryAssetGroup attempts to locate the asset group information
	// (genesis + group key) associated with a given asset specifier.
	QueryAssetGroup(context.Context, asset.Specifier) (*asset.AssetGroup,
		error)

	// QueryAssetGroupByID attempts to locate the asset group information
	// (genesis + group key) associated with a given asset.
	QueryAssetGroupByID(context.Context, asset.ID) (*asset.AssetGroup,
		error)

	// QueryAssetGroupByGroupKey fetches the asset group with a matching
	// tweaked key, including the genesis information used to create the
	// group.
	QueryAssetGroupByGroupKey(context.Context,
		*btcec.PublicKey) (*asset.AssetGroup, error)

	// FetchAssetMetaByHash attempts to fetch an asset meta based on an
	// asset hash.
	FetchAssetMetaByHash(ctx context.Context,
		metaHash [asset.MetaHashLen]byte) (*proof.MetaReveal, error)

	// FetchAssetMetaForAsset attempts to fetch an asset meta based on an
	// asset ID.
	FetchAssetMetaForAsset(ctx context.Context,
		assetID asset.ID) (*proof.MetaReveal, error)

	// AddrByTaprootOutput returns a single address based on its Taproot
	// output key or a sql.ErrNoRows error if no such address exists.
	AddrByTaprootOutput(ctx context.Context,
		key *btcec.PublicKey) (*AddrWithKeyInfo, error)

	// AddrByScriptKeyAndVersion returns a single address based on its
	// script key and version or a sql.ErrNoRows error if no such address
	// exists.
	AddrByScriptKeyAndVersion(context.Context, *btcec.PublicKey,
		Version) (*AddrWithKeyInfo, error)

	// SetAddrManaged sets an address as being managed by the internal
	// wallet.
	SetAddrManaged(ctx context.Context, addr *AddrWithKeyInfo,
		managedFrom time.Time) error

	// LastEventHeightByVersion returns the last event height for a given
	// address version.
	LastEventHeightByVersion(ctx context.Context,
		version Version) (uint32, error)

	// InsertInternalKey inserts an internal key into the database to make
	// sure it is identified as a local key later on when importing proofs.
	// The key can be an internal key for an asset script key or the
	// internal key of an anchor output.
	InsertInternalKey(ctx context.Context,
		keyDesc keychain.KeyDescriptor) error

	// InsertScriptKey inserts an address related script key into the
	// database, so it can be recognized as belonging to the wallet when a
	// transfer comes in later on.
	InsertScriptKey(ctx context.Context, scriptKey asset.ScriptKey,
		keyType asset.ScriptKeyType) error

	// FetchAllAssetMeta attempts to fetch all asset meta known to the
	// database.
	FetchAllAssetMeta(
		ctx context.Context) (map[asset.ID]*proof.MetaReveal, error)

	// FetchInternalKeyLocator attempts to fetch the key locator information
	// for the given raw internal key. If the key cannot be found, then
	// ErrInternalKeyNotFound is returned.
	FetchInternalKeyLocator(ctx context.Context,
		rawKey *btcec.PublicKey) (keychain.KeyLocator, error)
}

type Tap struct {
	// Version is the version of the address.
	Version Version

	// ChainParams is the reference to the chain parameters that were used
	// to encode the Taproot Asset address.
	ChainParams *ChainParams

	// AssetVersion is the Taproot Asset version of the asset.
	AssetVersion asset.Version

	// AssetID is the asset ID of the asset. This will be all zeroes for
	// V2 addresses that have a group key set.
	AssetID asset.ID

	// GroupKey is the tweaked public key that is used to associate assets
	// together across distinct asset IDs, allowing further issuance of the
	// asset to be made possible.
	GroupKey *btcec.PublicKey

	// ScriptKey represents the asset's Taproot output key encumbering the
	// different ways an asset can be spent. This is different for V2
	// addresses, where this key is not the Taproot output key but the
	// Taproot internal key (the bare/raw key) of the asset script key (not
	// to be confused with the InternalKey below, which is for the on-chain
	// part of the address). The sender will use this key to encrypt the
	// send fragment that they post to the proof courier's mailbox. The raw
	// script key will also be used by the sender to derive different
	// Taproot output script keys for each asset ID.
	ScriptKey btcec.PublicKey

	// InternalKey is the BIP-0340/0341 public key of the receiver.
	InternalKey btcec.PublicKey

	// TapscriptSibling is the tapscript sibling preimage of the script that
	// will be committed to alongside the assets received through this
	// address. This will usually be empty.
	TapscriptSibling *commitment.TapscriptPreimage

	// Amount is the number of asset units being requested by the receiver.
	// The amount is allowed to be zero for V2 addresses, where the sender
	// will post a fragment containing the asset IDs and amounts to the
	// proof courier's mailbox.
	Amount uint64

	// ProofCourierAddr is the address of the proof courier that will be
	// used to distribute related proofs for this address. For V2 addresses
	// the proof courier address is mandatory and must be a valid auth
	// mailbox address.
	ProofCourierAddr url.URL

	// UnknownOddTypes is a map of unknown odd types that were encountered
	// during decoding. This map is used to preserve unknown types that we
	// don't know of yet, so we can still encode them back when serializing.
	// This enables forward compatibility with future versions of the
	// protocol as it allows new odd (optional) types to be added without
	// breaking old clients that don't yet fully understand them.
	UnknownOddTypes tlv.TypeMap
	// contains filtered or unexported fields
}

type TestAddress struct {
	Version          uint8       `json:"version"`
	ChainParamsHRP   string      `json:"chain_params_hrp"`
	AssetVersion     uint8       `json:"asset_version"`
	AssetID          string      `json:"asset_id"`
	GroupKey         string      `json:"group_key"`
	ScriptKey        string      `json:"script_key"`
	InternalKey      string      `json:"internal_key"`
	TapscriptSibling string      `json:"tapscript_sibling"`
	Amount           uint64      `json:"amount"`
	ProofCourierAddr string      `json:"proof_courier_addr"`
	UnknownOddTypes  tlv.TypeMap `json:"unknown_odd_types"`
}

type TestVectors struct {
	ValidTestCases []*ValidTestCase `json:"valid_test_cases"`
	ErrorTestCases []*ErrorTestCase `json:"error_test_cases"`
}

type ValidTestCase struct {
	Address  *TestAddress `json:"address"`
	Expected string       `json:"expected"`
	Comment  string       `json:"comment"`
}

type Version uint8