ledger

Documentation

Overview

Package ledger enables ledger queries on specified channel on a Fabric network. An application that requires ledger queries from multiple channels should create a separate instance of the ledger client for each channel. Ledger client supports the following queries: QueryInfo, QueryBlock, QueryBlockByHash, QueryBlockByTxID, QueryTransaction and QueryConfig.

Basic Flow:
1) Prepare channel context
2) Create ledger client
3) Query ledger

Example

ctx := mockChannelProvider("mychannel")

c, err := New(ctx)
if err != nil {
	fmt.Println("failed to create client")
}

block, err := c.QueryBlock(1)
if err != nil {
	fmt.Printf("failed to query block: %s\n", err)
}

if block != nil {
	fmt.Println("Retrieved block #1")
}

Output:

Retrieved block #1

Index

• type Client
  • func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error)
  • func (c *Client) QueryBlock(blockNumber uint64, options ...RequestOption) (*common.Block, error)
  • func (c *Client) QueryBlockByHash(blockHash []byte, options ...RequestOption) (*common.Block, error)
  • func (c *Client) QueryBlockByTxID(txID fab.TransactionID, options ...RequestOption) (*common.Block, error)
  • func (c *Client) QueryConfig(options ...RequestOption) (fab.ChannelCfg, error)
  • func (c *Client) QueryInfo(options ...RequestOption) (*fab.BlockchainInfoResponse, error)
  • func (c *Client) QueryTransaction(transactionID fab.TransactionID, options ...RequestOption) (*pb.ProcessedTransaction, error)
• type ClientOption
  • func WithDefaultTargetFilter(filter fab.TargetFilter) ClientOption
• type RequestOption
  • func WithMaxTargets(maxTargets int) RequestOption
  • func WithMinTargets(minTargets int) RequestOption
  • func WithParentContext(parentContext reqContext.Context) RequestOption
  • func WithTargetEndpoints(keys ...string) RequestOption
  • func WithTargetFilter(targetFilter fab.TargetFilter) RequestOption
  • func WithTargets(targets ...fab.Peer) RequestOption
  • func WithTimeout(timeoutType fab.TimeoutType, timeout time.Duration) RequestOption

Examples

• Package
• Client.QueryBlock
• Client.QueryBlockByHash
• Client.QueryBlockByTxID
• Client.QueryConfig
• Client.QueryInfo
• Client.QueryTransaction
• New
• WithDefaultTargetFilter
• WithParentContext
• WithTargetFilter
• WithTargets

Types

type Client

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

Client enables ledger queries on a Fabric network.

func New

func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error)

New returns a ledger client instance. A ledger client instance provides a handler to query various info on specified channel. An application that requires interaction with multiple channels should create a separate instance of the ledger client for each channel. Ledger client supports specific queries only.

Example

ctx := mockChannelProvider("mychannel")

c, err := New(ctx)
if err != nil {
	fmt.Println(err)
}

if c != nil {
	fmt.Println("ledger client created")
}

Output:

ledger client created

func (*Client) QueryBlock

func (c *Client) QueryBlock(blockNumber uint64, options ...RequestOption) (*common.Block, error)

QueryBlock queries the ledger for Block by block number.

Parameters:
blockNumber is required block number(ID)
options hold optional request options

Returns:
block information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

block, err := c.QueryBlock(1)
if err != nil {
	fmt.Printf("failed to query block: %s\n", err)
}

if block != nil {
	fmt.Println("Retrieved block #1")
}

Output:

Retrieved block #1

func (*Client) QueryBlockByHash

func (c *Client) QueryBlockByHash(blockHash []byte, options ...RequestOption) (*common.Block, error)

QueryBlockByHash queries the ledger for block by block hash.

Parameters:
blockHash is required block hash
options hold optional request options

Returns:
block information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

block, err := c.QueryBlockByHash([]byte("hash"))
if err != nil {
	fmt.Printf("failed to query block by hash: %s\n", err)
}

if block != nil {
	fmt.Println("Retrieved block by hash")
}

Output:

Retrieved block by hash

func (*Client) QueryBlockByTxID

func (c *Client) QueryBlockByTxID(txID fab.TransactionID, options ...RequestOption) (*common.Block, error)

QueryBlockByTxID queries for block which contains a transaction.

Parameters:
txID is required transaction ID
options hold optional request options

Returns:
block information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

block, err := c.QueryBlockByTxID("123")
if err != nil {
	fmt.Printf("failed to query block by transaction ID: %s\n", err)
}

if block != nil {
	fmt.Println("Retrieved block by transaction ID")
}

Output:

Retrieved block by transaction ID

func (*Client) QueryConfig

func (c *Client) QueryConfig(options ...RequestOption) (fab.ChannelCfg, error)

QueryConfig queries for channel configuration.

