engines

package
v0.0.0-...-608ac5e Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2026 License: MIT Imports: 77 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Derivation paths for BitDrive keys
	BitDriveDerivationIndex = 4000
	BitDriveDerivationPath  = "m/84'/1'/0'/0/4000"
	AuthKeyPath             = "m/84'/1'/0'/1/4000"

	// Authentication tag size (8 bytes from HMAC-SHA256)
	AuthTagSize = 8

	// Metadata size (1 byte flags + 4 bytes timestamp + 4 bytes file type)
	MetadataSize = 9

	// Flag bits
	FlagEncrypted = 0x01
	FlagMultisig  = 0x02

	// Max file size (1MB)
	MaxFileSize = 1024 * 1024
)
View Source 
const (
	InputVbytes    = 68
	OutputVbytes   = 31
	OverheadVbytes = 10
)

Coin selection constants (P2WPKH)

View Source 
const (

	// ChequeWalletName is the name of the watch-only Bitcoin Core wallet for cheques
	ChequeWalletName = "cheque_watch"
)
View Source 
const (
	// TimestampPrefix is prepended to SHA256 hash in OP_RETURN to identify timestamp transactions
	TimestampPrefix = "STAMP"
)

Variables

This section is empty.

Functions

func AddDescriptorChecksum 

func AddDescriptorChecksum(desc string) (string, error)

AddDescriptorChecksum adds a checksum to a descriptor string

func BytesEqual 

func BytesEqual(a, b []byte) bool

BytesEqual performs constant-time byte comparison

func DescriptorChecksum 

func DescriptorChecksum(desc string) (string, error)

DescriptorChecksum computes the checksum for a descriptor string Implementation based on Bitcoin Core's algorithm: https://github.com/bitcoin/bitcoin/blob/master/src/script/descriptor.cpp

func DetectFileType 

func DetectFileType(content []byte) string

DetectFileType detects file type from magic bytes

func EncodeBase58Check 

func EncodeBase58Check(versionByte int, data []byte) (string, error)

EncodeBase58Check encodes data to Base58Check format

func EncodeMetadata 

func EncodeMetadata(encrypted, isMultisig bool, timestamp uint32, fileType string) string

EncodeMetadata encodes metadata into 9 bytes and returns base64

func EstimateFee 

func EstimateFee(inputCount int, numOutputs int, feeSatsPerVbyte int64) int64

EstimateFee estimates transaction fee for given parameters

func ExtractBitcoindStartupMessage 

func ExtractBitcoindStartupMessage(errMsg string) string

ExtractBitcoindStartupMessage returns a human-readable message from a -28 JSON-RPC error (e.g. "Verifying blocks…"), or "" if the error isn't a recognised startup error. Used to surface the actual phase to the UI instead of "0 / 0 blocks".

func FormatOPReturnData 

func FormatOPReturnData(metadataB64, contentStr string) string

FormatOPReturnData formats metadata and content for transaction

func HashFile 

func HashFile(path string) (string, error)

func IsBitDriveTransaction 

func IsBitDriveTransaction(opReturnMessage string) bool

IsBitDriveTransaction checks if an OP_RETURN message is a BitDrive transaction

func IsBitcoinCoreStartupError 

func IsBitcoinCoreStartupError(errMsg string) bool

IsBitcoinCoreStartupError reports whether the error originated from Bitcoin Core being mid-startup (block index load, verify, rescan, wallet load). Callers use this to back off instead of treating the failure as terminal.

func IsWalletAlreadyLoadedErr 

func IsWalletAlreadyLoadedErr(err error) bool

IsWalletAlreadyLoadedErr reports whether err is bitcoind's "-35 wallet already loaded" response. It's benign — the wallet IS loaded — so callers that loaded the wallet only to use it must treat it as success, not abort.

func NewZmqEngine 

func NewZmqEngine(endpoint string) *zmqEngine

func ParseOPReturnParts 

func ParseOPReturnParts(opReturnMessage string) (metadataB64, contentStr string, err error)

ParseOPReturnParts splits an OP_RETURN message into metadata and content parts

func ValidateBitcoinURI 

func ValidateBitcoinURI(uri string) bool

ValidateBitcoinURI checks if a string is a valid Bitcoin URI

func ValidateFileSize 

func ValidateFileSize(content []byte) error

ValidateFileSize checks if file size is within limits

func ValidateWIF 

func ValidateWIF(wif string, chainParams *chaincfg.Params) bool

ValidateWIF validates a WIF private key

func WIFToAddress 

