ledger

README

Ledger Package

This package implements the ledger, which includes the blockchain and global state.

If you're looking for API to work with the blockchain or state, look in ledger.go. This is the file where all public functions are exposed and is extensively documented. The sections in the file are:

Transaction-batch functions

These are functions that consensus should call. BeginTxBatch followed by CommitTxBatch or RollbackTxBatch. These functions will add a block to the blockchain with the specified transactions.

World-state functions

These functions are used to modify the global state. They would generally be called by the VM based on requests from chaincode.

Blockchain functions

These functions can be used to retrieve blocks/transactions from the blockchain or other information such as the blockchain size. Addition of blocks to the blockchain is done though the transaction-batch related functions.

Documentation

Index

• Constants
• Variables
• type Error
  • func (ledgerError *Error) Error() string
  • func (ledgerError *Error) Type() ErrorType
• type ErrorType
• type Ledger
  • func GetLedger() (*Ledger, error)
  • func GetNewLedger() (*Ledger, error)
  • func InitTestLedger(t *testing.T) *Ledger
  • func (ledger *Ledger) ApplyStateDelta(id interface{}, delta *statemgmt.StateDelta) error
  • func (ledger *Ledger) BeginTxBatch(id interface{}) error
  • func (ledger *Ledger) CommitStateDelta(id interface{}) error
  • func (ledger *Ledger) CommitTxBatch(id interface{}, transactions []*protos.Transaction, ...) error
  • func (ledger *Ledger) CopyState(sourceChaincodeID string, destChaincodeID string) error
  • func (ledger *Ledger) DeleteALLStateKeysAndValues() error
  • func (ledger *Ledger) DeleteState(chaincodeID string, key string) error
  • func (ledger *Ledger) GetBlockByNumber(blockNumber uint64) (*protos.Block, error)
  • func (ledger *Ledger) GetBlockchainInfo() (*protos.BlockchainInfo, error)
  • func (ledger *Ledger) GetBlockchainSize() uint64
  • func (ledger *Ledger) GetState(chaincodeID string, key string, committed bool) ([]byte, error)
  • func (ledger *Ledger) GetStateDelta(blockNumber uint64) (*statemgmt.StateDelta, error)
  • func (ledger *Ledger) GetStateMultipleKeys(chaincodeID string, keys []string, committed bool) ([][]byte, error)
  • func (ledger *Ledger) GetStateRangeScanIterator(chaincodeID string, startKey string, endKey string, committed bool) (statemgmt.RangeScanIterator, error)
  • func (ledger *Ledger) GetStateSnapshot() (*state.StateSnapshot, error)
  • func (ledger *Ledger) GetTXBatchPreviewBlockInfo(id interface{}, transactions []*protos.Transaction, metadata []byte) (*protos.BlockchainInfo, error)
  • func (ledger *Ledger) GetTempStateHash() ([]byte, error)
  • func (ledger *Ledger) GetTempStateHashWithTxDeltaStateHashes() ([]byte, map[string][]byte, error)
  • func (ledger *Ledger) GetTransactionByID(txID string) (*protos.Transaction, error)
  • func (ledger *Ledger) PutRawBlock(block *protos.Block, blockNumber uint64) error
  • func (ledger *Ledger) RollbackStateDelta(id interface{}) error
  • func (ledger *Ledger) RollbackTxBatch(id interface{}) error
  • func (ledger *Ledger) SetState(chaincodeID string, key string, value []byte) error
  • func (ledger *Ledger) SetStateMultipleKeys(chaincodeID string, kvs map[string][]byte) error
  • func (ledger *Ledger) TxBegin(txID string)
  • func (ledger *Ledger) TxFinished(txID string, txSuccessful bool)
  • func (ledger *Ledger) VerifyChain(highBlock, lowBlock uint64) (uint64, error)

Constants

const (
	//ErrorTypeInvalidArgument used to indicate the invalid input to ledger method
	ErrorTypeInvalidArgument = ErrorType("InvalidArgument")
	//ErrorTypeOutOfBounds used to indicate that a request is out of bounds
	ErrorTypeOutOfBounds = ErrorType("OutOfBounds")
	//ErrorTypeResourceNotFound used to indicate if a resource is not found
	ErrorTypeResourceNotFound = ErrorType("ResourceNotFound")
	//ErrorTypeBlockNotFound used to indicate if a block is not found when looked up by it's hash
	ErrorTypeBlockNotFound = ErrorType("ErrorTypeBlockNotFound")
)

Variables

var (
	// ErrOutOfBounds is returned if a request is out of bounds
	ErrOutOfBounds = newLedgerError(ErrorTypeOutOfBounds, "ledger: out of bounds")

	// ErrResourceNotFound is returned if a resource is not found
	ErrResourceNotFound = newLedgerError(ErrorTypeResourceNotFound, "ledger: resource not found")
)

