address

package
v0.0.0-...-c180733 Latest Latest
Warning

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

Go to latest
Published: Jan 22, 2026 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package address provides address generation, storage, and subscription management for blockchain addresses. It supports BIP-39/44 HD wallet derivation.

Index

Constants

View Source
const (
	DefaultEntropyBitLen = 128
)

DefaultEntropyBitLen is the default entropy length (128 bits = 12 word mnemonic).

Variables

View Source
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

func (m *Address) Decode(b []byte) error

Decode deserializes the address from bytes. Implements storage.Data interface.

func (*Address) Encode

func (m *Address) Encode() []byte

Encode serializes the address to bytes using gob encoding. Implements storage.Data interface.

func (*Address) GetKey

func (a *Address) GetKey() []byte

GetKey returns the address bytes as storage key. Implements storage.Key interface.

func (*Address) String

func (a *Address) String() string

String returns the address string representation.

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.

func (*Config) Load

func (c *Config) Load() (err error)

Load reads the configuration from storage. Performs cold start with defaults if no config exists.

func (*Config) Save

func (c *Config) Save() (err error)

Save persists the configuration to storage as JSON.

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

func (p *Manager) AddAddressRecord(address *Address) (err error)

AddAddressRecord adds a single address record to the pool. Returns ErrAddressExists if the address already exists.

func (*Manager) AddAddressRecordsBulk

func (p *Manager) AddAddressRecordsBulk(addresses []*Address) (err error)

AddAddressRecordsBulk adds multiple address records in bulk. Skips addresses that already exist.

func (*Manager) AddPrivateKey

func (p *Manager) AddPrivateKey(privateKeyBytes []byte) (address string, err error)

AddPrivateKey adds an address by its raw private key bytes.

func (*Manager) AddPrivateKeyHex

func (p *Manager) AddPrivateKeyHex(privateKeyHex string) (address string, err error)

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

func (p *Manager) GenerateBit44Address() (addressRecord *Address, err error)

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

func (p *Manager) GenerateBit44AddressWithLen(mnemonicLen int) (addressRecord *Address, err error)

GenerateBit44AddressWithLen creates a new BIP-44 HD wallet address with a custom mnemonic length (12 or 24 words).

func (*Manager) GetAddress

func (p *Manager) GetAddress(address string) (addressRecord *Address, err error)

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

func (p *Manager) IsAddressKnown(address string) bool

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

func (p *Manager) RecoverBit44Address(mnemonic []string) (addressRecord *Address, err error)

RecoverBit44Address recovers a BIP-44 HD wallet address from an existing mnemonic phrase. Returns the address derived from the mnemonic.

func (*Manager) WalkAllAddresses

func (p *Manager) WalkAllAddresses(walker func(address *Address))

WalkAllAddresses iterates over all addresses and calls walker for each. Thread-safe read operation.

type MemPoolOption

type MemPoolOption func(pool *Manager) error

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

Jump to

Keyboard shortcuts

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