Parameters:
options hold optional request options

Returns:
channel configuration information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

cfg, err := c.QueryConfig(WithTargets(mockPeerWithConfigBlock()))
if err != nil {
	fmt.Printf("failed to query config: %s\n", err)
}

if cfg != nil {
	fmt.Println("Retrieved channel configuration")
}

Output:

Retrieved channel configuration

func (*Client) QueryInfo

func (c *Client) QueryInfo(options ...RequestOption) (*fab.BlockchainInfoResponse, error)

QueryInfo queries for various useful blockchain information on this channel such as block height and current block hash.

Parameters:
options are optional request options

Returns:
blockchain information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

bci, err := c.QueryInfo()
if err != nil {
	fmt.Printf("failed to query for blockchain info: %s\n", err)
}

if bci != nil {
	fmt.Println("Retrieved ledger info")
}

Output:

Retrieved ledger info

func (*Client) QueryTransaction

func (c *Client) QueryTransaction(transactionID fab.TransactionID, options ...RequestOption) (*pb.ProcessedTransaction, error)

QueryTransaction queries the ledger for processed transaction by transaction ID.

Parameters:
txID is required transaction ID
options hold optional request options

Returns:
processed transaction information

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

t, err := c.QueryTransaction("123")
if err != nil {
	fmt.Printf("failed to query transaction: %s\n", err)
}

if t != nil {
	fmt.Println("Retrieved transaction")
}

Output:

Retrieved transaction

type ClientOption

type ClientOption func(*Client) error

ClientOption describes a functional parameter for the New constructor

func WithDefaultTargetFilter

func WithDefaultTargetFilter(filter fab.TargetFilter) ClientOption

WithDefaultTargetFilter option to configure new

Example

ctx := mockChannelProvider("mychannel")

c, err := New(ctx, WithDefaultTargetFilter(&urlTargetFilter{url: "example.com"}))
if err != nil {
	fmt.Println(err)
}

if c != nil {
	fmt.Println("ledger client created with url target filter")
}

Output:

ledger client created with url target filter

type RequestOption

type RequestOption func(ctx context.Client, opts *requestOptions) error

RequestOption func for each requestOptions argument

func WithMaxTargets

func WithMaxTargets(maxTargets int) RequestOption

WithMaxTargets specifies maximum number of targets to select per request. Default value for maximum number of targets is 1.

func WithMinTargets

func WithMinTargets(minTargets int) RequestOption

WithMinTargets specifies minimum number of targets that have to respond with no error (or agree on result). Default value for minimum number of targets is 1.

func WithParentContext

func WithParentContext(parentContext reqContext.Context) RequestOption

WithParentContext encapsulates grpc parent context

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println(err)
}

channelContext, err := mockChannelProvider("mychannel")()
if err != nil {
	fmt.Println("failed to return channel context")
	return
}

// get parent context and cancel
parentContext, cancel := sdkCtx.NewRequest(channelContext, sdkCtx.WithTimeout(20*time.Second))
defer cancel()

bci, err := c.QueryInfo(WithParentContext(parentContext))
if err != nil {
	fmt.Printf("failed to query for blockchain info: %s\n", err)
}

if bci != nil {
	fmt.Println("Retrieved blockchain info")
}

Output:

Retrieved blockchain info

func WithTargetEndpoints

func WithTargetEndpoints(keys ...string) RequestOption

WithTargetEndpoints allows overriding of the target peers per request. Targets are specified by name or URL, and the SDK will create the underlying peer objects.

func WithTargetFilter

func WithTargetFilter(targetFilter fab.TargetFilter) RequestOption

WithTargetFilter specifies a per-request target peer-filter.

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println(err)
}

block, err := c.QueryBlock(1, WithTargetFilter(&urlTargetFilter{url: "example.com"}))
if err != nil {
	fmt.Printf("failed to query block: %s\n", err)
}

if block != nil {
	fmt.Println("Retrieved block #1 from example.com")
}

Output:

Retrieved block #1 from example.com

func WithTargets

func WithTargets(targets ...fab.Peer) RequestOption

WithTargets allows for overriding of the target peers per request.

Example

c, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

cfg, err := c.QueryConfig(WithTargets(mockPeerWithConfigBlock()))
if err != nil {
	fmt.Printf("failed to query config with target peer: %s\n", err)
}

if cfg != nil {
	fmt.Println("Retrieved config from target peer")
}

Output:

Retrieved config from target peer

func WithTimeout

func WithTimeout(timeoutType fab.TimeoutType, timeout time.Duration) RequestOption

WithTimeout encapsulates key value pairs of timeout type, timeout duration to Options for QueryInfo, QueryBlock, QueryBlockByHash, QueryBlockByTxID, QueryTransaction, QueryConfig functions