address

package
v0.1.1-alpha Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2022 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MainnetHRP is the HRP for mainnet.
	MainnetHRP = "tarobc"

	// TestnetHRP is the HRP for testnet.
	TestnetHRP = "tarotb"

	// RegTestHRP is the HRP for regtest.
	RegTestHRP = "tarort"

	// SigNetHRP is the HRP for "the" signet.
	SigNetHRP = "tarotb"

	// SimNetHRP is the HRP for simnet.
	SimNetHRP = "tarosb"
)
View Source 
const (
	// TaroScriptVersion is the highest version of Taro script supported.
	TaroScriptVersion uint8 = 0
)

Variables

View Source 
var (
	// ErrUnsupportedHRP is an error returned when we attempt to encode a
	// Taro address with an HRP for a network without Taro support.
	ErrUnsupportedHRP = errors.New(
		"address: unsupported HRP value",
	)

	// ErrMismatchedHRP is an error returned when we attempt to decode a
	// Taro address with an HRP that does not match the expected network.
	ErrMismatchedHRP = errors.New(
		"address: network mismatch",
	)

	// ErrInvalidBech32m is an error returned when we attempt to decode a
	// Taro address from a string that is not a valid bech32m string.
	ErrInvalidBech32m = errors.New(
		"address: invalid bech32m string",
	)

	// ErrInvalidAmountCollectible is an error returned when we attempt to
	// create a Taro address for a Collectible asset with an amount not
	// equal to one.
	ErrInvalidAmountCollectible = errors.New(
		"address: collectible asset amount not one",
	)

	// ErrInvalidAmountNormal is an error returned when we attempt to
	// create a Taro address for a Normal asset with an amount of zero.
	ErrInvalidAmountNormal = errors.New(
		"address: normal asset amount of zero",
	)

	// ErrUnsupportedAssetType is an error returned when we attempt to
	// create a Taro address for a non-standard asset type.
	ErrUnsupportedAssetType = errors.New(
		"address: unsupported asset type",
	)

	// ErrNoAddr is returned if no address is found in the address store.
	ErrNoAddr = errors.New(
		"address: no address found",
	)
)
View Source 
var (

	// MainNetTaro holds the chain params for mainnet.
	MainNetTaro = ChainParams{
		Params:  &chaincfg.MainNetParams,
		TaroHRP: MainnetHRP,
	}

	// TestNet3Taro holds the chain params for testnet.
	TestNet3Taro = ChainParams{
		Params:  &chaincfg.TestNet3Params,
		TaroHRP: TestnetHRP,
	}

	// RegressionNetTaro holds the chain params for regtest.
	RegressionNetTaro = ChainParams{
		Params:  &chaincfg.RegressionNetParams,
		TaroHRP: RegTestHRP,
	}

	// SigNetTaro holds the chain params for signet.
	SigNetTaro = ChainParams{
		Params:  &chaincfg.SigNetParams,
		TaroHRP: SigNetHRP,
	}

	// SimNetTaro holds the chain params for simnet.
	SimNetTaro = ChainParams{
		Params:  &chaincfg.SimNetParams,
		TaroHRP: SimNetHRP,
	}
)

Functions

func IsBech32MTaroPrefix 

func IsBech32MTaroPrefix(prefix string) bool

IsBech32MTaroPrefix returns whether the prefix is a known prefix for Taro addresses on any supported network. This is used when creating an address, encoding an address to a string, or decoding an address string into a TLV.

func IsForNet 

func IsForNet(hrp string, net *ChainParams) bool

IsForNet returns whether the HRP is associated with the passed network.

func Register 

func Register(params *ChainParams) error

Register attempts to register a new taro ChainParams with the library. If a set of parameters for the network has already been registered, then an error is returned.

TODO(jhb): Resolve duplicate networks?

Types

type AddrWithKeyInfo 

