minimalsigner

README

minimalsigner

minimalsigner is a proof of concept of a stateless remote signer for lnd. Currently, it can do the following:

• import wallet seed and macaroon root key from environment variables
• export account list and macaroon for watch-only lnd instance
• sign messages for network announcements
• derive shared keys for peer connections
• sign PSBTs for on-chain transactions, channel openings/closes, HTLC updates, etc.
• verify macaroons on grpc request
• perform musig2 ops
• add and verify macaroon caveats (like expiration or ip address restriction)
• allow an interceptor to determine whether or not to sign
• run unit tests and itests, do automated builds
• log and gather metrics coherently

Usage

Ensure you have bitcoind and lnd installed. Build signer using Go 1.18+ from this directory:

go install ./cmd/...

Create a directory ~/.signer with a signer.conf similar to:

rpclisten=tcp://127.0.0.1:10021
regtest=true

Create a ~/.lnd-watchonly with a lnd.conf similar to:

[bitcoin]
bitcoin.active=true
bitcoin.regtest=true
bitcoin.node=bitcoind

[remotesigner]
remotesigner.enable=true
remotesigner.rpchost=127.0.0.1:10021
remotesigner.tlscertpath=/home/user/.signer/tls.cert
remotesigner.macaroonpath=/home/user/.signer/signer.custom.macaroon

Run as follows, with the wallet seed in SIGNER_SEED and the macaroon root key in SIGNER_MAC_ROOT_KEY:

~/.signer$ SIGNER_SEED=1111111111222222222233333333334444444444555555555566666666661234 \
              SIGNER_MAC_ROOT_KEY=6666666666555555555544444444443333333333222222222211111111114321 \
              signer --outputmacaroon=signer.custom.macaroon --outputaccounts=accounts.json

Now, run lnd in watch-only mode:

~/.lnd-watchonly$ lnd --lnddir=.

Create the watch-only wallet:

~$ lncli createwatchonly .signer/accounts.json

For more information regarding remotesigner mode in lnd, see the lnd docs.

Documentation

Index

• func CleanAndExpandPath(path string) string
• func ListenOnAddress(addr net.Addr) (net.Listener, error)
• func Main(cfg *Config, lisCfg ListenerCfg) error
• func NormalizeAddresses(addrs []string, defaultPort string, tcpResolver TCPResolver) ([]net.Addr, error)
• func ParseAddressString(strAddress string, defaultPort string, tcpResolver TCPResolver) (net.Addr, error)
• type Config
  • func DefaultConfig() Config
  • func LoadConfig() (*Config, error)
  • func ValidateConfig(cfg Config, fileParser, flagParser *flags.Parser) (*Config, error)
• type ListenerCfg
• type ListenerWithSignal
• type TCPResolver

Functions

func CleanAndExpandPath

func CleanAndExpandPath(path string) string

CleanAndExpandPath expands environment variables and leading ~ in the passed path, cleans the result, and returns it. This function is taken from https://github.com/btcsuite/btcd

func ListenOnAddress

func ListenOnAddress(addr net.Addr) (net.Listener, error)

ListenOnAddress creates a listener that listens on the given address.

func Main

func Main(cfg *Config, lisCfg ListenerCfg) error

Main is the true entry point for lnd. It accepts a fully populated and validated main configuration struct and an optional listener config struct. This function starts all main system components then blocks until a signal is received on the shutdownChan at which point everything is shut down again.

func NormalizeAddresses

func NormalizeAddresses(addrs []string, defaultPort string,
	tcpResolver TCPResolver) ([]net.Addr, error)

NormalizeAddresses returns a new slice with all the passed addresses normalized with the given default port and all duplicates removed.

func ParseAddressString

func ParseAddressString(strAddress string, defaultPort string,
	tcpResolver TCPResolver) (net.Addr, error)

ParseAddressString converts an address in string format to a net.Addr that is compatible with lnd. UDP is not supported because lnd needs reliable connections. We accept a custom function to resolve any TCP addresses so that caller is able control exactly how resolution is performed.

Types

type Config