Types

type Error

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

Error can be used for throwing an error from ledger code.

func (*Error) Error

func (ledgerError *Error) Error() string

func (*Error) Type

func (ledgerError *Error) Type() ErrorType

Type returns the type of the error

type ErrorType

type ErrorType string

ErrorType represents the type of a ledger error

type Ledger

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

Ledger - the struct for openchain ledger

func GetLedger

func GetLedger() (*Ledger, error)

GetLedger - gives a reference to a 'singleton' ledger

func GetNewLedger

func GetNewLedger() (*Ledger, error)

GetNewLedger - gives a reference to a new ledger TODO need better approach

func InitTestLedger

func InitTestLedger(t *testing.T) *Ledger

InitTestLedger provides a ledger for testing. This method creates a fresh db and constructs a ledger instance on that.

func (*Ledger) ApplyStateDelta

func (ledger *Ledger) ApplyStateDelta(id interface{}, delta *statemgmt.StateDelta) error

ApplyStateDelta applies a state delta to the current state. This is an in memory change only. You must call ledger.CommitStateDelta to persist the change to the DB. This should only be used as part of state synchronization. State deltas can be retrieved from another peer though the Ledger.GetStateDelta function or by creating state deltas with keys retrieved from Ledger.GetStateSnapshot(). For an example, see TestSetRawState in ledger_test.go Note that there is no order checking in this function and it is up to the caller to ensure that deltas are applied in the correct order. For example, if you are currently at block 8 and call this function with a delta retrieved from Ledger.GetStateDelta(10), you would now be in a bad state because you did not apply the delta for block 9. It's possible to roll the state forwards or backwards using stateDelta.RollBackwards. By default, a delta retrieved for block 3 can be used to roll forwards from state at block 2 to state at block 3. If stateDelta.RollBackwards=false, the delta retrieved for block 3 can be used to roll backwards from the state at block 3 to the state at block 2.

func (*Ledger) BeginTxBatch

func (ledger *Ledger) BeginTxBatch(id interface{}) error

BeginTxBatch - gets invoked when next round of transaction-batch execution begins

func (*Ledger) CommitStateDelta

func (ledger *Ledger) CommitStateDelta(id interface{}) error

CommitStateDelta will commit the state delta passed to ledger.ApplyStateDelta to the DB

func (*Ledger) CommitTxBatch

func (ledger *Ledger) CommitTxBatch(id interface{}, transactions []*protos.Transaction, transactionResults []*protos.TransactionResult, metadata []byte) error

CommitTxBatch - gets invoked when the current transaction-batch needs to be committed This function returns successfully iff the transactions details and state changes (that may have happened during execution of this transaction-batch) have been committed to permanent storage

func (*Ledger) CopyState

func (ledger *Ledger) CopyState(sourceChaincodeID string, destChaincodeID string) error

CopyState copies all the key-values from sourceChaincodeID to destChaincodeID

func (*Ledger) DeleteALLStateKeysAndValues

func (ledger *Ledger) DeleteALLStateKeysAndValues() error

DeleteALLStateKeysAndValues deletes all keys and values from the state. This is generally only used during state synchronization when creating a new state from a snapshot.

func (*Ledger) DeleteState

func (ledger *Ledger) DeleteState(chaincodeID string, key string) error

DeleteState tracks the deletion of state for chaincodeID and key. Does not immediately writes to DB

func (*Ledger) GetBlockByNumber

func (ledger *Ledger) GetBlockByNumber(blockNumber uint64) (*protos.Block, error)

GetBlockByNumber return block given the number of the block on blockchain. Lowest block on chain is block number zero

func (*Ledger) GetBlockchainInfo

func (ledger *Ledger) GetBlockchainInfo() (*protos.BlockchainInfo, error)

GetBlockchainInfo returns information about the blockchain ledger such as height, current block hash, and previous block hash.

func (*Ledger) GetBlockchainSize

func (ledger *Ledger) GetBlockchainSize() uint64

GetBlockchainSize returns number of blocks in blockchain

func (*Ledger) GetState

func (ledger *Ledger) GetState(chaincodeID string, key string, committed bool) ([]byte, error)

GetState get state for chaincodeID and key. If committed is false, this first looks in memory and if missing, pulls from db. If committed is true, this pulls from the db only.

func (*Ledger) GetStateDelta

func (ledger *Ledger) GetStateDelta(blockNumber uint64) (*statemgmt.StateDelta, error)

GetStateDelta will return the state delta for the specified block if available. If not available because it has been discarded, returns nil,nil.

func (*Ledger) GetStateMultipleKeys

func (ledger *Ledger) GetStateMultipleKeys(chaincodeID string, keys []string, committed bool) ([][]byte, error)

