wallet

package module
v0.0.0-...-ccda5c5 Latest Latest
Warning

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

Go to latest
Published: Jun 18, 2026 License: MIT Imports: 51 Imported by: 2

Documentation

Index

Constants

View Source
const (
	// identity
	SingleKeyIdentity = identity.SingleKeyIdentity
	// store
	FileStore     = types.FileStore
	InMemoryStore = types.InMemoryStore
)

Variables

View Source
var (
	ErrAlreadyInitialized = fmt.Errorf("wallet already initialized")
	ErrNotInitialized     = fmt.Errorf("wallet not initialized")
	ErrIsLocked           = fmt.Errorf("wallet is locked")
)
View Source
var ErrWaitingForConfirmation = fmt.Errorf("waiting for confirmation(s), please retry later")
View Source
var Version string
View Source
var WithSubDustVtxos = WithRecoverableVtxos

name alias, sub-dust vtxos are recoverable vtxos

Functions

func ApplyListVtxosOptions

func ApplyListVtxosOptions(opts ...ListVtxosOption) (*listVtxosOptions, error)

func GetEventStreamTopics

func GetEventStreamTopics(
	spentOutpoints []types.Outpoint, signerSessions []tree.SignerSession,
) []string

func JoinBatchSession

func JoinBatchSession(
	ctx context.Context, eventsCh <-chan client.BatchEventChannel,
	eventsHandler BatchEventsHandler, opts ...BatchEventHandlerOption,
) (string, string, time.Duration, []string, *tree.TxTree, error)

func NetVtxoAssets

func NetVtxoAssets(gross, subtract []types.Vtxo) []types.Asset

NetVtxoAssets returns the per-asset balance for a vtxo movement: assets found in `gross` minus the portion in `subtract` that effectively stayed in the wallet (change, already-owned vtxos, etc.).

The output preserves asset-id order as first encountered in `gross`, drops zero-net assets, and returns nil when there is no asset data (common pure-BTC case).

It is exported so that external SDKs reproducing the same vtxosToTxs reconstruction (e.g. go-sdk) can derive Transaction.Assets with identical semantics, rather than keeping a parallel copy of the helper.

Types

type Balance

type Balance struct {
	OnchainBalance  OnchainBalance    `json:"onchain_balance"`
	OffchainBalance OffchainBalance   `json:"offchain_balance"`
	AssetBalances   map[string]uint64 `json:"asset_balances,omitempty"`
}

type BatchEventHandlerOption

type BatchEventHandlerOption func(*options)

func WithCancel

func WithCancel(cancelCh <-chan struct{}) BatchEventHandlerOption

func WithReplay

func WithReplay(ch chan<- any) BatchEventHandlerOption

func WithSkipVtxoTreeSigning

func WithSkipVtxoTreeSigning() BatchEventHandlerOption

type BatchEventsHandler

type BatchEventsHandler interface {
	OnBatchStarted(
		ctx context.Context, event client.BatchStartedEvent,
	) (bool, time.Duration, error)
	OnBatchFinalized(ctx context.Context, event client.BatchFinalizedEvent) error
	OnBatchFailed(ctx context.Context, event client.BatchFailedEvent) error
	OnTreeTxEvent(ctx context.Context, event client.TreeTxEvent) error
	OnTreeSignatureEvent(ctx context.Context, event client.TreeSignatureEvent) error
	OnTreeSigningStarted(
		ctx context.Context, event client.TreeSigningStartedEvent, vtxoTree *tree.TxTree,
	) (bool, error)
	OnTreeNoncesAggregated(
		ctx context.Context,
		event client.TreeNoncesAggregatedEvent,
	) (signed bool, err error)
	OnTreeNonces(ctx context.Context, event client.TreeNoncesEvent) (signed bool, err error)
	OnBatchFinalization(
		ctx context.Context,
		event client.BatchFinalizationEvent, vtxoTree, connectorTree *tree.TxTree,
	) ([]string, error)
	OnStreamStarted(
		ctx context.Context, event client.StreamStartedEvent,
	) error
}

type BatchSessionOption

type BatchSessionOption interface {
	// contains filtered or unexported methods
}

func WithCancelCh

func WithCancelCh(ch <-chan struct{}) BatchSessionOption

WithCancelCh allows to cancel the settlement process

func WithEventsCh

func WithEventsCh(ch chan<- any) BatchSessionOption

func WithExpiryThreshold

func WithExpiryThreshold(threshold int64) BatchSessionOption

func WithExtraSigner

func WithExtraSigner(signerSessions ...tree.SignerSession) BatchSessionOption

WithExtraSigner allows to use a set of custom signer for the vtxo tree signing process

func WithFunds

func WithFunds(boardingUtxos []types.Utxo, vtxos []types.VtxoWithTapTree) BatchSessionOption

func WithRecoverableVtxos

func WithRecoverableVtxos() BatchSessionOption

func WithRetries

func WithRetries(num int) BatchSessionOption

func WithoutTreeSigner

func WithoutTreeSigner() BatchSessionOption

WithoutTreeSigner disables the tree signer for the batch session

