ledger

README

Ledger Package

This package implements the ledger for Openchain 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

• Variables
• type Ledger
  • func GetLedger() (*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) 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) GetStateRangeScanIterator(chaincodeID string, startKey string, endKey string, committed bool) (statemgmt.RangeScanIterator, error)
  • func (ledger *Ledger) GetStateSnapshot() (*state.StateSnapshot, error)
  • func (ledger *Ledger) GetTXBatchPreviewBlock(id interface{}, transactions []*protos.Transaction, metadata []byte) (*protos.Block, error)
  • func (ledger *Ledger) GetTempStateHash() ([]byte, error)
  • func (ledger *Ledger) GetTempStateHashWithTxDeltaStateHashes() ([]byte, map[string][]byte, error)
  • func (ledger *Ledger) GetTransactionByUUID(txUUID 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) TxBegin(txUUID string)
  • func (ledger *Ledger) TxFinished(txUUID string, txSuccessful bool)
  • func (ledger *Ledger) VerifyChain(highBlock, lowBlock uint64) (uint64, error)

Variables

var (
	// ErrOutOfBounds is returned if a request is out of bounds
	ErrOutOfBounds = errors.New("ledger: out of bounds")

	// ErrResourceNotFound is returned if a resource is not found
	ErrResourceNotFound = errors.New("ledger: resource not found")
)

Types

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 InitTestLedger

func InitTestLedger(t *testing.T) *Ledger

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 retrived 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) 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 immideatly 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.

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 retrived 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 transfering the state from one peer to another peer. You must call stateSnapshot.Release() once you are done with the snapsnot to free up resources.

func (*Ledger) GetTXBatchPreviewBlock

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

GetTXBatchPreviewBlock returns a preview block that will have the same block.GetHash() result as the block commited to the database if ledger.CommitTxBatch is called with the same parameters. If the state is modified by a transaction between these two calls, the hash will be different. The preview block does not include non-hashed data such as the local timestamp.

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) GetTransactionByUUID

func (ledger *Ledger) GetTransactionByUUID(txUUID string) (*protos.Transaction, error)

GetTransactionByUUID return transaction by it's uuid

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 - Descards 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) TxBegin

func (ledger *Ledger) TxBegin(txUUID string)

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

func (*Ledger) TxFinished

func (ledger *Ledger) TxFinished(txUUID 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 integrety 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 the block that contains the non-matching previous block hash. For example, if VerifyChain(0, 99) is called and prevous 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 verofication. 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.