censusdb

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: AGPL-3.0 Imports: 20 Imported by: 2

Documentation

Index

Constants

View Source 
const (

	// CensusKeyMaxLen is the maximum length for census keys (20 bytes for Ethereum addresses)
	CensusKeyMaxLen = 20
)

Variables

View Source 
var (
	// ErrCensusNotFound is returned when a census is not found in the database.
	ErrCensusNotFound = fmt.Errorf("census not found in the local database")
	// ErrCensusAlreadyExists is returned by New() if the census already exists.
	ErrCensusAlreadyExists = fmt.Errorf("census already exists in the local database")
	// ErrWrongAuthenticationToken is returned when the authentication token is invalid.
	ErrWrongAuthenticationToken = fmt.Errorf("wrong authentication token")
	// ErrCensusIsLocked is returned if the census does not allow write operations.
	ErrCensusIsLocked = fmt.Errorf("census is locked")
	// ErrKeyNotFound is returned when a key is not found in the Merkle tree.
	ErrKeyNotFound = fmt.Errorf("key not found")
)

Functions

func VerifyProof 

func VerifyProof(key, value, root, siblings types.HexBytes, pathBits uint64) bool

VerifyProof verifies a Merkle proof for the given leaf key. Uses lean-imt verification with the configured hash function.

Types

type CensusDB 

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

CensusDB is a safe and persistent database of census trees. It maintains an in‑memory index mapping Merkle tree roots (in hexadecimal form) to census IDs.

func NewCensusDB 

func NewCensusDB(db db.Database) *CensusDB

NewCensusDB creates a new CensusDB object. It scans the persistent database for existing census references and builds the in‑memory index.

func (*CensusDB) CleanupWorkingCensus 

func (c *CensusDB) CleanupWorkingCensus(censusID uuid.UUID) error

CleanupWorkingCensus removes a working census from the database and memory. This is used to clean up temporary censuses after they have been converted to root-based ones.

func (*CensusDB) Del 

func (c *CensusDB) Del(censusID uuid.UUID) error

Del removes a census from the database and memory.

func (*CensusDB) Exists 

func (c *CensusDB) Exists(censusID uuid.UUID) bool

Exists returns true if the censusID exists in the local database.

func (*CensusDB) ExistsByAddress 

func (c *CensusDB) ExistsByAddress(address common.Address) bool

ExistsByAddress returns true if a census with the given Ethereum address exists in the local database.

func (*CensusDB) ExistsByRoot 

func (c *CensusDB) ExistsByRoot(root types.HexBytes) bool

ExistsByRoot returns true if a census with the given root exists in the local database.

func (*CensusDB) HashLen 

func (c *CensusDB) HashLen() int

HashLen returns the length of the hash function output in bytes.

func (*CensusDB) Import 

func (c *CensusDB) Import(root types.HexBytes, reader io.Reader) (*CensusRef, error)

Import imports a census from a JSON-encoded census dump read from an io.Reader. It creates a new census tree, populates it with the data from the dump, and creates a new CensusRef with the imported tree. It returns the CensusRef and any error encountered during the process, such as decoding errors or tree creation/import errors.

func (*CensusDB) ImportAll 

func (c *CensusDB) ImportAll(data []byte) (*CensusRef, error)

ImportAll imports a census from a JSON-encoded census dump. It decodes the dump, creates a new census tree, and populates it with the data from the dump. Then, it creates a new CensusRef with the imported tree and adds it to the database. It returns the CensusRef and any error encountered during the process, such as decoding errors or tree creation/import errors.

func (*CensusDB) ImportEvents 

func (c *CensusDB) ImportEvents(root types.HexBytes, events []census.CensusEvent) (*CensusRef, error)

ImportEvents imports a census from a list of census events. It creates a new census tree by the root provided, applies the events checking against the that root, and returns the CensusRef.

func (*CensusDB) ImportEventsByAddress 

func (c *CensusDB) ImportEventsByAddress(
	address common.Address,
	expectedRoot types.HexBytes,
	events []census.CensusEvent,
) (*CensusRef, error)

ImportEventsByAddress imports a census from a list of census events, identified by an Ethereum address. It creates a new census tree by the address provided, applies the events checking against the expected root, and returns the CensusRef.

func (*CensusDB) Load 

func (c *CensusDB) Load(censusID uuid.UUID) (*CensusRef, error)

Load returns a census from memory or from the persistent KV database.

func (*CensusDB) LoadByAddress 

func (c *CensusDB) LoadByAddress(address common.Address) (*CensusRef, error)

LoadByAddress loads a census by its Ethereum address from memory or from the persistent KV database.

func (*CensusDB) LoadByRoot 

func (c *CensusDB) LoadByRoot(root types.HexBytes) (*CensusRef, error)

LoadByRoot loads a census by its root from memory or from the persistent KV database.

func (*CensusDB) New 

func (c *CensusDB) New(censusID uuid.UUID) (*CensusRef, error)

New creates a new working census with a UUID identifier and adds it to the database. It returns ErrCensusAlreadyExists if a census with the given UUID is already present.

func (*CensusDB) NewByAddress 

func (c *CensusDB) NewByAddress(address common.Address) (*CensusRef, error)

NewByAddress creates a new census identified by an Ethereum address. It returns ErrCensusAlreadyExists if a census with the given address is already present.

func (*CensusDB) NewByRoot 

func (c *CensusDB) NewByRoot(root types.HexBytes) (*CensusRef, error)

NewByRoot creates a new census identified by its root. It returns ErrCensusAlreadyExists if a census with the given root is already present.

func (*CensusDB) ProofByRoot 

func (c *CensusDB) ProofByRoot(root, leafKey types.HexBytes) (*types.CensusProof, error)

ProofByRoot generates a Merkle proof for the given leafKey in a census identified by its root.

func (*CensusDB) PublishCensus 

func (c *CensusDB) PublishCensus(originCensusID uuid.UUID, destinationRef *CensusRef) error

PublishCensus publishes a working census to a root-based census by moving the Pebble directory.

func (*CensusDB) PurgeWorkingCensuses 

func (c *CensusDB) PurgeWorkingCensuses(maxAge time.Duration) (int, error)

PurgeWorkingCensuses removes all working censuses older than the specified duration.

func (*CensusDB) SizeByRoot 

func (c *CensusDB) SizeByRoot(root types.HexBytes) (int, error)

SizeByRoot returns the number of leaves in the Merkle tree with the given root.

func (*CensusDB) TrunkKey 

func (c *CensusDB) TrunkKey(key types.HexBytes) types.HexBytes

TrunkKey computes the hash of a key and truncates it to the required length. For leanimt census, we use the address directly (20 bytes for Ethereum addresses).

func (*CensusDB) VerifyProof 

func (c *CensusDB) VerifyProof(proof *types.CensusProof) bool

VerifyProof checks the validity of a Merkle proof.

type CensusRef 

type CensusRef struct {
	ID       uuid.UUID
	HashType string
	LastUsed time.Time
	// contains filtered or unexported fields
}

CensusRef is a reference to a census. It holds the Merkle tree. All accesses to the underlying tree (and its currentRoot) are protected by treeMu.

func (*CensusRef) ApplyEvents 

func (cr *CensusRef) ApplyEvents(events []census.CensusEvent) error

ApplyEvents safely applies a list of census events to the Merkle tree.

func (*CensusRef) FetchKeysAndValues 

func (cr *CensusRef) FetchKeysAndValues() ([]types.HexBytes, []*types.BigInt, error)

FetchKeysAndValues fetches all keys and values from the Merkle tree. Returns the keys as byte arrays (20-byte addresses) and the values as BigInts (weights). Note: This is a placeholder implementation. The lean-imt census package doesn't expose a direct iteration API, so this would need to be implemented if required.

func (*CensusRef) GenProof 

func (cr *CensusRef) GenProof(key types.HexBytes) (*types.CensusProof, error)

GenProof safely generates a Merkle proof for the given leaf key. It returns the proof components (key, value, siblings, index) and an inclusion boolean. For lean-imt, key must be a 20-byte Ethereum address.

func (*CensusRef) Insert 

func (cr *CensusRef) Insert(key, value types.HexBytes) error

Insert safely inserts a key/value pair into the Merkle tree. It holds treeMu during the Add and Root calls. Key must be exactly 20 bytes (Ethereum address).

func (*CensusRef) InsertBatch 

func (cr *CensusRef) InsertBatch(keys, values []types.HexBytes) ([]any, error)

InsertBatch safely inserts a batch of key/value pairs into the Merkle tree.

func (*CensusRef) Root 

func (cr *CensusRef) Root() types.HexBytes

Root safely returns the current Merkle tree root.

func (*CensusRef) SetTree 

func (cr *CensusRef) SetTree(tree *census.CensusIMT)

SetTree sets the census.CensusIMT pointer.

func (*CensusRef) Size 

func (cr *CensusRef) Size() int

Size safely returns the number of leaves in the Merkle tree.

func (*CensusRef) Tree 

func (cr *CensusRef) Tree() *census.CensusIMT

Tree returns the underlying census.CensusIMT pointer. (Not concurrency‑safe; use Insert, Root, or GenProof.)

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.