type Config struct {
	SignerDir  string `long:"signerdir" description:"The base directory that contains signer's data, logs, configuration file, etc."`
	ConfigFile string `short:"C" long:"configfile" description:"Path to configuration file"`

	TLSCertPath        string        `long:"tlscertpath" description:"Path to write the TLS certificate for lnd's RPC services"`
	TLSKeyPath         string        `long:"tlskeypath" description:"Path to write the TLS private key for lnd's RPC services"`
	TLSExtraIPs        []string      `long:"tlsextraip" description:"Adds an extra ip to the generated certificate"`
	TLSExtraDomains    []string      `long:"tlsextradomain" description:"Adds an extra domain to the generated certificate"`
	TLSAutoRefresh     bool          `long:"tlsautorefresh" description:"Re-generate TLS certificate and key if the IPs or domains are changed"`
	TLSDisableAutofill bool          `` /* 173-byte string literal not displayed */
	TLSCertDuration    time.Duration `long:"tlscertduration" description:"The duration for which the auto-generated TLS certificate will be valid for"`

	OutputMacaroon string `long:"outputmacaroon" description:"Path to write a signer macaroon for the watch-only node"`
	OutputAccounts string `long:"outputaccounts" description:"Path to write a JSON file with xpubs for the watch-only node"`
	ChanBackup     string `long:"chanbackup" description:"Path to channel.backup file for the watch-only node"`

	LogDir         string `long:"logdir" description:"Directory to log output."`
	MaxLogFiles    int    `long:"maxlogfiles" description:"Maximum logfiles to keep (0 for no rotation)"`
	MaxLogFileSize int    `long:"maxlogfilesize" description:"Maximum logfile size in MB"`

	// We'll parse these 'raw' string arguments into real net.Addrs in the
	// loadConfig function. We need to expose the 'raw' strings so the
	// command line library can access them.
	// Only the parsed net.Addrs should be used!
	RawRPCListeners []string `long:"rpclisten" description:"Add an interface/port/socket to listen for RPC connections"`
	RPCListeners    []net.Addr

	DebugLevel string `short:"d" long:"debuglevel" description:"Logging level for all subsystems {trace, debug, info, warn, error, critical}"`

	// MainNet  bool `long:"mainnet" description:"NOT RECOMMENDED: Use the main network"`
	TestNet3 bool `long:"testnet" description:"Use the test network"`
	SimNet   bool `long:"simnet" description:"Use the simulation test network"`
	RegTest  bool `long:"regtest" description:"Use the regression test network"`
	SigNet   bool `long:"signet" description:"Use the signet test network"`

	// ActiveNetParams contains parameters of the target chain.
	ActiveNetParams chaincfg.Params
	// contains filtered or unexported fields
}

Config defines the configuration options for lnd.

See LoadConfig for further details regarding the configuration loading+parsing process.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns all default values for the Config struct.

func LoadConfig

func LoadConfig() (*Config, error)

LoadConfig initializes and parses the config using a config file and command line options.

The configuration proceeds as follows:

1. Start with a default config with sane settings
2. Pre-parse the command line to check for an alternative config file
3. Load configuration file overwriting defaults with any specified options
4. Parse CLI options and overwrite/add any specified options

func ValidateConfig

func ValidateConfig(cfg Config, fileParser, flagParser *flags.Parser) (
	*Config, error)

ValidateConfig check the given configuration to be sane. This makes sure no illegal values or combination of values are set. All file system paths are normalized. The cleaned up config is returned on success.

type ListenerCfg

type ListenerCfg struct {
	// RPCListeners can be set to the listeners to use for the RPC server.
	// If empty a regular network listener will be created.
	RPCListeners []*ListenerWithSignal
}

ListenerCfg is a wrapper around custom listeners that can be passed to lnd when calling its main method.

type ListenerWithSignal

type ListenerWithSignal struct {
	net.Listener

	// Ready will be closed by the server listening on Listener.
	Ready chan struct{}

	// MacChan is an optional way to pass the admin macaroon to the program
	// that started lnd. The channel should be buffered to avoid lnd being
	// blocked on sending to the channel.
	MacChan chan []byte
}

ListenerWithSignal is a net.Listener that has an additional Ready channel that will be closed when a server starts listening.

type TCPResolver

type TCPResolver = func(network, addr string) (*net.TCPAddr, error)

TCPResolver is a function signature that resolves an address on a given network.