Documentation
¶
Overview ¶
Package address provides address generation, storage, and subscription management for blockchain addresses. It supports BIP-39/44 HD wallet derivation.
Index ¶
- Constants
- Variables
- type Address
- type AddressCodec
- type Config
- type Manager
- func (p *Manager) AddAddressFill(addressString string, fill func(a *Address)) (addressRecord *Address, err error)
- func (p *Manager) AddAddressRecord(address *Address) (err error)
- func (p *Manager) AddAddressRecordsBulk(addresses []*Address) (err error)
- func (p *Manager) AddPrivateKey(privateKeyBytes []byte) (address string, err error)
- func (p *Manager) AddPrivateKeyHex(privateKeyHex string) (address string, err error)
- func (p *Manager) AddPrivateKeyHexFill(privateKeyHex string, fillParams func(address *Address)) (addressString string, err error)
- func (p *Manager) DevCheckMemPool()
- func (p *Manager) DevDumpMemPool()
- func (p *Manager) GenerateBit44Address() (addressRecord *Address, err error)
- func (p *Manager) GenerateBit44AddressWithLen(mnemonicLen int) (addressRecord *Address, err error)
- func (p *Manager) GetAddress(address string) (addressRecord *Address, err error)
- func (p *Manager) GetFreeAddressAndSubscribe(serviceId int, userId, invoiceId int64, watchOnly bool) (addressRecord *Address, err error)
- func (p *Manager) IsAddressKnown(address string) bool
- func (p *Manager) NewAddressRecord(addressString string, privateKey []byte) (addressRecord *Address, err error)
- func (p *Manager) NewAddressRecordFill(addressString string, fill func(a *Address)) (addressRecord *Address, err error)
- func (p *Manager) RecoverBit44Address(mnemonic []string) (addressRecord *Address, err error)
- func (p *Manager) WalkAllAddresses(walker func(address *Address))
- type MemPoolOption
- type ObjectsSource
Constants ¶
const (
DefaultEntropyBitLen = 128
)
DefaultEntropyBitLen is the default entropy length (128 bits = 12 word mnemonic).
Variables ¶
var ( // ErrAddressUnknown is returned when an address is not found in the pool. ErrAddressUnknown = errors.New("unknown address") // ErrAddressExists is returned when trying to add an existing address. ErrAddressExists = errors.New("address already exists") // ErrConfigStorageEmpty is returned when config storage is not set. ErrConfigStorageEmpty = errors.New("config storage not set") // ErrNoFreeAddresses is returned when no free addresses are available. ErrNoFreeAddresses = errors.New("no free addresses") // ErrInvalidAddressBytes is returned for invalid address byte length. ErrInvalidAddressBytes = errors.New("invalid address bytes") // ErrInvalidAddress is returned for malformed address strings. ErrInvalidAddress = errors.New("invalid address string") // ErrAddressBytesEmpty is returned when address bytes are empty. ErrAddressBytesEmpty = errors.New("address bytes empty") // ErrAddressStringEmpty is returned when address string is empty. ErrAddressStringEmpty = errors.New("address string empty") // ErrPrivateKeyEmpty is returned when private key is required but empty. ErrPrivateKeyEmpty = errors.New("private key empty") // ErrAddressPrivateKeyMismatch is returned when address doesn't match private key. ErrAddressPrivateKeyMismatch = errors.New("address and private key mismatch") // ErrInvalidMnemonicLen is returned for invalid BIP-39 mnemonic length. ErrInvalidMnemonicLen = errors.New("invalid mnemonic length") )
Error definitions for address operations.
Functions ¶
This section is empty.
Types ¶
type Address ¶
type Address struct {
// Address is the human-readable address string (e.g., 0x...).
Address string `json:"address" storm:"id"`
// AddressBytes is the raw 20-byte address.
AddressBytes []byte `json:"addressBytes" storm:"index"`
// PrivateKey is the 32-byte private key (nil for watch-only).
PrivateKey []byte `json:"privateKey"`
// Master indicates if this is a master/root address.
Master bool `json:"master"`
// Subscribed indicates if the address is subscribed for notifications.
Subscribed bool `json:"subscribed"`
// ServiceId is the subscriber's service identifier.
ServiceId int `json:"serviceId"`
// UserId is the subscriber's user identifier.
UserId int64 `json:"userId"`
// InvoiceId is the associated invoice identifier.
InvoiceId int64 `json:"invoiceId"`
// WatchOnly indicates the address has no private key.
WatchOnly bool `json:"watchOnly"`
// Bip39Support indicates BIP-39 mnemonic support.
Bip39Support bool `json:"bip39Support,omitempty"`
// Bip39Mnemonic stores the BIP-39 mnemonic words.
Bip39Mnemonic []string `json:"bip39Mnemonic,omitempty"`
}
Address represents a blockchain address with its associated data. Supports both regular addresses and HD wallet addresses (BIP-39/44).
func (*Address) Decode ¶
Decode deserializes the address from bytes. Implements storage.Data interface.
func (*Address) Encode ¶
Encode serializes the address to bytes using gob encoding. Implements storage.Data interface.
type AddressCodec ¶
type AddressCodec interface {
// EncodeBytesToAddress converts raw bytes to address string.
EncodeBytesToAddress(addressBytes []byte) (string, error)
// DecodeAddressToBytes converts address string to raw bytes.
DecodeAddressToBytes(address string) ([]byte, error)
// PrivateKeyToAddress derives address from private key.
PrivateKeyToAddress(privateKey []byte) (string, []byte, error)
// IsValid checks if an address string is valid.
IsValid(address string) bool
}
AddressCodec defines the interface for address encoding/decoding. Implementations are chain-specific (e.g., Ethereum, Bitcoin).
type Config ¶
type Config struct {
Debug bool `json:"debug"`
EnableAddressGenerate bool `json:"enableAddressGenerate"`
MinFreePoolSize int `json:"minFreePoolSize"`
GeneratePoolUpTo int `json:"generatePoolUpTo"`
Bip39Support bool `json:"bip39Support"`
Bip36MnemonicLen int `json:"bip36MnemonicLen"`
Bip44CoinType string `json:"bip44CoinType"`
Bip32DerivationPath string `json:"bip32DerivationPath"`
// contains filtered or unexported fields
}
Config holds the address pool configuration settings. Controls address generation, pool sizes, and BIP-39/44 HD wallet settings.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages a pool of blockchain addresses. It maintains separate pools for all addresses and free (unsubscribed) addresses. Thread-safe for concurrent access.
func NewManager ¶
func NewManager(options ...MemPoolOption) (pool *Manager, err error)
NewManager creates a new address manager with the specified options. Loads existing addresses from storage and initializes the free address pool.
func (*Manager) AddAddressFill ¶
func (p *Manager) AddAddressFill(addressString string, fill func(a *Address)) (addressRecord *Address, err error)
AddAddressFill adds an address with custom initialization via fill function.
func (*Manager) AddAddressRecord ¶
AddAddressRecord adds a single address record to the pool. Returns ErrAddressExists if the address already exists.
func (*Manager) AddAddressRecordsBulk ¶
AddAddressRecordsBulk adds multiple address records in bulk. Skips addresses that already exist.
func (*Manager) AddPrivateKey ¶
AddPrivateKey adds an address by its raw private key bytes.
func (*Manager) AddPrivateKeyHex ¶
AddPrivateKeyHex adds an address by its private key in hex format.
func (*Manager) AddPrivateKeyHexFill ¶
func (p *Manager) AddPrivateKeyHexFill(privateKeyHex string, fillParams func(address *Address)) (addressString string, err error)
AddPrivateKeyHexFill adds an address by its hex-encoded private key with custom initialization. The fillParams function allows setting additional fields on the address record.
func (*Manager) DevCheckMemPool ¶
func (p *Manager) DevCheckMemPool()
DevCheckMemPool is a development utility that verifies the fast pool consistency. Checks that all addresses in allAddresses can be found in the fast lookup pool.
func (*Manager) DevDumpMemPool ¶
func (p *Manager) DevDumpMemPool()
DevDumpMemPool is a development utility that logs all addresses in the pool. Outputs address string, subscription state, service/user/invoice IDs, and watch state.
func (*Manager) GenerateBit44Address ¶
GenerateBit44Address creates a new BIP-44 HD wallet address using the configured mnemonic length and coin type. Returns an address with BIP-39 mnemonic.
func (*Manager) GenerateBit44AddressWithLen ¶
GenerateBit44AddressWithLen creates a new BIP-44 HD wallet address with a custom mnemonic length (12 or 24 words).
func (*Manager) GetAddress ¶
GetAddress retrieves an address record by address string. Returns ErrAddressUnknown if not found. Thread-safe.
func (*Manager) GetFreeAddressAndSubscribe ¶
func (p *Manager) GetFreeAddressAndSubscribe(serviceId int, userId, invoiceId int64, watchOnly bool) (addressRecord *Address, err error)
GetFreeAddressAndSubscribe retrieves a free address and subscribes it. Marks the address as subscribed with the given service/user/invoice IDs. Triggers pool refill if needed. Thread-safe.
func (*Manager) IsAddressKnown ¶
IsAddressKnown checks if an address is managed by this pool. Thread-safe operation.
func (*Manager) NewAddressRecord ¶
func (p *Manager) NewAddressRecord(addressString string, privateKey []byte) (addressRecord *Address, err error)
NewAddressRecord creates a new address record with the given address and private key.
func (*Manager) NewAddressRecordFill ¶
func (p *Manager) NewAddressRecordFill(addressString string, fill func(a *Address)) (addressRecord *Address, err error)
NewAddressRecordFill creates a new address record with custom initialization. The fill function allows setting additional fields before validation.
func (*Manager) RecoverBit44Address ¶
RecoverBit44Address recovers a BIP-44 HD wallet address from an existing mnemonic phrase. Returns the address derived from the mnemonic.
func (*Manager) WalkAllAddresses ¶
WalkAllAddresses iterates over all addresses and calls walker for each. Thread-safe read operation.
type MemPoolOption ¶
MemPoolOption is a function that configures a Manager.
func WithAddressCodec ¶
func WithAddressCodec(codec AddressCodec) MemPoolOption
WithAddressCodec sets the address encoder/decoder.
func WithAddressStorage ¶
func WithAddressStorage(store storage.SimpleStorage) MemPoolOption
WithAddressStorage sets the storage backend for addresses.
func WithConfigStorage ¶
func WithConfigStorage(store storage.BinStorage) MemPoolOption
WithConfigStorage sets the storage backend for configuration.
type ObjectsSource ¶
type ObjectsSource interface {
// AppendKeys should append the keys of the maps to the supplied slice and return the resulting slice
AppendKeys([]string) []string
// Get should return the value for the supplied key
Get(string) *Address
}
ObjectsSource is for supplying data to initialise fastStore