blockchainstore

README

BlockchainStore

blockchainstore is a Go library for persisting and querying blockchain blocks in SQL databases (e.g., SQLite, MySQL, PostgreSQL). It provides a flexible and simple interface for managing block objects and block chains.

Features

• Database Agnostic SQL Store: Uses dracory/neat for SQL query generation across various database drivers.
• Auto Migration: Automatically creates and manages the block store database table schema.
• Rich Querying: Flexible block listing options including filtering by ID, limit, offset, sorting, and soft deletion.
• Clean Block Abstraction: Methods for reading and writing block header fields (PreviousHash, ThisHash, Data, Timestamp, etc.).

Installation

go get github.com/dracory/blockchainstore

Quick Start

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"

	"github.com/dracory/blockchainstore"
	_ "modernc.org/sqlite"
)

func main() {
	db, err := sql.Open("sqlite", ":memory:")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	store, err := blockchainstore.NewStore(blockchainstore.NewStoreOptions{
		BlockTableName:     "blocks_block",
		DB:                 db,
		AutomigrateEnabled: true,
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// Create a new block
	block := blockchainstore.NewBlock()
	block.SetData("Hello Blockchain")
	block.SetPreviousHash("0000000000000000000000000000000000000000000000000000000000000000")
	block.SetThisHash("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")

	if err := store.BlockCreate(ctx, block); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Block Created! ID: %s\n", block.ID())

	// Retrieve the block
	found, err := store.BlockFindByID(ctx, block.ID())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Retrieved Block Data: %s\n", found.Data())
}

Examples

Detailed, runnable examples complete with tests are provided in the examples directory:

• Basic Example (examples/basic/main.go): Demonstrates basic store initialization, creating blocks, and fetching blocks by ID. Includes test main_test.go.
• Advanced Example (examples/advanced/main.go): Demonstrates building a chain of SHA-256 linked blocks, querying blocks with pagination and sorting, updating blocks, and block deletion. Includes test main_test.go.

To run all examples and tests across the project:

go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• Constants
• type Block
  • func NewBlock() *Block
  • func NewBlockFromExistingData(data map[string]string) *Block
  • func NewBlockFromJSON(json string) *Block
  • func (o *Block) Data() string
  • func (o *Block) PreviousHash() string
  • func (o *Block) SetData(data string) *Block
  • func (o *Block) SetPreviousHash(previousHash string) *Block
  • func (o *Block) SetThisHash(thisHash string) *Block
  • func (o *Block) SetTimestamp(timestamp string) *Block
  • func (o *Block) ThisHash() string
  • func (o *Block) Timestamp() string
• type BlockQueryOptions
• type Blockchain
  • func NewBlockchain() *Blockchain
• type NewStoreOptions
• type Store
  • func NewStore(opts NewStoreOptions) (*Store, error)
  • func (store *Store) AutoMigrate() error
  • func (store *Store) BlockCreate(ctx context.Context, block *Block) error
  • func (store *Store) BlockDelete(ctx context.Context, block *Block) error
  • func (store *Store) BlockDeleteByID(ctx context.Context, id string) error
  • func (store *Store) BlockFindByID(ctx context.Context, id string) (*Block, error)
  • func (store *Store) BlockList(ctx context.Context, options BlockQueryOptions) ([]Block, error)
  • func (store *Store) BlockUpdate(ctx context.Context, block *Block) error
  • func (st *Store) EnableDebug(debug bool)
• type StoreInterface

Constants

const BLOCK_TABLE_NAME = "blocks_block"

Types

type Block

type Block struct {
	dataobject.DataObject
}

func NewBlock

func NewBlock() *Block

func NewBlockFromExistingData

func NewBlockFromExistingData(data map[string]string) *Block

func NewBlockFromJSON

func NewBlockFromJSON(json string) *Block

func (*Block) Data

func (o *Block) Data() string

func (*Block) PreviousHash

func (o *Block) PreviousHash() string

func (*Block) SetData

func (o *Block) SetData(data string) *Block

func (*Block) SetPreviousHash

func (o *Block) SetPreviousHash(previousHash string) *Block

func (*Block) SetThisHash

func (o *Block) SetThisHash(thisHash string) *Block

func (*Block) SetTimestamp

func (o *Block) SetTimestamp(timestamp string) *Block

func (*Block) ThisHash

func (o *Block) ThisHash() string

func (*Block) Timestamp

func (o *Block) Timestamp() string

Timestamp is the time when the block was created

Returns: - string: the time when the block was created

type BlockQueryOptions

type BlockQueryOptions struct {
	ID          string
	IDIn        []string
	Offset      int
	Limit       int
	SortOrder   string
	OrderBy     string
	CountOnly   bool
	WithDeleted bool
}

type Blockchain

type Blockchain struct {
	dataobject.DataObject
}

func NewBlockchain

func NewBlockchain() *Blockchain

type NewStoreOptions

type NewStoreOptions struct {
	BlockTableName     string
	DB                 *sql.DB
	DbDriverName       string
	TimeoutSeconds     int64
	AutomigrateEnabled bool
	DebugEnabled       bool
}

NewStoreOptions define the options for creating a new block store

type Store

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

func NewStore

func NewStore(opts NewStoreOptions) (*Store, error)

NewStore creates a new block store

func (*Store) AutoMigrate

func (store *Store) AutoMigrate() error

AutoMigrate auto migrate

func (*Store) BlockCreate

func (store *Store) BlockCreate(ctx context.Context, block *Block) error

func (*Store) BlockDelete

func (store *Store) BlockDelete(ctx context.Context, block *Block) error

func (*Store) BlockDeleteByID

func (store *Store) BlockDeleteByID(ctx context.Context, id string) error

func (*Store) BlockFindByID

func (store *Store) BlockFindByID(ctx context.Context, id string) (*Block, error)

func (*Store) BlockList

func (store *Store) BlockList(ctx context.Context, options BlockQueryOptions) ([]Block, error)

func (*Store) BlockUpdate

func (store *Store) BlockUpdate(ctx context.Context, block *Block) error

func (*Store) EnableDebug

func (st *Store) EnableDebug(debug bool)

EnableDebug - enables the debug option

type StoreInterface

type StoreInterface interface {
	BlockCreate(ctx context.Context, block *Block) error
	BlockDelete(ctx context.Context, block *Block) error
	BlockDeleteByID(ctx context.Context, blockID string) error
	BlockFindByID(ctx context.Context, id string) (*Block, error)
	BlockList(ctx context.Context, options BlockQueryOptions) ([]Block, error)
	BlockUpdate(ctx context.Context, block *Block) error
}