type BatchTxRes

type BatchTxRes struct {
	CommitmentTxid string
	CommitmentTx   string
	IntentTx       string
	ForfeitTxs     []string
	VtxoInputs     []types.Vtxo
	UtxoInputs     []types.Utxo
	VtxoOutputs    []types.Vtxo
	UtxoOutputs    []types.Receiver
	Extension      extension.Extension
}

type BurnAssetRes

type BurnAssetRes = OffchainTxRes

type CollaborativeExitRes

type CollaborativeExitRes = BatchTxRes

type FinalizePendingTxsRes

type FinalizePendingTxsRes = []OffchainTxRes

type InitArgs

type InitArgs struct {
	ServerUrl   string
	Seed        string
	Password    string
	ExplorerURL string
	Explorer    explorer.Explorer
}

type IssueAssetRes

type IssueAssetRes struct {
	OffchainTxRes
	IssuedAssets []asset.AssetId
}

type ListVtxosOption

type ListVtxosOption func(options *listVtxosOptions) error

func WithTimeRange

func WithTimeRange(before, after int64) ListVtxosOption

type LockedOnchainBalance

type LockedOnchainBalance struct {
	SpendableAt string `json:"spendable_at"`
	Amount      uint64 `json:"amount"`
}

type OffchainBalance

type OffchainBalance struct {
	Total          uint64        `json:"total"`
	NextExpiration string        `json:"next_expiration,omitempty"`
	Details        []VtxoDetails `json:"details"`
}

type OffchainTxRes

type OffchainTxRes struct {
	Txid        string
	Tx          string
	Checkpoints []string
	Inputs      []types.Vtxo
	Outputs     []types.Receiver
	Extension   extension.Extension
}

type OnchainBalance

type OnchainBalance struct {
	SpendableAmount uint64                 `json:"spendable_amount"`
	LockedAmount    []LockedOnchainBalance `json:"locked_amount,omitempty"`
}

type ReceiverOption

type ReceiverOption interface {
	SendOption
	BatchSessionOption
	UnrollOption
}

ReceiverOption is the intersection of every option family that accepts a destination/change address override. A value satisfying ReceiverOption can be passed to any method taking SendOption, BatchSessionOption, or UnrollOption — so WithReceiver is defined once here instead of duplicated per family. See SignOption in sign_opts.go for the same pattern.

func WithReceiver

func WithReceiver(addr string) ReceiverOption

WithReceiver overrides the destination/change address that the method would otherwise freshly derive via identity.NewKey. Accepts an offchain ark address or an onchain bitcoin address; the consuming method validates which kinds are permitted (e.g. SendOffChain requires offchain; OnboardAgainAllExpiredBoardings requires onchain; Settle / CollaborativeExit accept either).

Note: directing change to a known address weakens unlinkability — caller's choice. Skipping the identity.NewKey call also means no new key is recorded in the wallet for the change output.

type RedeemNotesRes

type RedeemNotesRes = BatchTxRes

type ReissueAssetRes

type ReissueAssetRes = OffchainTxRes

type SendOffChainRes

type SendOffChainRes = OffchainTxRes

type SendOption

type SendOption interface {
	// contains filtered or unexported methods
}

SendOption is satisfied by any value whose applySend method mutates a sendOptions. Interface-typed options let a single definition satisfy multiple option families — see WithKeys in sign_opts.go.

func WithExtraPacket

func WithExtraPacket(packets ...extension.Packet) SendOption

WithExtraPacket appends extra extension.Packet values to the OP_RETURN extension blob that is included in the ark transaction alongside the asset packet (type 0x00).

Type 0x00 is reserved for the asset packet, automatically built depending on the Transaction. Passing type 0x00 returns an error.

Duplicate packet types are not permitted.

func WithTxOutsTaprootTree

func WithTxOutsTaprootTree(tapTrees map[string][]byte) SendOption

WithTxOutsTaprootTree sets the PSBT BIP-371 TaprootTapTree field on every output whose hex-encoded pkScript matches a key in the map. Callers pass the BIP-371-encoded tap tree bytes (via txutils.TapTree(scripts).Encode()). SendOffChain returns an error if any pkScript key matches no output of the ark tx, surfacing what would otherwise be a silent footgun for protocol- critical VTXO spending.

func WithoutExpirySorting

func WithoutExpirySorting() SendOption

type ServiceOption

type ServiceOption func(*service)

func WithClientVersion

func WithClientVersion(version string) ServiceOption

func WithExplorer

func WithExplorer(explorer explorer.Explorer) ServiceOption

func WithIdentity

func WithIdentity(identitySvc identity.Identity) ServiceOption

func WithVerbose

func WithVerbose() ServiceOption

func WithoutFinalizePendingTxs

func WithoutFinalizePendingTxs() ServiceOption

type SettleRes

type SettleRes = BatchTxRes

type SignOption

type SignOption interface {
	SendOption
	BatchSessionOption
	UnrollOption
}