type AddrWithKeyInfo struct {
	*Taro

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

AddrWithKeyInfo wraps a normal Taro struct with key descriptor information.

type Book 

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

Book is used to create and also look up the set of created Taro addresses.

func NewBook 

func NewBook(cfg BookConfig) *Book

NewBook creates a new Book instance from the config.

func (*Book) AddrByTaprootOutput 

func (b *Book) AddrByTaprootOutput(ctx context.Context,
	key *btcec.PublicKey) (*AddrWithKeyInfo, error)

AddrByTaprootOutput returns a single address based on its Taproot output key or a sql.ErrNoRows error if no such address exists.

func (*Book) CompleteEvent 

func (b *Book) CompleteEvent(ctx context.Context, event *Event,
	status Status, anchorPoint wire.OutPoint) error

CompleteEvent updates an address event as being complete and links it with the proof and asset that was imported/created for it.

func (*Book) GetOrCreateEvent 

func (b *Book) GetOrCreateEvent(ctx context.Context, status Status,
	addr *AddrWithKeyInfo, walletTx *lndclient.Transaction,
	outputIdx uint32, tapscriptSibling *chainhash.Hash) (*Event, error)

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.

func (*Book) GetPendingEvents 

func (b *Book) GetPendingEvents(ctx context.Context) ([]*Event, error)

GetPendingEvents returns all events that are not yet in status complete from the database.

func (*Book) ListAddrs 

func (b *Book) ListAddrs(ctx context.Context,
	params QueryParams) ([]AddrWithKeyInfo, error)

ListAddrs lists a set of addresses based on the expressed query params.

func (*Book) NewAddress 

func (b *Book) NewAddress(ctx context.Context, genesis asset.Genesis,
	famKey *btcec.PublicKey, amount uint64) (*AddrWithKeyInfo, error)

NewAddress creates a new Taro address based on the input parameters.

func (*Book) QueryEvents 

func (b *Book) QueryEvents(ctx context.Context,
	query EventQueryParams) ([]*Event, error)

QueryEvents returns all events that match the given query.

func (*Book) RegisterSubscriber 

func (b *Book) RegisterSubscriber(
	receiver *chanutils.EventReceiver[*AddrWithKeyInfo],
	deliverExisting bool, deliverFrom QueryParams) error

RegisterSubscriber adds a new subscriber for receiving events. The deliverExisting boolean indicates whether already existing items should be sent to the NewItemCreated channel when the subscription is started. An optional deliverFrom can be specified to indicate from which timestamp/index/ marker onward existing items should be delivered on startup. If deliverFrom is nil/zero/empty then all existing items will be delivered.

func (*Book) RemoveSubscriber 

func (b *Book) RemoveSubscriber(
	subscriber *chanutils.EventReceiver[*AddrWithKeyInfo]) error

RemoveSubscriber removes the given subscriber and also stops it from processing events.

func (*Book) SetAddrManaged 

func (b *Book) SetAddrManaged(ctx context.Context, addr *AddrWithKeyInfo,
	managedFrom time.Time) error

SetAddrManaged sets an address as being managed by the internal wallet.

type BookConfig 

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

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

BookConfig is the main config for the address.Book.

type ChainParams 

type ChainParams struct {
	*chaincfg.Params

	// TaroHRP is the HRP to use for Taro addresses for the target network.
	TaroHRP string
}

ChainParams defines a Taro-supporting network by its parameters. These parameters include those specified by chaincfg.Params, as well as a Taro-specific HRP used for Taro addresses. These parameters may be used by Taro applications to differentiate networks as well as addresses and keys for one network from those intended for use on another network.

func Net 

func Net(hrp string) (*ChainParams, error)

Net returns the ChainParams struct associated with a Taro HRP.

func ParamsForChain 

func ParamsForChain(name string) ChainParams

ParamsForChain returns the ChainParams for a given chain based on its name.

type Event 

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

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

	// Addr is the Taro 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 Taro
	// 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 Taro commitment
	// (when NO tapscript sibling if present) is equal to the
	// TaprootOutputKey of the Addr.
	InternalKey *btcec.PublicKey

	// TapscriptSibling, if non-empty, signals that a Tapscript sibling leaf
	// was present in the on-chain Taproot output that sent the assets. This
	// can only be achieved by importing a proof and then scanning for the
	// Taproot output on chain retroactively, since at the time a Taro
	// address is created the sibling might not yet be known.
	//
	// NOTE: The functionality described above (importing the proof and re-
	// scanning the chain) is not yet implemented, so this should always be
	// empty or nil at the moment.
	TapscriptSibling []byte

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

	// HasProof indicates that a proof for this transfer was imported. We
	// don't keep a reference to it in memory as the proof itself can be
	// large. The proof can be fetched by the script key of the address.
	HasProof bool
}

Event represents a single incoming asset transfer that was initiated by sending an on-chain transaction to the Taproot output key generated by a Taro address. Each event represents a single on-chain UTXO that is being taken custody of and is being tracked/watched by the internal wallet. One Taro address can receive multiple times and therefore can have multiple events.

type EventQueryParams 

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
}

EventQueryParams holds the set of query params for address events.

type EventStorage 

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,
		addr *AddrWithKeyInfo, walletTx *lndclient.Transaction,
		outputIdx uint32, tapscriptSibling *chainhash.Hash) (*Event,
		error)

	// QueryAddrEvents returns a list of event that match the given query
	// parameters.
	QueryAddrEvents(ctx context.Context, params EventQueryParams) ([]*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
}