func WIFToAddress(wifStr string, chainParams *chaincfg.Params) (string, error)

WIFToAddress converts a WIF private key to its corresponding address

Types

type BackupContents 

type BackupContents struct {
	HasWallet       bool
	HasMultisig     bool
	HasTransactions bool
}

BackupContents describes what a backup file contains.

type BackupEngine 

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

BackupEngine handles wallet backup and restore operations.

func NewBackupEngine 

func NewBackupEngine(db *sql.DB, walletDir string) *BackupEngine

NewBackupEngine creates a new BackupEngine.

func (*BackupEngine) CreateBackup 

func (e *BackupEngine) CreateBackup(ctx context.Context) ([]byte, string, error)

CreateBackup produces a ZIP archive containing wallet.json plus multisig and transaction data exported from the DB.

func (*BackupEngine) HasCurrentWallet 

func (e *BackupEngine) HasCurrentWallet() bool

HasCurrentWallet returns true if wallet.json exists.

func (*BackupEngine) RestoreBackup 

func (e *BackupEngine) RestoreBackup(ctx context.Context, data []byte, filename string) error

RestoreBackup restores wallet data from a backup file. The caller is responsible for stopping/restarting services.

func (*BackupEngine) ValidateBackup 

func (e *BackupEngine) ValidateBackup(_ context.Context, data []byte, filename string) (*BackupContents, error)

ValidateBackup validates a backup file (ZIP or JSON) and reports contents.

type Base58DecodeResult 

type Base58DecodeResult struct {
	VersionByte   int
	Payload       []byte
	Checksum      []byte
	ChecksumValid bool
	AddressType   string
}

Base58DecodeResult holds the result of Base58Check decoding

func DecodeBase58Check 

func DecodeBase58Check(input string) (*Base58DecodeResult, error)

DecodeBase58Check decodes a Base58Check string

type BitDriveEngine 

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

BitDriveEngine handles BitDrive file storage operations

func NewBitDriveEngine 

func NewBitDriveEngine(
	db *sql.DB,
	walletEngine *WalletEngine,
	dataDir string,
	chainParams *chaincfg.Params,
) *BitDriveEngine

NewBitDriveEngine creates a new BitDrive engine

func (*BitDriveEngine) DecodeMultisigData 

func (e *BitDriveEngine) DecodeMultisigData(ctx context.Context, opReturnMessage string) ([]byte, error)

DecodeMultisigData decodes multisig group data from OP_RETURN

func (*BitDriveEngine) DecodeOPReturnData 

func (e *BitDriveEngine) DecodeOPReturnData(ctx context.Context, opReturnMessage string) ([]byte, *ParsedMetadata, error)

DecodeOPReturnData decodes and optionally decrypts OP_RETURN data

func (*BitDriveEngine) Decrypt 

func (e *BitDriveEngine) Decrypt(ctx context.Context, encryptedData []byte, timestamp uint32, fileType string) ([]byte, error)

Decrypt verifies the HMAC auth tag and decrypts content

func (*BitDriveEngine) DeleteFile 

func (e *BitDriveEngine) DeleteFile(ctx context.Context, id int64) error

DeleteFile removes a file from local storage and database

func (*BitDriveEngine) DeriveKeyStream 

func (e *BitDriveEngine) DeriveKeyStream(ctx context.Context, timestamp uint32, fileType string, length int) ([]byte, error)

DeriveKeyStream derives a keystream for XOR encryption Uses SHA256(seed || counter) where seed = SHA256(privateKeyHex:timestamp:fileType)

func (*BitDriveEngine) EncodeMultisigData 

func (e *BitDriveEngine) EncodeMultisigData(ctx context.Context, jsonData []byte, encrypt bool) (string, error)

EncodeMultisigData encodes multisig group data with optional encryption

func (*BitDriveEngine) EncodeOPReturnData 

func (e *BitDriveEngine) EncodeOPReturnData(ctx context.Context, content []byte, encrypt bool) (string, string, uint32, error)

EncodeOPReturnData encodes metadata and content for OP_RETURN storage

func (*BitDriveEngine) Encrypt 

func (e *BitDriveEngine) Encrypt(ctx context.Context, content []byte, timestamp uint32, fileType string) ([]byte, error)

Encrypt encrypts content using XOR with derived keystream and appends HMAC auth tag

func (*BitDriveEngine) GetDir 

func (e *BitDriveEngine) GetDir() string

GetDir returns the BitDrive directory path

func (*BitDriveEngine) GetFileContent 

func (e *BitDriveEngine) GetFileContent(ctx context.Context, filename string) ([]byte, error)

