Documentation
¶
Overview ¶
Package db provides optional SQLite-backed persistence for buildoor runtime state: settings overrides, won blocks, validator registrations, proposer preferences and an audit log. It mirrors the database patterns used by the sibling spamoor project (glebarez/go-sqlite + sqlx + goose migrations).
Persistence is opt-in: when the configured file path is empty the Database runs in a disabled mode where every method is a no-op (reads return empty, writes are dropped). This keeps callers free of nil-checks while preserving the original in-memory-only behaviour when --state-db is not set.
Index ¶
- Constants
- type AuditLog
- type Config
- type Database
- func (d *Database) AddWonBlock(wb WonBlock) error
- func (d *Database) AppendAuditLog(entry AuditLog) error
- func (d *Database) Close() error
- func (d *Database) Enabled() bool
- func (d *Database) GetAuditLogs(offset, limit int) ([]AuditLog, int, error)
- func (d *Database) GetProposerPreferences(limit int) ([]ProposerPreference, error)
- func (d *Database) GetSettings() ([]SettingRow, error)
- func (d *Database) GetValidatorRegistrations() ([]ValidatorRegistration, error)
- func (d *Database) GetWonBlocks(offset, limit int) ([]WonBlock, int, error)
- func (d *Database) Init() error
- func (d *Database) PutProposerPreference(p ProposerPreference) error
- func (d *Database) PutSetting(row SettingRow) error
- func (d *Database) PutValidatorRegistration(reg ValidatorRegistration) error
- func (d *Database) RunDBTransaction(handler func(tx *sqlx.Tx) error) error
- type ProposerPreference
- type SettingRow
- type ValidatorRegistration
- type WonBlock
Constants ¶
const ( WonBlockSourceBuilderAPI = "builder_api" WonBlockSourceEPBS = "epbs" )
WonBlockSource identifies which subsystem delivered a won block.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuditLog ¶
type AuditLog struct {
ID int64 `db:"id" json:"id"`
Timestamp int64 `db:"timestamp" json:"timestamp"`
Actor string `db:"actor" json:"actor"`
RemoteAddr string `db:"remote_addr" json:"remote_addr"`
Action string `db:"action" json:"action"`
Target string `db:"target" json:"target"`
Detail string `db:"detail" json:"detail"`
Result string `db:"result" json:"result"`
}
AuditLog records a single authenticated mutating action against the API.
type Config ¶
type Config struct {
// File is the path to the SQLite database file. When empty the database
// is disabled and all operations become no-ops.
File string
// MaxOpenConns and MaxIdleConns bound the connection pool. Zero values
// fall back to sensible defaults.
MaxOpenConns int
MaxIdleConns int
}
Config configures the SQLite database connection.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database wraps a SQLite connection and exposes the buildoor persistence repositories. A single connection is shared for reads and writes; writes are serialised by writerMutex to avoid "database is locked" under WAL.
func NewDatabase ¶
func NewDatabase(config *Config, logger logrus.FieldLogger) *Database
NewDatabase creates a Database. When config.File is empty the database is disabled and Init/repository methods become no-ops.
func (*Database) AddWonBlock ¶
AddWonBlock inserts a won block and prunes the table to maxWonBlocks rows. No-op when the database is disabled.
func (*Database) AppendAuditLog ¶
AppendAuditLog inserts an audit entry and prunes the table to maxAuditLogs rows. No-op when the database is disabled.
func (*Database) Enabled ¶
Enabled reports whether persistence is active (a file path was configured).
func (*Database) GetAuditLogs ¶
GetAuditLogs returns a page of audit entries (newest first) and the total count. Returns an empty page when the database is disabled.
func (*Database) GetProposerPreferences ¶
func (d *Database) GetProposerPreferences(limit int) ([]ProposerPreference, error)
GetProposerPreferences returns up to limit most-recent proposer preferences (highest slot first). Returns an empty slice when the database is disabled.
func (*Database) GetSettings ¶
func (d *Database) GetSettings() ([]SettingRow, error)
GetSettings returns all persisted settings rows. Returns an empty slice when the database is disabled.
func (*Database) GetValidatorRegistrations ¶
func (d *Database) GetValidatorRegistrations() ([]ValidatorRegistration, error)
GetValidatorRegistrations returns all persisted validator registrations. Returns an empty slice when the database is disabled.
func (*Database) GetWonBlocks ¶
GetWonBlocks returns a page of won blocks (newest first) and the total count. Returns an empty page when the database is disabled.
func (*Database) Init ¶
Init opens the SQLite connection (WAL mode) and applies embedded migrations. It is a no-op when the database is disabled.
func (*Database) PutProposerPreference ¶
func (d *Database) PutProposerPreference(p ProposerPreference) error
PutProposerPreference upserts a proposer preference by slot and prunes the table to maxProposerPreferences rows. No-op when the database is disabled.
func (*Database) PutSetting ¶
func (d *Database) PutSetting(row SettingRow) error
PutSetting upserts the full 3-way state for a settings key. No-op when the database is disabled. The settings service owns the in-memory authority and always writes the complete row, so a plain INSERT OR REPLACE is correct.
func (*Database) PutValidatorRegistration ¶
func (d *Database) PutValidatorRegistration(reg ValidatorRegistration) error
PutValidatorRegistration upserts a validator registration by pubkey. No-op when the database is disabled.
type ProposerPreference ¶
type ProposerPreference struct {
Slot uint64 `db:"slot"`
ValidatorIndex uint64 `db:"validator_index"`
FeeRecipient string `db:"fee_recipient"`
TargetGasLimit uint64 `db:"target_gas_limit"`
Raw string `db:"raw"`
}
ProposerPreference is a persisted Gloas proposer preference (from gossip). raw holds the JSON-encoded SignedProposerPreferences for verbatim rehydration.
type SettingRow ¶
type SettingRow struct {
Key string `db:"key"`
CLIValue sql.NullString `db:"cli_value"`
CLISeq int64 `db:"cli_seq"`
UIValue sql.NullString `db:"ui_value"`
UISeq int64 `db:"ui_seq"`
UpdatedAt int64 `db:"updated_at"`
Actor string `db:"actor"`
}
SettingRow is the persisted 3-way state for a single settings key.
Resolution: the hardcoded default (in code) is the floor; cli_value and ui_value override it, and whichever has the higher seq wins. A seq of 0 means that layer is absent. cli_value tracks the last operator-supplied value (flag/env/config); a change to it is detected by value-diff on startup and bumps cli_seq so the CLI write "wins" until the UI sets a newer value.
type ValidatorRegistration ¶
type ValidatorRegistration struct {
Pubkey string `db:"pubkey"`
FeeRecipient string `db:"fee_recipient"`
GasLimit uint64 `db:"gas_limit"`
Timestamp int64 `db:"timestamp"`
Raw string `db:"raw"`
UpdatedAt int64 `db:"updated_at"`
}
ValidatorRegistration is a persisted Builder API validator registration (proposer fee-recipient preference). raw holds the JSON-encoded signed registration so the in-memory store can be rehydrated verbatim on restart.
type WonBlock ¶
type WonBlock struct {
ID int64 `db:"id" json:"-"`
Source string `db:"source" json:"source"`
Slot uint64 `db:"slot" json:"slot"`
BlockHash string `db:"block_hash" json:"block_hash"`
NumTransactions int `db:"num_transactions" json:"num_transactions"`
NumBlobs int `db:"num_blobs" json:"num_blobs"`
ValueWei string `db:"value_wei" json:"value_wei"`
ValueETH string `db:"value_eth" json:"value_eth"`
Timestamp int64 `db:"timestamp" json:"timestamp"`
}
WonBlock is a successfully delivered/included block, from either the Builder API or the ePBS reveal path.
Source Files