EventStorage is the interface that a component storing address events should implement.

type KeyRing 

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

KeyRing is used to create script and internal keys for Taro addresses.

type QueryParams 

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
}

QueryParams holds the set of query params for the address book.

type Status 

type Status uint8

Status denotes an address event's current status. 

const (
	// StatusTransactionDetected denotes that a transaction for an incoming
	// asset transfer was detected but the transaction hasn't been confirmed
	// yet.
	StatusTransactionDetected Status = 0

	// StatusTransactionConfirmed denotes that the transaction for an
	// incoming asset transfer was confirmed. The transfer now requires the
	// proof to be imported to proceed.
	StatusTransactionConfirmed Status = 1

	// StatusProofReceived denotes that the proof for an incoming asset
	// transfer was received and is now being validated and processed.
	StatusProofReceived Status = 2

	// StatusCompleted denotes that an incoming asset transfer was completed
	// successfully and the local node has taken over custody of the assets
	// that were transferred.
	StatusCompleted Status = 3
)

type Storage 

type Storage interface {
	EventStorage

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

	// QueryAddrs attemps to query for a set of addresses.
	QueryAddrs(ctx context.Context,
		params QueryParams) ([]AddrWithKeyInfo, 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)

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

Storage is the main storage interface for the address book.

type Taro 

type Taro struct {
	// ChainParams is the reference to the chain parameters that were used
	// to encode the Taro addresses.
	ChainParams *ChainParams

	// Version is the Taro version of the asset.
	Version asset.Version

	// Genesis is the receiving asset's genesis metadata which directly
	// maps to its unique ID within the Taro protocol.
	asset.Genesis

	// FamilyKey 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.
	FamilyKey *btcec.PublicKey

	// ScriptKey represents a tweaked Taproot output key encumbering the
	// different ways an asset can be spent.
	ScriptKey btcec.PublicKey

	// InternalKey is the BIP-340/341 public key of the receiver.
	InternalKey btcec.PublicKey

	// Amount is the number of asset units being requested by the receiver.
	Amount uint64
}

Taro represents a Taro address. Taro addresses specify an asset, pubkey, and amount.

func DecodeAddress 

func DecodeAddress(addr string, net *ChainParams) (*Taro, error)

DecodeAddress parses a bech32m encoded Taro address string and returns the HRP and address TLV.

func New 

func New(genesis asset.Genesis, familyKey *btcec.PublicKey,
	scriptKey btcec.PublicKey, internalKey btcec.PublicKey, amt uint64,
	net *ChainParams) (*Taro, error)

New creates an address for receiving a Taro asset.

func (*Taro) AssetCommitmentKey 

func (a *Taro) AssetCommitmentKey() [32]byte

AssetCommitmentKey is the key that maps to the asset leaf for the asset specified by a Taro address.

func (*Taro) Copy 

func (a *Taro) Copy() *Taro

Copy returns a deep copy of an Address.

func (*Taro) Decode 

func (a *Taro) Decode(r io.Reader) error

Decode decodes an address from a TLV stream.

func (*Taro) DecodeRecords 

func (a *Taro) DecodeRecords() []tlv.Record

DecodeRecords provides all records known for an address for proper decoding.

func (*Taro) Encode 

func (a *Taro) Encode(w io.Writer) error

Encode encodes an address into a TLV stream.

func (*Taro) EncodeAddress 

func (a *Taro) EncodeAddress() (string, error)

EncodeAddress returns a bech32m string encoding of a Taro address.

func (*Taro) EncodeRecords 

func (a *Taro) EncodeRecords() []tlv.Record

EncodeRecords determines the non-nil records to include when encoding an address at runtime.

func (*Taro) Net 

func (a *Taro) Net() (*ChainParams, error)

Net returns the ChainParams struct matching the Taro address network.

func (*Taro) TaprootOutputKey 

func (a *Taro) TaprootOutputKey(sibling *chainhash.Hash) (*btcec.PublicKey,
	error)

TaprootOutputKey returns the on-chain Taproot output key.

func (*Taro) TaroCommitment 

func (a *Taro) TaroCommitment() (*commitment.TaroCommitment, error)

TaroCommitment constructs the Taro commitment that is expected to appear on chain when assets are being sent to this address.

func (*Taro) TaroCommitmentKey 

func (a *Taro) TaroCommitmentKey() [32]byte

TaroCommitmentKey is the key that maps to the root commitment for the asset family specified by a Taro address.

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.