GetFileContent reads a file from local storage

func (*BitDriveEngine) ListFiles 

func (e *BitDriveEngine) ListFiles(ctx context.Context) ([]bitdrive.File, error)

ListFiles returns all files from the database

func (*BitDriveEngine) OpenDir 

func (e *BitDriveEngine) OpenDir(ctx context.Context) error

OpenDir opens the BitDrive directory in the OS file manager.

func (*BitDriveEngine) SaveFile 

func (e *BitDriveEngine) SaveFile(ctx context.Context, txid string, content []byte, metadata *ParsedMetadata) error

SaveFile saves a file to local storage and creates a database record

func (*BitDriveEngine) WipeData 

func (e *BitDriveEngine) WipeData(ctx context.Context) error

WipeData removes all BitDrive local data

type BitcoinURI 

type BitcoinURI struct {
	Address     string
	Amount      float64
	Label       string
	Message     string
	ExtraParams map[string]string
}

BitcoinURI represents a parsed BIP-0021 Bitcoin URI

func ParseBitcoinURI 

func ParseBitcoinURI(uri string) (*BitcoinURI, error)

ParseBitcoinURI parses a BIP-0021 Bitcoin URI

type BlockResult 

type BlockResult struct {
	Height int32
	Error  error
}

BlockResult represents the result of processing a single block

type ChequeEngine 

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

ChequeEngine manages cheque derivation (ONLY) Gets seed from WalletEngine when needed

func NewChequeEngine 

func NewChequeEngine(
	walletEngine *WalletEngine,
	chainParams *chaincfg.Params,
	bitcoind *service.Service[corerpc.BitcoinServiceClient],
) *ChequeEngine

NewChequeEngine creates a new cheque engine

func (*ChequeEngine) DeriveChequeAddress 

func (e *ChequeEngine) DeriveChequeAddress(walletId string, index uint32) (string, error)

DeriveChequeAddress derives the native segwit address at m/44'/0'/999'/{index} for a specific wallet

func (*ChequeEngine) DeriveChequePrivateKey 

func (e *ChequeEngine) DeriveChequePrivateKey(walletId string, index uint32) (string, error)

DeriveChequePrivateKey derives the WIF private key at m/44'/0'/999'/{index} for a specific wallet

func (*ChequeEngine) GetChainParams 

func (e *ChequeEngine) GetChainParams() *chaincfg.Params

GetChainParams returns the chain parameters

func (*ChequeEngine) ScanForFunds 

func (e *ChequeEngine) ScanForFunds(ctx context.Context, walletId string, bitcoind corerpc.BitcoinServiceClient, count int) ([]ChequeRecovery, error)

ScanForFunds scans the first count addresses for UTXOs for a specific wallet

func (*ChequeEngine) Start 

func (e *ChequeEngine) Start(ctx context.Context) <-chan struct{}

Start begins the cheque engine background monitoring. Returned channel closes once both background goroutines have exited; runtime/test shutdown should block on it so in-flight bitcoind RPC calls don't race the gomock controller's teardown (calling t.Fatalf from a goroutine after the test ended panics).

type ChequeRecovery 

type ChequeRecovery struct {
	Index   uint32
	Address string
	Amount  uint64
	Txid    string
}

ChequeRecovery represents a recovered cheque with funds

type CoinSelectionResult 

type CoinSelectionResult struct {
	SelectedUTXOs  []*walletpb.UnspentOutput
	TotalInputSats int64
	FeeSats        int64
	ChangeSats     int64
}

CoinSelectionResult holds the result of coin selection

func SelectCoins 

func SelectCoins(
	allUTXOs []*walletpb.UnspentOutput,
	frozenOutpoints map[string]bool,
	targetSats int64,
	feeSatsPerVbyte int64,
	numOutputs int,
	strategy walletpb.CoinSelectionStrategy,
	requiredOutpoints map[string]bool,
) (*CoinSelectionResult, error)

SelectCoins selects UTXOs for a transaction using the specified strategy

type DeniabilityEngine 

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

func NewDeniability 

func NewDeniability(
	wallet *service.Service[validatorrpc.WalletServiceClient],
	bitcoind *service.Service[corerpc.BitcoinServiceClient],
	db *sql.DB,
	walletEngine *WalletEngine,
) *DeniabilityEngine

func (*DeniabilityEngine) CleanupDenials 

func (e *DeniabilityEngine) CleanupDenials(ctx context.Context) ([]*pb.ListUnspentOutputsResponse_Output, []deniability.Denial, error)

func (*DeniabilityEngine) ExecuteDenial 

func (e *DeniabilityEngine) ExecuteDenial(ctx context.Context, utxos []*pb.ListUnspentOutputsResponse_Output, denial deniability.Denial) error

func (*DeniabilityEngine) ProcessUTXO 

func (e *DeniabilityEngine) ProcessUTXO(ctx context.Context, utxo *pb.ListUnspentOutputsResponse_Output, denial deniability.Denial) error

func (*DeniabilityEngine) Run 

func (e *DeniabilityEngine) Run(ctx context.Context) error

type DetectedWithdrawal 

type DetectedWithdrawal struct {
	Txid        string    `json:"txid"`
	Sidechain   string    `json:"sidechain"`
	Amount      int64     `json:"amount"`
	Destination string    `json:"destination"`
	DetectedAt  time.Time `json:"detected_at"`
	BlockHash   *string   `json:"block_hash,omitempty"`
}

DetectedWithdrawal represents a detected fast withdrawal transaction

type HashMsg 

type HashMsg struct {
	Hash [32]byte // use encoding/hex.EncodeToString() to get it into the RPC method string format.
	Seq  uint32
}

HashMsg is a subscription event coming from a "hash"-type ZMQ message.

type InsufficientFundsError 

type InsufficientFundsError struct {
	Needed       int64
	Available    int64
	FrozenAmount int64
	Message      string
}

InsufficientFundsError is returned when there aren't enough funds

func (*InsufficientFundsError) Error 

func (e *InsufficientFundsError) Error() string

type M4Engine 

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

M4Engine manages the SCDB state and M4 message processing

func NewM4Engine 

func NewM4Engine(db *sql.DB) *M4Engine

func (*M4Engine) GetM4History 

func (e *M4Engine) GetM4History(ctx context.Context, limit int) ([]m4.M4Message, error)

GetM4History returns the last N M4 messages

func (*M4Engine) GetVotePreferences 

func (e *M4Engine) GetVotePreferences(ctx context.Context) ([]m4.VotePreference, error)

GetVotePreferences returns user's vote preferences

func (*M4Engine) GetWithdrawalBundles 

func (e *M4Engine) GetWithdrawalBundles(ctx context.Context, sidechainSlot *uint8) ([]m4.WithdrawalBundle, error)

GetWithdrawalBundles returns active withdrawal bundles for a sidechain

func (*M4Engine) ListSidechains 

func (e *M4Engine) ListSidechains(ctx context.Context) ([]m4.Sidechain, error)

ListSidechains returns all sidechains

func (*M4Engine) ProcessBlock 

func (e *M4Engine) ProcessBlock(ctx context.Context, height uint32, block *wire.MsgBlock) error

ProcessBlock processes a block for M3/M4 messages and updates SCDB state

func (*M4Engine) SetVotePreference 

func (e *M4Engine) SetVotePreference(ctx context.Context, sidechainSlot uint8, voteType m4.VoteType, bundleHash *string) error

SetVotePreference sets user's vote preference for a sidechain

type MerkleTreeResult 

type MerkleTreeResult struct {
	MerkleRoot    string
	Levels        [][]string
	RCBLevels     [][]string // Reversed Concatenated Bytes
	FormattedText string
}

MerkleTreeResult holds the result of Merkle tree calculation

func CalculateMerkleTree 

func CalculateMerkleTree(txids []string) (*MerkleTreeResult, error)

CalculateMerkleTree calculates the Merkle tree from transaction IDs

type NotificationBroadcaster 

type NotificationBroadcaster interface {
	Broadcast(ctx context.Context, event *notificationv1.WatchResponse)
}

NotificationBroadcaster interface for testability

type NotificationEngine 

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

func NewNotificationEngine 

func NewNotificationEngine(
	db *sql.DB,
	bitcoind *service.Service[corerpc.BitcoinServiceClient],
) *NotificationEngine

func (*NotificationEngine) Broadcast 

func (e *NotificationEngine) Broadcast(ctx context.Context, event *notificationv1.WatchResponse)

Broadcast sends a notification event to all subscribers (public method)

func (*NotificationEngine) Run 

func (e *NotificationEngine) Run(ctx context.Context) error

func (*NotificationEngine) Subscribe 

func (e *NotificationEngine) Subscribe(ctx context.Context) <-chan *notificationv1.WatchResponse

type PaperWalletKeypair 

type PaperWalletKeypair struct {
	PrivateKeyWIF string
	PublicAddress string
	PrivateKeyHex string
}

PaperWalletKeypair holds a generated paper wallet keypair