GetStateMultipleKeys returns the values for the multiple keys. This method is mainly to amortize the cost of grpc communication between chaincode shim peer

func (*Ledger) GetStateRangeScanIterator

func (ledger *Ledger) GetStateRangeScanIterator(chaincodeID string, startKey string, endKey string, committed bool) (statemgmt.RangeScanIterator, error)

GetStateRangeScanIterator returns an iterator to get all the keys (and values) between startKey and endKey (assuming lexical order of the keys) for a chaincodeID. If committed is true, the key-values are retrieved only from the db. If committed is false, the results from db are mergerd with the results in memory (giving preference to in-memory data) The key-values in the returned iterator are not guaranteed to be in any specific order

func (*Ledger) GetStateSnapshot

func (ledger *Ledger) GetStateSnapshot() (*state.StateSnapshot, error)

GetStateSnapshot returns a point-in-time view of the global state for the current block. This should be used when transferring the state from one peer to another peer. You must call stateSnapshot.Release() once you are done with the snapshot to free up resources.

func (*Ledger) GetTXBatchPreviewBlockInfo

func (ledger *Ledger) GetTXBatchPreviewBlockInfo(id interface{},
	transactions []*protos.Transaction, metadata []byte) (*protos.BlockchainInfo, error)

GetTXBatchPreviewBlockInfo returns a preview block info that will contain the same information as GetBlockchainInfo will return after ledger.CommitTxBatch is called with the same parameters. If the state is modified by a transaction between these two calls, the contained hash will be different.

func (*Ledger) GetTempStateHash

func (ledger *Ledger) GetTempStateHash() ([]byte, error)

GetTempStateHash - Computes state hash by taking into account the state changes that may have taken place during the execution of current transaction-batch

func (*Ledger) GetTempStateHashWithTxDeltaStateHashes

func (ledger *Ledger) GetTempStateHashWithTxDeltaStateHashes() ([]byte, map[string][]byte, error)

GetTempStateHashWithTxDeltaStateHashes - In addition to the state hash (as defined in method GetTempStateHash), this method returns a map [txUuid of Tx --> cryptoHash(stateChangesMadeByTx)] Only successful txs appear in this map

func (*Ledger) GetTransactionByID

func (ledger *Ledger) GetTransactionByID(txID string) (*protos.Transaction, error)

GetTransactionByID return transaction by it's txId

func (*Ledger) PutRawBlock

func (ledger *Ledger) PutRawBlock(block *protos.Block, blockNumber uint64) error

PutRawBlock puts a raw block on the chain. This function should only be used for synchronization between peers.

func (*Ledger) RollbackStateDelta

func (ledger *Ledger) RollbackStateDelta(id interface{}) error

RollbackStateDelta will discard the state delta passed to ledger.ApplyStateDelta

func (*Ledger) RollbackTxBatch

func (ledger *Ledger) RollbackTxBatch(id interface{}) error

RollbackTxBatch - Discards all the state changes that may have taken place during the execution of current transaction-batch

func (*Ledger) SetState

func (ledger *Ledger) SetState(chaincodeID string, key string, value []byte) error

SetState sets state to given value for chaincodeID and key. Does not immideatly writes to DB

func (*Ledger) SetStateMultipleKeys

func (ledger *Ledger) SetStateMultipleKeys(chaincodeID string, kvs map[string][]byte) error

SetStateMultipleKeys sets the values for the multiple keys. This method is mainly to amortize the cost of grpc communication between chaincode shim peer

func (*Ledger) TxBegin

func (ledger *Ledger) TxBegin(txID string)

TxBegin - Marks the begin of a new transaction in the ongoing batch

func (*Ledger) TxFinished

func (ledger *Ledger) TxFinished(txID string, txSuccessful bool)

TxFinished - Marks the finish of the on-going transaction. If txSuccessful is false, the state changes made by the transaction are discarded

func (*Ledger) VerifyChain

func (ledger *Ledger) VerifyChain(highBlock, lowBlock uint64) (uint64, error)

VerifyChain will verify the integrity of the blockchain. This is accomplished by ensuring that the previous block hash stored in each block matches the actual hash of the previous block in the chain. The return value is the block number of lowest block in the range which can be verified as valid. The first block is assumed to be valid, and an error is only returned if the first block does not exist, or some other sort of irrecoverable ledger error such as the first block failing to hash is encountered. For example, if VerifyChain(0, 99) is called and previous hash values stored in blocks 8, 32, and 42 do not match the actual hashes of respective previous block 42 would be the return value from this function. highBlock is the high block in the chain to include in verification. If you wish to verify the entire chain, use ledger.GetBlockchainSize() - 1. lowBlock is the low block in the chain to include in verification. If you wish to verify the entire chain, use 0 for the genesis block.