ledger

Documentation

Index

• type BlockHolder
• type HistoryQueryExecutor
• type KV
• type KeyModification
• type Ledger
• type OrdererLedger
• type OrdererLedgerProvider
• type PeerLedger
• type PeerLedgerProvider
• type PrunePolicy
• type QueryExecutor
• type QueryRecord
• type QueryResult
• type ResultsIterator
• type TxSimulator
• type ValidatedLedger

Types

type BlockHolder

type BlockHolder interface {
	GetBlock() *common.Block
	GetBlockBytes() []byte
}

BlockHolder holds block returned by the iterator in GetBlocksIterator. The sole purpose of this holder is to avoid desrialization if block is desired in raw bytes form (e.g., for transfer)

type HistoryQueryExecutor

type HistoryQueryExecutor interface {
	// GetHistoryForKey retrieves the history of values for a key.
	GetHistoryForKey(namespace string, key string) (ResultsIterator, error)
}

HistoryQueryExecutor executes the history queries

type KV

type KV struct {
	Key   string
	Value []byte
}

KV - QueryResult for KV-based datamodel. Holds a key and corresponding value. A nil value indicates a non-existent key.

type KeyModification

type KeyModification struct {
	TxID  string
	Value []byte
}

KeyModification - QueryResult for History.

type Ledger

type Ledger interface {
	// GetBlockchainInfo returns basic info about blockchain
	GetBlockchainInfo() (*pb.BlockchainInfo, error)
	// GetBlockByNumber returns block at a given height
	// blockNumber of  math.MaxUint64 will return last block
	GetBlockByNumber(blockNumber uint64) (*common.Block, error)
	// GetBlocksIterator returns an iterator that starts from `startBlockNumber`(inclusive).
	// The iterator is a blocking iterator i.e., it blocks till the next block gets available in the ledger
	// ResultsIterator contains type BlockHolder
	GetBlocksIterator(startBlockNumber uint64) (ResultsIterator, error)
	// Close closes the ledger
	Close()
	// Commit adds a new block
	Commit(block *common.Block) error
}

Ledger captures the methods that are common across the 'PeerLedger', 'OrdererLedger', and 'ValidatedLedger'

type OrdererLedger

type OrdererLedger interface {
	Ledger
}

OrdererLedger implements methods required by 'orderer ledger'

type OrdererLedgerProvider

type OrdererLedgerProvider interface {
	// Create creates a new ledger with a given unique id
	Create(ledgerID string) (OrdererLedger, error)
	// Open opens an already created ledger
	Open(ledgerID string) (OrdererLedger, error)
	// Exists tells whether the ledger with given id exits
	Exists(ledgerID string) (bool, error)
	// List lists the ids of the existing ledgers
	List() ([]string, error)
	// Close closes the ValidatedLedgerProvider
	Close()
}

OrdererLedgerProvider provides handle to raw ledger instances

type PeerLedger

type PeerLedger interface {
	Ledger
	// GetTransactionByID retrieves a transaction by id
	GetTransactionByID(txID string) (*common.Envelope, error)
	// GetBlockByHash returns a block given it's hash
	GetBlockByHash(blockHash []byte) (*common.Block, error)
	// NewTxSimulator gives handle to a transaction simulator.
	// A client can obtain more than one 'TxSimulator's for parallel execution.
	// Any snapshoting/synchronization should be performed at the implementation level if required
	NewTxSimulator() (TxSimulator, error)
	// NewQueryExecutor gives handle to a query executor.
	// A client can obtain more than one 'QueryExecutor's for parallel execution.
	// Any synchronization should be performed at the implementation level if required
	NewQueryExecutor() (QueryExecutor, error)
	// NewHistoryQueryExecutor gives handle to a history query executor.
	// A client can obtain more than one 'HistoryQueryExecutor's for parallel execution.
	// Any synchronization should be performed at the implementation level if required
	NewHistoryQueryExecutor() (HistoryQueryExecutor, error)
	//Prune prunes the blocks/transactions that satisfy the given policy
	Prune(policy PrunePolicy) error
}

PeerLedger differs from the OrdererLedger in that PeerLedger locally maintain a bitmask that tells apart valid transactions from invalid ones

type PeerLedgerProvider

type PeerLedgerProvider interface {
	// Create creates a new ledger with a given unique id
	Create(ledgerID string) (PeerLedger, error)
	// Open opens an already created ledger
	Open(ledgerID string) (PeerLedger, error)
	// Exists tells whether the ledger with given id exits
	Exists(ledgerID string) (bool, error)
	// List lists the ids of the existing ledgers
	List() ([]string, error)
	// Close closes the PeerLedgerProvider
	Close()
}

PeerLedgerProvider provides handle to ledger instances

type PrunePolicy

type PrunePolicy interface{}

PrunePolicy - a general interface for supporting different pruning policies

type QueryExecutor

type QueryExecutor interface {
	// GetState gets the value for given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
	GetState(namespace string, key string) ([]byte, error)
	// GetStateMultipleKeys gets the values for multiple keys in a single call
	GetStateMultipleKeys(namespace string, keys []string) ([][]byte, error)
	// GetStateRangeScanIterator returns an iterator that contains all the key-values between given key ranges.
	// startKey is included in the results and endKey is excluded. An empty startKey refers to the first available key
	// and an empty endKey refers to the last available key. For scanning all the keys, both the startKey and the endKey
	// can be supplied as empty strings. However, a full scan shuold be used judiciously for performance reasons.
	// The returned ResultsIterator contains results of type *KV
	GetStateRangeScanIterator(namespace string, startKey string, endKey string) (ResultsIterator, error)
	// ExecuteQuery executes the given query and returns an iterator that contains results of type specific to the underlying data store.
	// Only used for state databases that support query
	ExecuteQuery(query string) (ResultsIterator, error)
	// Done releases resources occupied by the QueryExecutor
	Done()
}

QueryExecutor executes the queries Get* methods are for supporting KV-based data model. ExecuteQuery method is for supporting a rich datamodel and query support

ExecuteQuery method in the case of a rich data model is expected to support queries on latest state, historical state and on the intersection of state and transactions

type QueryRecord

type QueryRecord struct {
	Namespace string
	Key       string
	Record    []byte
}

QueryRecord - Result structure for query records. Holds a namespace, key and record. Only used for state databases that support query

type QueryResult

type QueryResult interface{}

QueryResult - a general interface for supporting different types of query results. Actual types differ for different queries

type ResultsIterator

type ResultsIterator interface {
	// Next returns the next item in the result set. The `QueryResult` is expected to be nil when
	// the iterator gets exhausted
	Next() (QueryResult, error)
	// Close releases resources occupied by the iterator
	Close()
}

ResultsIterator - an iterator for query result set

type TxSimulator

type TxSimulator interface {
	QueryExecutor
	// SetState sets the given value for the given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
	SetState(namespace string, key string, value []byte) error
	// DeleteState deletes the given namespace and key
	DeleteState(namespace string, key string) error
	// SetMultipleKeys sets the values for multiple keys in a single call
	SetStateMultipleKeys(namespace string, kvs map[string][]byte) error
	// ExecuteUpdate for supporting rich data model (see comments on QueryExecutor above)
	ExecuteUpdate(query string) error
	// GetTxSimulationResults encapsulates the results of the transaction simulation.
	// This should contain enough detail for
	// - The update in the state that would be caused if the transaction is to be committed
	// - The environment in which the transaction is executed so as to be able to decide the validity of the enviroment
	//   (at a later time on a different peer) during committing the transactions
	// Different ledger implementation (or configurations of a single implementation) may want to represent the above two pieces
	// of information in different way in order to support different data-models or optimize the information representations.
	// TODO detailed illustration of a couple of representations.
	GetTxSimulationResults() ([]byte, error)
}

TxSimulator simulates a transaction on a consistent snapshot of the 'as recent state as possible' Set* methods are for supporting KV-based data model. ExecuteUpdate method is for supporting a rich datamodel and query support

type ValidatedLedger

type ValidatedLedger interface {
	Ledger
}

ValidatedLedger represents the 'final ledger' after filtering out invalid transactions from PeerLedger. Post-v1