func GeneratePaperWallet 

func GeneratePaperWallet(chainParams *chaincfg.Params) (*PaperWalletKeypair, error)

GeneratePaperWallet generates a new random keypair for paper wallets

type ParsedMetadata 

type ParsedMetadata struct {
	Encrypted  bool
	IsMultisig bool
	Timestamp  uint32
	FileType   string
}

ParsedMetadata contains parsed BitDrive OP_RETURN metadata

func ParseMetadata 

func ParseMetadata(metadataB64 string) (*ParsedMetadata, error)

ParseMetadata parses the 9-byte metadata from base64

type Parser 

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

Parser is responsible for parsing blocks from bitcoind and storing OP_RETURN data in SQLite

func NewBitcoind 

func NewBitcoind(
	bitcoind *service.Service[corerpc.BitcoinServiceClient],
	db *sql.DB,
	conf config.Config,
) *Parser

func (*Parser) HandleNewRawTransaction 

func (p *Parser) HandleNewRawTransaction(
	ctx context.Context, tx *wire.MsgTx,
) error

HandleNewRawTransaction can be called on a brand new transaction from the mempool.

func (*Parser) Run 

func (p *Parser) Run(ctx context.Context) error

Run runs the engine. It checks if a new block has been mined, and if so, handles it!

Should be started in a goroutine.

func (*Parser) SetCoinnewsLogger 

func (p *Parser) SetCoinnewsLogger(logger *zerolog.Logger)

SetCoinnewsLogger attaches a dedicated logger for coinnews sync events. Passing nil disables coinnews-sync logging.

type PendingFastWithdrawal 

type PendingFastWithdrawal struct {
	Hash           string    `json:"hash"`            // Withdrawal hash from server
	Sidechain      string    `json:"sidechain"`       // Which sidechain
	ServerAddress  string    `json:"server_address"`  // L2 address to send to
	ExpectedAmount int64     `json:"expected_amount"` // Amount expected (sats)
	ServerURL      string    `json:"server_url"`      // Fast withdrawal server URL
	CreatedAt      time.Time `json:"created_at"`
}

PendingFastWithdrawal represents a fast withdrawal waiting for L2 payment

type RawMsg 

type RawMsg struct {
	Serialized []byte // use encoding/hex.EncodeToString() to get it into the RPC method string format.
	Seq        uint32
}

RawMsg is a subscription event coming from a "raw"-type ZMQ message.

type SequenceEvent 

type SequenceEvent int

SequenceEvent is an enum describing what event triggered the sequence message. 

const (
	Invalid            SequenceEvent = iota
	BlockConnected                   // Blockhash connected
	BlockDisconnected                // Blockhash disconnected
	TransactionRemoved               // Transactionhash removed from mempool for non-block inclusion reason
	TransactionAdded                 // Transactionhash added mempool
)

type SequenceMsg 

type SequenceMsg struct {
	Hash       [32]byte // use encoding/hex.EncodeToString() to get it into the RPC method string format.
	Event      SequenceEvent
	MempoolSeq uint64
}

SequenceMsg is a subscription event coming from a "sequence" ZMQ message.

type SidechainMonitorEngine 

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

SidechainMonitorEngine monitors all sidechains for fast withdrawal transactions

func NewSidechainMonitorEngine 

func NewSidechainMonitorEngine(
	thunder *service.Service[*thunder.Client],
	bitnames *service.Service[*bitnames.Client],
	bitassets *service.Service[*bitassets.Client],
	truthcoin *service.Service[*truthcoin.Client],
	photon *service.Service[*photon.Client],
	coinshift *service.Service[*coinshift.Client],
	notificationEngine NotificationBroadcaster,
) *SidechainMonitorEngine

NewSidechainMonitorEngine creates a new sidechain monitoring engine

func (*SidechainMonitorEngine) GetDetectedWithdrawals 

func (e *SidechainMonitorEngine) GetDetectedWithdrawals(ctx context.Context) ([]DetectedWithdrawal, error)

GetDetectedWithdrawals returns all detected withdrawals

func (*SidechainMonitorEngine) GetPendingFastWithdrawals 

func (e *SidechainMonitorEngine) GetPendingFastWithdrawals(ctx context.Context) ([]PendingFastWithdrawal, error)

GetPendingFastWithdrawals returns all pending fast withdrawals

func (*SidechainMonitorEngine) GetWithdrawalByTxid 

func (e *SidechainMonitorEngine) GetWithdrawalByTxid(ctx context.Context, txid string) (*DetectedWithdrawal, error)

GetWithdrawalByTxid returns a specific withdrawal by transaction ID

func (*SidechainMonitorEngine) RegisterPendingFastWithdrawal 

func (e *SidechainMonitorEngine) RegisterPendingFastWithdrawal(ctx context.Context, withdrawal PendingFastWithdrawal) error

RegisterPendingFastWithdrawal adds a pending fast withdrawal to monitor for

func (*SidechainMonitorEngine) Run 

func (e *SidechainMonitorEngine) Run(ctx context.Context) error

Run starts the monitoring engine

type TimestampEngine 

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

func NewTimestampEngine 

func NewTimestampEngine(
	db *sql.DB,
	log zerolog.Logger,
	wallet WalletService,
	bitcoind *service.Service[corerpc.BitcoinServiceClient],
) *TimestampEngine

func (*TimestampEngine) GetTimestamp 

func (e *TimestampEngine) GetTimestamp(ctx context.Context, id int64) (*timestamps.FileTimestamp, error)

func (*TimestampEngine) ListTimestamps 

func (e *TimestampEngine) ListTimestamps(ctx context.Context) ([]timestamps.FileTimestamp, error)

func (*TimestampEngine) Run 

func (e *TimestampEngine) Run(ctx context.Context) error

func (*TimestampEngine) TimestampFile 

func (e *TimestampEngine) TimestampFile(ctx context.Context, filename string, fileData []byte) (*timestamps.FileTimestamp, error)

func (*TimestampEngine) VerifyTimestamp 

func (e *TimestampEngine) VerifyTimestamp(ctx context.Context, fileData []byte, filename string) (*timestamps.FileTimestamp, error)

type UTXO 

type UTXO struct {
	TxID   string
	Vout   int32
	Amount uint64
}

type WalletAdapter 

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

WalletAdapter adapts the wallet engine for the timestamp engine, routing OP_RETURN broadcasts through the active wallet's backend (electrum or enforcer).

func NewWalletAdapter 

func NewWalletAdapter(engine *WalletEngine) *WalletAdapter

func (*WalletAdapter) SendTransaction 

func (w *WalletAdapter) SendTransaction(ctx context.Context, opReturnData []byte) (string, error)

type WalletEngine 

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

WalletEngine handles wallet unlock/lock, backend routing, and Bitcoin Core sync. When an orchestrator client is set, core wallet operations are delegated to the orchestrator's WalletManagerService.

func NewWalletEngine 

func NewWalletEngine(
	bitcoindConnector func(context.Context) (corerpc.BitcoinServiceClient, error),
	enforcerConnector func(context.Context) (validatorrpc.WalletServiceClient, error),
	walletDir string,
	chainParams *chaincfg.Params,
) *WalletEngine

NewWalletEngine creates a new unified wallet engine

func (*WalletEngine) BroadcastOpReturn 

func (e *WalletEngine) BroadcastOpReturn(ctx context.Context, data []byte, feeSatPerVByte, feeSats uint64) (string, error)

BroadcastOpReturn publishes raw OP_RETURN data through the active wallet's backend and returns the txid. Electrum wallets run no local enforcer, so they broadcast through the orchestrator wallet manager — the same path the normal "Send" flow uses; enforcer and Bitcoin Core wallets use the enforcer wallet. This is the single broadcast seam every server-side OP_RETURN sender shares.

func (*WalletEngine) CombinePsbt 

func (e *WalletEngine) CombinePsbt(ctx context.Context, psbtsBase64 []string) (string, error)

CombinePsbt merges cosigner PSBTs of the same transaction.

func (*WalletEngine) CreateBitcoinCoreWalletFromSeed 

func (e *WalletEngine) CreateBitcoinCoreWalletFromSeed(
	ctx context.Context,
	walletName string,
	seedHex string,
	accountIndex uint32,
	derivationPath string,
) error

CreateBitcoinCoreWalletFromSeed creates a Bitcoin Core wallet and imports the seed. accountIndex/derivationPath are the optional account-level derivation override (0/"" = standard BIP84+BIP86 at account 0).

func (*WalletEngine) CreatePsbt 

func (e *WalletEngine) CreatePsbt(ctx context.Context, req *orchpb.CreatePsbtRequest) (string, error)

CreatePsbt builds an unsigned PSBT for an electrum-wallet send via the orchestrator and returns it base64-encoded.

func (*WalletEngine) EnsureBitcoinCoreWallet 

func (e *WalletEngine) EnsureBitcoinCoreWallet(ctx context.Context, walletId string) (string, error)