SignOption is the intersection of every option family that accepts signing keys. A value that satisfies SignOption can be passed to any method taking SendOption, BatchSessionOption, or UnrollOption — so WithKeys is defined once here instead of duplicated per family.

func WithKeys

func WithKeys(keys map[string]string) SignOption

WithKeys is usable in SendOffChain, Settle, Unroll, and every other method that currently accepts one of the three option families.

type UnrollOption

type UnrollOption interface {
	// contains filtered or unexported methods
}

func WithUtxosToClaim

func WithUtxosToClaim(utxos []types.Utxo) UnrollOption

type UnrollRes

type UnrollRes struct {
	ParentTx   string
	ParentTxid string
	ChildTx    string
	ChildTxid  string
}

type VtxoDetails

type VtxoDetails struct {
	ExpiryTime string `json:"expiry_time"`
	Amount     uint64 `json:"amount"`
}

type VtxosOption

type VtxosOption interface {
	SendOption
	UnrollOption
}

VtxosOption is the intersection of every option family that accepts a caller-supplied set of vtxos. A single WithVtxos satisfies all of SendOption, BatchSessionOption, and UnrollOption.

func WithVtxos

func WithVtxos(vtxos []types.VtxoWithTapTree) VtxosOption

type Wallet

type Wallet interface {
	Identity() identity.Identity
	Client() client.Client
	Indexer() indexer.Indexer
	Explorer() explorer.Explorer

	GetVersion() string
	GetConfigData(ctx context.Context) (*types.Config, error)
	Init(ctx context.Context, args InitArgs) error
	IsLocked(ctx context.Context) bool
	Unlock(ctx context.Context, password string) error
	Lock(ctx context.Context) error
	Dump(ctx context.Context) (seed string, err error)
	SignTransaction(ctx context.Context, tx string, opts ...SignOption) (string, error)
	Reset(ctx context.Context)
	Stop()
	// ** Funding **
	Receive(
		ctx context.Context,
	) (onchainAddr string, offchainAddr, boardingAddr *types.Address, err error)
	GetAddresses(ctx context.Context) (
		onchainAddresses []string,
		offchainAddresses, boardingAddresses, redemptionAddresses []types.Address, err error,
	)
	Balance(ctx context.Context) (*Balance, error)
	ListVtxos(
		ctx context.Context, opts ...ListVtxosOption,
	) (spendable, spent []types.Vtxo, err error)
	GetTransactionHistory(ctx context.Context) ([]types.Transaction, error)
	NotifyIncomingFunds(ctx context.Context, address string) ([]types.Vtxo, error)
	// ** Assets **
	IssueAsset(
		ctx context.Context, amount uint64, controlAsset types.ControlAsset,
		metadata []asset.Metadata, opts ...SendOption,
	) (*IssueAssetRes, error)
	ReissueAsset(
		ctx context.Context, assetId string, amount uint64, opts ...SendOption,
	) (*ReissueAssetRes, error)
	BurnAsset(
		ctx context.Context, assetID string, amount uint64, opts ...SendOption,
	) (*BurnAssetRes, error)
	// ** Offchain txs **
	SendOffChain(
		ctx context.Context, receivers []types.Receiver, opts ...SendOption,
	) (*SendOffChainRes, error)
	FinalizePendingTxs(
		ctx context.Context, createdAfter *time.Time, opts ...SendOption,
	) ([]string, error)
	// ** Batch session **
	Settle(ctx context.Context, opts ...BatchSessionOption) (*SettleRes, error)
	CollaborativeExit(
		ctx context.Context, addr string, amount uint64, opts ...BatchSessionOption,
	) (*CollaborativeExitRes, error)
	RedeemNotes(
		ctx context.Context, notes []string, opts ...BatchSessionOption,
	) (*RedeemNotesRes, error)
	RegisterIntent(
		ctx context.Context, vtxos []types.Vtxo, boardingUtxos []types.Utxo, notes []string,
		outputs []types.Receiver, cosignersPublicKeys []string, opts ...SignOption,
	) (intentID string, err error)
	DeleteIntent(
		ctx context.Context, vtxos []types.Vtxo, boardingUtxos []types.Utxo,
		notes []string, opts ...SignOption,
	) error
	// ** Unroll **
	Unroll(ctx context.Context, opts ...UnrollOption) ([]UnrollRes, error)
	CompleteUnroll(ctx context.Context, to string, opts ...UnrollOption) (string, error)
	OnboardAgainAllExpiredBoardings(ctx context.Context, opts ...UnrollOption) (string, error)
	WithdrawFromAllExpiredBoardings(
		ctx context.Context, to string, opts ...UnrollOption,
	) (string, error)
}

func LoadWallet

func LoadWallet(storeSvc types.Store, opts ...ServiceOption) (Wallet, error)

func NewWallet

func NewWallet(storeSvc types.Store, opts ...ServiceOption) (Wallet, error)

Directories

Path Synopsis
example
alice_to_bob command
mempool
Package explorer provides an explorer client with support for multiple concurrent WebSocket connections for addresses tracking.
Package explorer provides an explorer client with support for multiple concurrent WebSocket connections for addresses tracking.
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL