deposit

package
v0.34.0-beta Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MinConfs is the legacy minimum confirmation target deposits had to
	// reach before they were considered ready to be used for swaps.
	MinConfs = 6

	// MaxConfs is unset since we don't require a max number of
	// confirmations for deposits.
	MaxConfs = 0

	// DefaultTransitionTimeout is the default timeout for transitions in
	// the deposit state machine.
	DefaultTransitionTimeout = 5 * time.Second

	// PollInterval is the interval in which we poll for new deposits to our
	// static address.
	PollInterval = 10 * time.Second
)
View Source 
const (
	DefaultConfTarget = 3
)
View Source 
const (
	DefaultObserverSize = 20
)
View Source 
const (
	IdLength = 32
)
View Source 
const Subsystem = "SADDR"

Subsystem defines the sub system name of this package.

Variables

View Source 
var (
	// Deposited signals that funds at a static address have been detected
	// and are available to the client.
	Deposited = fsm.StateType("Deposited")

	// Withdrawing signals that the withdrawal transaction has been
	// broadcast, awaiting sufficient confirmations.
	Withdrawing = fsm.StateType("Withdrawing")

	// Withdrawn signals that the withdrawal transaction has been confirmed.
	Withdrawn = fsm.StateType("Withdrawn")

	// OpeningChannel signals that the open channel transaction has been
	// broadcast.
	OpeningChannel = fsm.StateType("OpeningChannel")

	// ChannelPublished signals that the open channel transaction has been
	// published and that the channel should be managed from lnd from now
	// on.
	ChannelPublished = fsm.StateType("ChannelPublished")

	// LoopingIn signals that the deposit is locked for a loop in swap.
	LoopingIn = fsm.StateType("LoopingIn")

	// LoopedIn signals that the loop in swap has been successfully
	// completed. It implies that we signed the sweepless sweep tx for the
	// server.
	LoopedIn = fsm.StateType("LoopedIn")

	// SweepHtlcTimeout signals that the htlc timeout path is in the
	// process of being swept.
	SweepHtlcTimeout = fsm.StateType("SweepHtlcTimeout")

	// HtlcTimeoutSwept signals that the htlc timeout path has been swept.
	HtlcTimeoutSwept = fsm.StateType("HtlcTimeoutSwept")

	// PublishExpirySweep signals that the deposit has expired, and we are
	// in the process of publishing the expiry sweep transaction.
	PublishExpirySweep = fsm.StateType("PublishExpirySweep")

	// WaitForExpirySweep signals that the expiry sweep transaction has been
	// published, and we are waiting for it to be confirmed.
	WaitForExpirySweep = fsm.StateType("WaitForExpirySweep")

	// Expired signals that the deposit has expired and the expiry sweep
	// transaction has been confirmed sufficiently.
	Expired = fsm.StateType("Expired")
)

States.

View Source 
var (
	// OnStart is sent to the fsm once the deposit outpoint has been
	// detected. It transitions the fsm into the Deposited state from where
	// we can trigger a withdrawal, a loopin or an expiry.
	OnStart = fsm.EventType("OnStart")

	// OnWithdrawInitiated is sent to the fsm when a withdrawal has been
	// initiated.
	OnWithdrawInitiated = fsm.EventType("OnWithdrawInitiated")

	// OnWithdrawn is sent to the fsm when a withdrawal has been confirmed.
	OnWithdrawn = fsm.EventType("OnWithdrawn")

	// OnOpeningChannel is sent to the fsm when a channel open has been
	// initiated.
	OnOpeningChannel = fsm.EventType("OnOpeningChannel")

	// OnChannelPublished is sent to the fsm when a channel open has been
	// published. Loop has done its work here and the channel should now be
	// managed from lnd.
	OnChannelPublished = fsm.EventType("OnChannelPublished")

	// OnLoopInInitiated is sent to the fsm when a loop in has been
	// initiated.
	OnLoopInInitiated = fsm.EventType("OnLoopInInitiated")

	// OnSweepingHtlcTimeout is sent to the fsm when the htlc timeout path
	// is being swept. This indicates that the server didn't pay the swap
	// invoice, but the htlc tx was published, from we which we need to
	// sweep the htlc timeout path.
	OnSweepingHtlcTimeout = fsm.EventType("OnSweepingHtlcTimeout")

	// OnHtlcTimeoutSwept is sent to the fsm when the htlc timeout path has
	// been swept.
	OnHtlcTimeoutSwept = fsm.EventType("OnHtlcTimeoutSwept")

	// OnLoopedIn is sent to the fsm when the user intents to use the
	// deposit for a loop in swap.
	OnLoopedIn = fsm.EventType("OnLoopedIn")

	// OnExpiry is sent to the fsm when the deposit has expired.
	OnExpiry = fsm.EventType("OnExpiry")

	// OnExpiryPublished is sent to the fsm when the expiry sweep tx has
	// been published.
	OnExpiryPublished = fsm.EventType("OnExpiryPublished")

	// OnExpirySwept is sent to the fsm when the expiry sweep tx has been
	// confirmed.
	OnExpirySwept = fsm.EventType("OnExpirySwept")

	// OnRecover is sent to the fsm when it should recover from client
	// restart.
	OnRecover = fsm.EventType("OnRecover")
)

Events.

View Source 
var (
	// ErrDepositNotFound is returned when a deposit is not found in the
	// database.
	ErrDepositNotFound = errors.New("deposit not found")
)
View Source 
var (
	ErrProtocolVersionNotSupported = errors.New("protocol version not " +
		"supported")
)

Functions

func CheckDuplicates 

func CheckDuplicates(outpoints []wire.OutPoint) error

CheckDuplicates returns an error if the outpoint list contains duplicates.

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.

Types

type AddressManager 

type AddressManager interface {
	// GetStaticAddressParameters returns the static address parameters.
	GetStaticAddressParameters(ctx context.Context) (*script.Parameters,
		error)

	// GetStaticAddress returns the deposit address for the given
	// client and server public keys.
	GetStaticAddress(ctx context.Context) (*script.StaticAddress, error)

	// ListUnspent returns a list of utxos at the static address.
	ListUnspent(ctx context.Context, minConfs,
		maxConfs int32) ([]*lnwallet.Utxo, error)

	// GetTaprootAddress returns a taproot address.
	GetTaprootAddress(clientPubkey, serverPubkey *btcec.PublicKey,
		expiry int64) (*btcutil.AddressTaproot, error)
}

AddressManager handles fetching of address parameters.

type Deposit 

type Deposit struct {
	sync.Mutex

	// Outpoint of the deposit.
	wire.OutPoint

	// ID is the unique identifier of the deposit.
	ID ID

	// Value is the amount of the deposit.
	Value btcutil.Amount

	// ConfirmationHeight is the absolute height at which the deposit was
	// first confirmed. A value of zero means the deposit is still
	// unconfirmed.
	ConfirmationHeight int64

	// TimeOutSweepPkScript is the pk script that is used to sweep the
	// deposit to after it is expired.
	TimeOutSweepPkScript []byte

	// ExpirySweepTxid is the transaction id of the expiry sweep.
	ExpirySweepTxid chainhash.Hash

	// SwapHash is an optional reference to a static address loop-in swap
	// that used this deposit.
	SwapHash *lntypes.Hash

	// FinalizedWithdrawalTx is the coop-signed withdrawal transaction. It
	// is republished on new block arrivals and on client restarts.
	FinalizedWithdrawalTx *wire.MsgTx
	// contains filtered or unexported fields
}

Deposit bundles an utxo at a static address together with manager-relevant data.

Lock order: if both Manager.mu and a Deposit lock are needed, acquire Manager.mu before Deposit.Lock. Never acquire Manager.mu while holding a Deposit lock.

The state and ConfirmationHeight fields are mutable and protected by the deposit lock.

func ToDeposit 

func ToDeposit(row sqlc.Deposit, lastUpdate sqlc.DepositUpdate) (*Deposit,
	error)

ToDeposit converts an sql deposit to a deposit.

func (*Deposit) GetConfirmationHeight 

func (d *Deposit) GetConfirmationHeight() int64

GetConfirmationHeight returns the deposit confirmation height.

func (*Deposit) GetConfirmationHeightNoLock 

func (d *Deposit) GetConfirmationHeightNoLock() int64

GetConfirmationHeightNoLock returns the deposit confirmation height without acquiring the deposit lock.

func (*Deposit) GetState 

func (d *Deposit) GetState() fsm.StateType

func (*Deposit) IsExpired 

func (d *Deposit) IsExpired(currentHeight, expiry uint32) bool

func (*Deposit) IsInFinalState 

func (d *Deposit) IsInFinalState() bool

IsInFinalState returns true if the deposit is final.

func (*Deposit) IsInState 

func (d *Deposit) IsInState(state fsm.StateType) bool

func (*Deposit) IsInStateNoLock 

func (d *Deposit) IsInStateNoLock(state fsm.StateType) bool

IsInStateNoLock returns whether the deposit is in the given state without acquiring the deposit lock.

func (*Deposit) SetState 

func (d *Deposit) SetState(state fsm.StateType)

type FSM 

type FSM struct {
	*fsm.StateMachine
	// contains filtered or unexported fields
}

FSM is the state machine that handles the instant out.

func NewFSM 

func NewFSM(ctx context.Context, deposit *Deposit, cfg *ManagerConfig,
	finalizedDepositChan chan wire.OutPoint,
	recoverStateMachine bool) (*FSM, error)

NewFSM creates a new state machine that can action on all static address feature requests.

func (*FSM) Debugf 

func (f *FSM) Debugf(format string, args ...any)

Debugf logs a debug message with the deposit outpoint.

func (*FSM) DepositStatesV0 

func (f *FSM) DepositStatesV0() fsm.States

DepositStatesV0 returns the states a deposit can be in.

func (*FSM) Errorf 

func (f *FSM) Errorf(format string, args ...any)

Errorf logs an error message with the deposit outpoint.

func (*FSM) FinalizeDepositAction 

func (f *FSM) FinalizeDepositAction(_ context.Context,
	_ fsm.EventContext) fsm.EventType

FinalizeDepositAction is the final action after a withdrawal. It signals to the manager that the deposit has been swept and the FSM can be removed.

func (*FSM) Infof 

func (f *FSM) Infof(format string, args ...any)

Infof logs an info message with the deposit outpoint.

func (*FSM) PublishDepositExpirySweepAction 

func (f *FSM) PublishDepositExpirySweepAction(ctx context.Context,
	_ fsm.EventContext) fsm.EventType

PublishDepositExpirySweepAction creates and publishes the timeout transaction that spends the deposit from the static address timeout leaf to the predefined timeout sweep pkscript.

func (*FSM) SignDescriptor 

func (f *FSM) SignDescriptor(ctx context.Context) (*lndclient.SignDescriptor,
	error)

SignDescriptor returns the sign descriptor for the static address output.

func (*FSM) Stop 

func (f *FSM) Stop()

Stop requests shutdown of the FSM's block notification loop.

func (*FSM) WaitForExpirySweepAction 

func (f *FSM) WaitForExpirySweepAction(ctx context.Context,
	_ fsm.EventContext) fsm.EventType

WaitForExpirySweepAction waits for enough confirmations before a timeout sweep is considered successful.

type ID 

type ID [IdLength]byte

ID is a unique identifier for a deposit.

func GetRandomDepositID 

func GetRandomDepositID() (ID, error)

GetRandomDepositID generates a random deposit ID.

func (*ID) FromByteSlice 

func (r *ID) FromByteSlice(b []byte) error

FromByteSlice creates a deposit id from a byte slice.

type Manager 

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

Manager manages the address state machines.

Lock order: if both Manager.mu and a Deposit lock are needed, acquire Manager.mu before Deposit.Lock. Never acquire Manager.mu while holding a Deposit lock. Multiple deposits must be locked with lockDeposits, which canonicalizes lock order by outpoint.

func NewManager 

func NewManager(cfg *ManagerConfig) *Manager

NewManager creates a new deposit manager.

func (*Manager) AllOutpointsActiveDeposits 

func (m *Manager) AllOutpointsActiveDeposits(outpoints []wire.OutPoint,
	targetState fsm.StateType) ([]*Deposit, bool)

AllOutpointsActiveDeposits checks if all deposits referenced by the outpoints are in our in-mem active deposits map and in the specified state. If fsm.EmptyState is set as targetState all deposits are returned regardless of their state. Each existent deposit is locked during the check.

func (*Manager) AllStringOutpointsActiveDeposits 

func (m *Manager) AllStringOutpointsActiveDeposits(outpoints []string,
	stateFilter fsm.StateType) ([]*Deposit, bool)

AllStringOutpointsActiveDeposits converts outpoint strings of format txid:idx to wire outpoints and checks if all deposits referenced by the outpoints are active and in the specified state. If fsm.EmptyState is referenced as stateFilter all deposits are returned regardless of their state.

func (*Manager) DepositsForOutpoints 

func (m *Manager) DepositsForOutpoints(ctx context.Context,
	outpoints []string, ignoreUnknown bool) ([]*Deposit, error)

DepositsForOutpoints returns all deposits that are behind the given outpoints.

func (*Manager) EnsureDepositsFresh 

func (m *Manager) EnsureDepositsFresh(ctx context.Context) error

EnsureDepositsFresh reconciles the cached active deposit set with lnd's current wallet view. Spending paths call this before selecting deposits so stale persisted records are not treated as live funds. This can happen when an unconfirmed funding transaction is replaced, a confirmed deposit is reorged out, or the output was spent outside the active manager path.

func (*Manager) GetActiveDepositsInState 

func (m *Manager) GetActiveDepositsInState(stateFilter fsm.StateType) (
	[]*Deposit, error)

GetActiveDepositsInState returns all active deposits. This function is called on a client restart before the manager is fully initialized, hence we don't have to lock the deposits.

func (*Manager) GetAllDeposits 

func (m *Manager) GetAllDeposits(ctx context.Context) ([]*Deposit, error)

GetAllDeposits returns all known deposits from the database.

func (*Manager) GetVisibleDeposits 

func (m *Manager) GetVisibleDeposits(ctx context.Context) ([]*Deposit, error)

GetVisibleDeposits returns deposits that should be exposed through normal user-facing views. The database can contain historical Deposited rows whose outpoints are no longer present in lnd's current wallet view, for example after replacement or reorg. Once the manager has recovered its live cache, plain Deposited records are only visible while their outpoint is in the active set.

func (*Manager) Run 

func (m *Manager) Run(ctx context.Context, initChan chan struct{}) error

Run runs the address manager.

func (*Manager) TransitionDeposits 

func (m *Manager) TransitionDeposits(ctx context.Context, deposits []*Deposit,
	event fsm.EventType, expectedFinalState fsm.StateType) error

TransitionDeposits allows a caller to transition a set of deposits to a new state. Caveat: The action triggered by the state transitions should not compute heavy things or call external endpoints that can block for a long time as this function blocks until the expectedFinalState is reached. The default timeout for the transition is set to DefaultTransitionTimeout.

func (*Manager) UpdateDeposit 

func (m *Manager) UpdateDeposit(ctx context.Context, d *Deposit) error

UpdateDeposit overrides all fields of the deposit with given ID in the store.

type ManagerConfig 

type ManagerConfig struct {
	// AddressManager is the address manager that is used to fetch static
	// address parameters.
	AddressManager AddressManager

	// Store is the database store that is used to store static address
	// related records.
	Store Store

	// WalletKit is the wallet client that is used to derive new keys from
	// lnd's wallet.
	WalletKit lndclient.WalletKitClient

	// ChainNotifier is the chain notifier that is used to listen for new
	// blocks.
	ChainNotifier lndclient.ChainNotifierClient

	// Signer is the signer client that is used to sign transactions.
	Signer lndclient.SignerClient
}

ManagerConfig holds the configuration for the address manager.

type SqlStore 

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

SqlStore is the backing store for static address deposits.

func NewSqlStore 

func NewSqlStore(db *loopdb.BaseDB) *SqlStore

NewSqlStore constructs a new SQLStore from a BaseDB. The BaseDB is agnostic to the underlying driver which can be postgres or sqlite.

func (*SqlStore) AllDeposits 

func (s *SqlStore) AllDeposits(ctx context.Context) ([]*Deposit, error)

AllDeposits retrieves all known deposits to our static address.

func (*SqlStore) CreateDeposit 

func (s *SqlStore) CreateDeposit(ctx context.Context, deposit *Deposit) error

CreateDeposit creates a static address deposit record in the database.

func (*SqlStore) DepositForOutpoint 

func (s *SqlStore) DepositForOutpoint(ctx context.Context,
	outpoint string) (*Deposit, error)

DepositForOutpoint retrieves the deposit with the given outpoint from the database.

func (*SqlStore) GetDeposit 

func (s *SqlStore) GetDeposit(ctx context.Context, id ID) (*Deposit, error)

GetDeposit retrieves the deposit from the database.

func (*SqlStore) UpdateDeposit 

func (s *SqlStore) UpdateDeposit(ctx context.Context, deposit *Deposit) error

UpdateDeposit updates the deposit in the database.

Callers that pass a live deposit must hold the deposit lock while calling this method. The deposit FSM already does this for state transitions, and Manager.UpdateDeposit wraps external callers with the same lock.

type Store 

type Store interface {
	// CreateDeposit inserts a new deposit into the store.
	CreateDeposit(ctx context.Context, deposit *Deposit) error

	// UpdateDeposit updates the deposit in the database.
	UpdateDeposit(ctx context.Context, deposit *Deposit) error

	// GetDeposit retrieves a deposit with depositID from the database.
	GetDeposit(ctx context.Context, depositID ID) (*Deposit, error)

	// DepositForOutpoint retrieves the deposit with the given outpoint.
	DepositForOutpoint(ctx context.Context, outpoint string) (*Deposit,
		error)

	// AllDeposits retrieves all deposits from the store.
	AllDeposits(ctx context.Context) ([]*Deposit, error)
}

Store is the database interface that is used to store and retrieve static address deposits.

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.