EnsureBitcoinCoreWallet ensures a Bitcoin Core wallet exists for the given walletId Creates it from the seed if it doesn't exist (lazy loading).

Concurrent callers for the same walletId are coalesced via singleflight so only one CreateWallet/LoadWallet against bitcoind is in flight at a time. Without this, each frontend poll would queue another loadwallet RPC and hit "-4: Wallet already loading" while Core was busy.

func (*WalletEngine) EnsureWatchOnlyWallet 

func (e *WalletEngine) EnsureWatchOnlyWallet(ctx context.Context, walletId string) (string, error)

EnsureWatchOnlyWallet ensures a watch-only wallet exists in Bitcoin Core

func (*WalletEngine) FinalizePsbt 

func (e *WalletEngine) FinalizePsbt(ctx context.Context, psbtBase64 string) (string, error)

FinalizePsbt extracts the raw transaction from a fully-signed PSBT.

func (*WalletEngine) GetActiveWallet 

func (e *WalletEngine) GetActiveWallet(ctx context.Context) (*WalletInfo, error)

GetActiveWallet returns the active wallet If the wallet is encrypted, it uses the unlocked data from memory If the wallet is unencrypted, it reads directly from wallet.json

func (*WalletEngine) GetActiveWalletInfo 

func (e *WalletEngine) GetActiveWalletInfo(ctx context.Context) (*WalletInfo, error)

GetActiveWalletInfo returns the WalletInfo for the currently active wallet This is an alias for GetActiveWallet for backwards compatibility

func (*WalletEngine) GetAllWallets 

func (e *WalletEngine) GetAllWallets(ctx context.Context) ([]WalletInfo, error)

func (*WalletEngine) GetBitcoinCoreWalletName 

func (e *WalletEngine) GetBitcoinCoreWalletName(ctx context.Context, walletId string) (string, error)

GetBitcoinCoreWalletName returns the Bitcoin Core wallet name for a walletId

func (*WalletEngine) GetChainParams 

func (e *WalletEngine) GetChainParams() *chaincfg.Params

GetChainParams returns the chain parameters for this wallet engine

func (*WalletEngine) GetElectrumBalance 

func (e *WalletEngine) GetElectrumBalance(ctx context.Context, walletId string) (confirmed, pending uint64, err error)

GetElectrumBalance returns the confirmed and pending balance (in sats) for an electrum wallet from the orchestrator's Esplora-backed provider.

func (*WalletEngine) GetElectrumReceiveAddress 

func (e *WalletEngine) GetElectrumReceiveAddress(ctx context.Context, walletId string) (string, error)

GetElectrumReceiveAddress returns a fresh receive address for an electrum wallet from the orchestrator, which derives it locally and serves chain data over Esplora (no Bitcoin Core).

func (*WalletEngine) GetElectrumTransactions 

func (e *WalletEngine) GetElectrumTransactions(ctx context.Context, walletId string) ([]*orchpb.TransactionEntry, error)

GetElectrumTransactions returns an electrum wallet's transactions from the orchestrator, which serves them over Esplora.

func (*WalletEngine) GetElectrumUnspent 

func (e *WalletEngine) GetElectrumUnspent(ctx context.Context, walletId string) ([]*orchpb.UnspentOutput, error)

GetElectrumUnspent returns an electrum wallet's UTXOs from the orchestrator, which serves them over Esplora.

func (*WalletEngine) GetEnforcerSeed 

func (e *WalletEngine) GetEnforcerSeed() (string, error)

GetEnforcerSeed returns the enforcer wallet's seed hex Used by ChequeEngine for deriving cheque addresses

func (*WalletEngine) GetWalletBackendType 

func (e *WalletEngine) GetWalletBackendType(ctx context.Context, walletId string) (WalletType, error)

GetWalletBackendType returns the backend type for a wallet

func (*WalletEngine) GetWalletInfo 

func (e *WalletEngine) GetWalletInfo(ctx context.Context, walletId string) (*WalletInfo, error)

GetWalletInfo reads wallet.json and returns info for the specified walletId

func (*WalletEngine) GetWalletSeed 

func (e *WalletEngine) GetWalletSeed(walletId string) (string, error)

GetWalletSeed returns the seed hex for a specific wallet by ID Used by ChequeEngine for per-wallet cheque address derivation

func (*WalletEngine) IsUnlocked 

func (e *WalletEngine) IsUnlocked() bool

IsUnlocked returns whether the engine is unlocked

func (*WalletEngine) IsWatchOnly 

func (e *WalletEngine) IsWatchOnly(ctx context.Context, walletId string) (bool, error)

IsWatchOnly reports whether the wallet has no signing key (watch-only), orthogonal to its provider type.

func (*WalletEngine) Lock 

func (e *WalletEngine) Lock()

Lock drops the in-memory seed and wallet cache. The seed string itself can't be zeroed in place (Go strings are immutable) — it lingers until GC.

func (*WalletEngine) RequireFullNode 

func (e *WalletEngine) RequireFullNode(ctx context.Context, op string) error

RequireFullNode returns a clear error when the active wallet is electrum, for L1 operations (sidechain proposals, withdrawal bundles) that can only be produced by a full node with the BIP300/301 enforcer — they live in the block coinbase / are built by the enforcer, so no standalone wallet can broadcast them. Returns nil when the wallet type can't be determined, so the caller's own error path still runs.

func (*WalletEngine) SendTransaction 

func (e *WalletEngine) SendTransaction(ctx context.Context, req *orchpb.SendTransactionRequest) (string, error)

SendTransaction builds, signs, and broadcasts a transaction through the orchestrator wallet manager, which routes to the active wallet's backend (electrum or Bitcoin Core). Used by server-side senders like news OP_RETURNs.

func (*WalletEngine) SetOrchestratorClient 

func (e *WalletEngine) SetOrchestratorClient(client orchrpc.WalletManagerServiceClient)

SetOrchestratorClient sets the orchestrator WalletManagerService client. When set, core wallet operations delegate to the orchestrator.

func (*WalletEngine) SignPsbt 

func (e *WalletEngine) SignPsbt(ctx context.Context, walletId, psbtBase64 string) (string, error)

SignPsbt adds an electrum wallet's signatures to a base64 PSBT.

func (*WalletEngine) SyncWallets 

func (e *WalletEngine) SyncWallets(ctx context.Context) error

SyncWallets syncs Bitcoin Core wallets from wallet.json to Bitcoin Core This is called after wallet unlock to ensure all Bitcoin Core wallets exist

func (*WalletEngine) Unlock 

func (e *WalletEngine) Unlock(walletData map[string]any) error

Unlock loads the seed into memory from decrypted wallet data

type WalletInfo 

type WalletInfo struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	WalletType WalletType `json:"wallet_type"`
	Master     struct {
		SeedHex string `json:"seed_hex"`
	} `json:"master"`
	L1 struct {
		Mnemonic string `json:"mnemonic"`
	} `json:"l1"`
	WatchOnly *struct {
		Descriptor string `json:"descriptor"`
		Xpub       string `json:"xpub"`
	} `json:"watch_only,omitempty"`
	// AccountIndex shifts the standard BIP84/BIP86 descriptors to this account.
	// 0 = standard. Mutually exclusive with DerivationPath.
	AccountIndex uint32 `json:"account_index,omitempty"`
	// DerivationPath is an explicit account-level path (m/purpose'/coin'/account')
	// overriding purpose/coin/account; empty = standard purposes at AccountIndex.
	DerivationPath string `json:"derivation_path,omitempty"`
}

WalletInfo contains information about a wallet from wallet.json

func (*WalletInfo) IsWatchOnly 

func (w *WalletInfo) IsWatchOnly() bool

IsWatchOnly reports whether the wallet holds no signing key — it carries an xpub/descriptor payload instead of a seed. Orthogonal to the provider type.

type WalletService 

type WalletService interface {
	SendTransaction(ctx context.Context, opReturnData []byte) (string, error)
}

WalletService interface for sending transactions

type WalletType 

type WalletType string

WalletType is a wallet's provider backend. Watch-only is an orthogonal capability (the watch_only payload), not a provider. 

const (
	WalletTypeEnforcer    WalletType = "enforcer"
	WalletTypeBitcoinCore WalletType = "bitcoinCore"
	WalletTypeElectrum    WalletType = "electrum"
)

type ZMQ 

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

ZMQEngine receives raw, unconfirmed transactions from bitcoind via ZMQ. Processes them and broadcasts them to the rest of the system.

func NewZMQ 

func NewZMQ(endpoint string) (*ZMQ, error)

NewZMQ creates a new ZMQ engine for receiving Bitcoin Core raw transaction notifications

func (*ZMQ) Run 

func (e *ZMQ) Run(ctx context.Context) error

Run starts the ZMQ engine and begins listening for raw transaction notifications

func (*ZMQ) Subscribe 

func (e *ZMQ) Subscribe() <-chan *wire.MsgTx

Subscribe returns a channel that will receive new transactions

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.