gateway

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2021 License: Apache-2.0 Imports: 24 Imported by: 72

Documentation

Overview

Package gateway enables Go developers to build client applications using the Hyperledger Fabric programming model as described in the 'Developing Applications' chapter of the Fabric documentation: https://hyperledger-fabric.readthedocs.io/en/latest/developapps/developing_applications.html

A Gateway object is created using the Connect() function to connect to a 'gateway' peer as specified in a network configuration file, using an identity stored in a wallet. Interactions with smart contracts are then invoked within the context of this gateway connection.

See https://github.com/hyperledger/fabric-samples/blob/master/fabcar/go/fabcar.go for a working sample.

Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	os.Exit(1)
}

// Path to the network config (CCP) file
ccpPath := filepath.Join(
	"..",
	"connection-org1.yaml",
)

// Connect to the gateway peer(s) using the network config and identity in the wallet
gw, err := Connect(
	WithConfig(config.FromFile(filepath.Clean(ccpPath))),
	WithIdentity(wallet, "appUser"),
)
if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

// Get the network channel 'mychannel'
network, err := gw.GetNetwork("mychannel")
if err != nil {
	fmt.Printf("Failed to get network: %s\n", err)
	os.Exit(1)
}

// Get the smart contract 'fabcar'
contract := network.GetContract("fabcar")

// Submit a transaction in that contract to the ledger
result, err := contract.SubmitTransaction("createCar", "CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	os.Exit(1)
}
fmt.Println(string(result))

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConfigOption 

type ConfigOption = func(*Gateway) error

ConfigOption specifies the gateway configuration source.

func WithConfig 

func WithConfig(config core.ConfigProvider) ConfigOption

WithConfig configures the gateway from a network config, such as a ccp file. 

Parameters:
config is a ConfigProvider function which provides config backend

Returns:
A ConfigOption which can be passed as the first parameter to the Connect() function
Example 
// Path to the network config (CCP) file
ccpPath := filepath.Join(
	"..",
	"connection-org1.yaml",
)

// Connect to the gateway peer(s) using the network config
gw, err := Connect(
	WithConfig(config.FromFile(filepath.Clean(ccpPath))),
	WithUser("admin"),
)
if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

Output:

func WithSDK 

func WithSDK(sdk *fabsdk.FabricSDK) ConfigOption

WithSDK configures the gateway with the configuration from an existing FabricSDK instance 

Parameters:
sdk is an instance of fabsdk.FabricSDK from which the configuration is extracted

Returns:
A ConfigOption which can be passed as the first parameter to the Connect() function
Example 
sdk, err := fabsdk.New(config.FromFile("testdata/connection-tls.json"))
if err != nil {
	fmt.Printf("Failed to create SDK: %s", err)
}

gw, err := Connect(
	WithSDK(sdk),
	WithUser("user1"),
)
if err != nil {
	fmt.Printf("Failed to create gateway: %s", err)
}
defer gw.Close()

Output:

type Contract 

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

A Contract object represents a smart contract instance in a network. Applications should get a Contract instance from a Network using the GetContract method

func (*Contract) CreateTransaction 

func (c *Contract) CreateTransaction(name string, opts ...TransactionOption) (*Transaction, error)

CreateTransaction creates an object representing a specific invocation of a transaction function implemented by this contract, and provides more control over the transaction invocation using the optional arguments. A new transaction object must be created for each transaction invocation. 

Parameters:
name is the name of the transaction function to be invoked in the smart contract.
opts are the options to be associated with the transaction.

Returns:
A Transaction object for subsequent evaluation or submission.
Example 
contract := myContract()

txn, err := contract.CreateTransaction("createCar")
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

result, err := txn.Submit("CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

func (*Contract) EvaluateTransaction 

func (c *Contract) EvaluateTransaction(name string, args ...string) ([]byte, error)

EvaluateTransaction will evaluate a transaction function and return its results. The transaction function 'name' will be evaluated on the endorsing peers but the responses will not be sent to the ordering service and hence will not be committed to the ledger. This can be used for querying the world state. 

Parameters:
name is the name of the transaction function to be invoked in the smart contract.
args are the arguments to be sent to the transaction function.

Returns:
The return value of the transaction function in the smart contract.
Example 
contract := myContract()

result, err := contract.EvaluateTransaction("queryCar", "CAR01")
if err != nil {
	fmt.Printf("Failed to evaluate transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

func (*Contract) Name 

func (c *Contract) Name() string

Name returns the name of the smart contract

func (*Contract) RegisterEvent 

func (c *Contract) RegisterEvent(eventFilter string) (fab.Registration, <-chan *fab.CCEvent, error)

RegisterEvent registers for chaincode events. Unregister must be called when the registration is no longer needed. 

Parameters:
eventFilter is the chaincode event filter (regular expression) for which events are to be received

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.
Example 
contract := myContract()

eventID := "test([a-zA-Z]+)"

reg, notifier, err := contract.RegisterEvent(eventID)
if err != nil {
	fmt.Printf("Failed to register contract event: %s", err)
	return
}
defer contract.Unregister(reg)

result, err := contract.SubmitTransaction("createCar", "CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

var ccEvent *fab.CCEvent
select {
case ccEvent = <-notifier:
	fmt.Printf("Received CC event: %#v\n", ccEvent)
case <-time.After(time.Second * 20):
	fmt.Printf("Did NOT receive CC event for eventId(%s)\n", eventID)
}

Output:

func (*Contract) SubmitTransaction 

func (c *Contract) SubmitTransaction(name string, args ...string) ([]byte, error)

SubmitTransaction will submit a transaction to the ledger. The transaction function 'name' will be evaluated on the endorsing peers and then submitted to the ordering service for committing to the ledger. 

Parameters:
name is the name of the transaction function to be invoked in the smart contract.
args are the arguments to be sent to the transaction function.

Returns:
The return value of the transaction function in the smart contract.
Example 
contract := myContract()

result, err := contract.SubmitTransaction("createCar", "CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

func (*Contract) Unregister 

func (c *Contract) Unregister(registration fab.Registration)

Unregister removes the given registration and closes the event channel. 

Parameters:
registration is the registration handle that was returned from RegisterContractEvent method

type Gateway 

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

Gateway is the entry point to a Fabric network

func Connect 

func Connect(config ConfigOption, identity IdentityOption, options ...Option) (*Gateway, error)

Connect to a gateway defined by a network config file. Must specify a config option, an identity option and zero or more strategy options. 

Parameters:
config is a ConfigOption used to specify the network connection configuration.  This must contain connection details for at least one 'gateway' peer.
identity is an IdentityOption which assigns a signing identity for all interactions under this Gateway connection.
options specifies other gateway options

Returns:
A Transaction object for subsequent evaluation or submission.
Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	os.Exit(1)
}

// Path to the network config (CCP) file
ccpPath := filepath.Join(
	"..",
	"connection-org1.yaml",
)

// Connect to the gateway peer(s) using the network config and identity in the wallet
gw, err := Connect(
	WithConfig(config.FromFile(filepath.Clean(ccpPath))),
	WithIdentity(wallet, "appUser"),
)
if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

Output:

func (*Gateway) Close 

func (gw *Gateway) Close()

Close the gateway connection and all associated resources, including removing listeners attached to networks and contracts created by the gateway.

func (*Gateway) GetNetwork 

func (gw *Gateway) GetNetwork(name string) (*Network, error)

GetNetwork returns an object representing a network channel. 

Parameters:
name is the name of the network channel

Returns:
A Network object representing the channel
Example 
gw := myGateway()

network, err := gw.GetNetwork("fabcar")
if err != nil {
	fmt.Printf("Failed to get network: %s\n", err)
	return
}

fmt.Println(network.Name())

Output:

type Identity 

type Identity interface {
	// contains filtered or unexported methods
}

Identity represents a specific identity format

type IdentityOption 

type IdentityOption = func(*Gateway) error

IdentityOption specifies the user identity under which all transactions are performed for this gateway instance.

func WithIdentity 

func WithIdentity(wallet wallet, label string) IdentityOption

WithIdentity is an optional argument to the Connect method which specifies the identity that is to be used to connect to the network. All operations under this gateway connection will be performed using this identity. 

Parameters:
wallet is a Wallet implementation that contains identities
label is the name of the identity in the wallet to associate with the gateway

Returns:
An IdentityOption which can be passed as the second parameter to the Connect() function
Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	os.Exit(1)
}

// Connect to the gateway peer(s) using an identity from this wallet
gw, err := Connect(
	WithConfig(config.FromFile("testdata/connection-tls.json")),
	WithIdentity(wallet, "appUser"),
)

if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

Output:

func WithUser 

func WithUser(user string) IdentityOption

WithUser is an optional argument to the Connect method which specifies the identity that is to be used to connect to the network. The creadentials are extracted from the credential store specified in the connection profile. All operations under this gateway connection will be performed using this identity. 

Parameters:
user is the name of the user in the credential store.

Returns:
An IdentityOption which can be passed as the second parameter to the Connect() function
Example 
// Connect to the gateway peer(s) using an identity defined in the network config
gw, err := Connect(
	WithConfig(config.FromFile("testdata/connection-tls.json")),
	WithUser("user1"),
)

if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

Output:

type Network 

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

A Network object represents the set of peers in a Fabric network (channel). Applications should get a Network instance from a Gateway using the GetNetwork method.

func (*Network) GetContract 

func (n *Network) GetContract(chaincodeID string) *Contract

GetContract returns instance of a smart contract on the current network. 

Parameters:
chaincodeID is the name of the chaincode that contains the smart contract

Returns:
A Contract object representing the smart contract
Example 
network := myNetwork()

contract := network.GetContract("fabcar")

fmt.Println(contract.Name())

Output:

func (*Network) GetContractWithName 

func (n *Network) GetContractWithName(chaincodeID string, name string) *Contract

GetContractWithName returns instance of a smart contract on the current network. If the chaincode instance contains more than one smart contract class (available using the latest contract programming model), then an individual class can be selected. 

Parameters:
chaincodeID is the name of the chaincode that contains the smart contract
name is the class name of the smart contract within the chaincode.

Returns:
A Contract object representing the smart contract

func (*Network) Name 

func (n *Network) Name() string

Name is the name of the network (also known as channel name)

func (*Network) RegisterBlockEvent 

func (n *Network) RegisterBlockEvent() (fab.Registration, <-chan *fab.BlockEvent, error)

RegisterBlockEvent registers for block events. Unregister must be called when the registration is no longer needed. 

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.
Example 
network := myNetwork()

reg, notifier, err := network.RegisterBlockEvent()
if err != nil {
	fmt.Printf("Failed to register block event: %s", err)
	return
}
defer network.Unregister(reg)

contract := network.GetContract("fabcar")

runContract(contract) // submit transactions

var bEvent *fab.BlockEvent
select {
case bEvent = <-notifier:
	fmt.Printf("Received block event: %#v\n", bEvent)
case <-time.After(time.Second * 20):
	fmt.Printf("Did NOT receive block event\n")
}

Output:

func (*Network) RegisterFilteredBlockEvent 

func (n *Network) RegisterFilteredBlockEvent() (fab.Registration, <-chan *fab.FilteredBlockEvent, error)

RegisterFilteredBlockEvent registers for filtered block events. Unregister must be called when the registration is no longer needed. 

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.
Example 
network := myNetwork()

reg, notifier, err := network.RegisterFilteredBlockEvent()
if err != nil {
	fmt.Printf("Failed to register filtered block event: %s", err)
	return
}
defer network.Unregister(reg)

contract := network.GetContract("fabcar")

runContract(contract) // submit transactions

var bEvent *fab.FilteredBlockEvent
select {
case bEvent = <-notifier:
	fmt.Printf("Received block event: %#v\n", bEvent)
case <-time.After(time.Second * 20):
	fmt.Printf("Did NOT receive block event\n")
}

Output:

func (*Network) Unregister 

func (n *Network) Unregister(registration fab.Registration)

Unregister removes the given registration and closes the event channel. 

Parameters:
registration is the registration handle that was returned from RegisterBlockEvent method

type Option 

type Option = func(*Gateway) error

Option functional arguments can be supplied when connecting to the gateway.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout is an optional argument to the Connect method which defines the commit timeout for all transaction submissions for this gateway.

Example 
// Path to the network config (CCP) file
ccpPath := filepath.Join(
	"..",
	"connection-org1.yaml",
)

// Connect to the gateway peer(s) using the network config
gw, err := Connect(
	WithConfig(config.FromFile(filepath.Clean(ccpPath))),
	WithUser("admin"),
	WithTimeout(300*time.Second),
)
if err != nil {
	fmt.Printf("Failed to connect to gateway: %s\n", err)
	os.Exit(1)
}
defer gw.Close()

Output:

type Transaction 

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

A Transaction represents a specific invocation of a transaction function, and provides flexibility over how that transaction is invoked. Applications should obtain instances of this class from a Contract using the Contract.CreateTransaction method.

Instances of this class are stateful. A new instance <strong>must</strong> be created for each transaction invocation.

func (*Transaction) Evaluate 

func (txn *Transaction) Evaluate(args ...string) ([]byte, error)

Evaluate a transaction function and return its results. The transaction function will be evaluated on the endorsing peers but the responses will not be sent to the ordering service and hence will not be committed to the ledger. This can be used for querying the world state.

Example 
contract := myContract()

txn, err := contract.CreateTransaction("queryCar")
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

result, err := txn.Evaluate("CAR01")
if err != nil {
	fmt.Printf("Failed to evaluate transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

func (*Transaction) RegisterCommitEvent 

func (txn *Transaction) RegisterCommitEvent() <-chan *fab.TxStatusEvent

RegisterCommitEvent registers for a commit event for this transaction. 

Returns:
the channel that is used to receive the event. The channel is closed after the event is queued.
Example 
contract := myContract()

txn, err := contract.CreateTransaction("createCar")
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

notifier := txn.RegisterCommitEvent()

result, err := txn.Submit("CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

var cEvent *fab.TxStatusEvent
select {
case cEvent = <-notifier:
	fmt.Printf("Received commit event: %#v\n", cEvent)
case <-time.After(time.Second * 20):
	fmt.Printf("Did NOT receive commit event\n")
}

fmt.Println(string(result))

Output:

func (*Transaction) Submit 

func (txn *Transaction) Submit(args ...string) ([]byte, error)

Submit a transaction to the ledger. The transaction function represented by this object will be evaluated on the endorsing peers and then submitted to the ordering service for committing to the ledger.

Example 
contract := myContract()

txn, err := contract.CreateTransaction("createCar")
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

result, err := txn.Submit("CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

type TransactionOption 

type TransactionOption = func(*Transaction) error

TransactionOption functional arguments can be supplied when creating a transaction object

func WithEndorsingPeers 

func WithEndorsingPeers(peers ...string) TransactionOption

WithEndorsingPeers is an optional argument to the CreateTransaction method which sets the peers that should be used for endorsement of transaction submitted to the ledger using Submit()

Example 
contract := myContract()

txn, err := contract.CreateTransaction(
	"createCar",
	WithEndorsingPeers("peer1.org1.example.com:8051", "peer1.org2.example.com:10051"),
)
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

result, err := txn.Submit("CAR10", "VW", "Polo", "Grey", "Mary")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

func WithTransient 

func WithTransient(data map[string][]byte) TransactionOption

WithTransient is an optional argument to the CreateTransaction method which sets the transient data that will be passed to the transaction function but will not be stored on the ledger. This can be used to pass private data to a transaction function.

Example 
contract := myContract()

transient := make(map[string][]byte)
transient["price"] = []byte("8500")

txn, err := contract.CreateTransaction(
	"changeCarOwner",
	WithTransient(transient),
)
if err != nil {
	fmt.Printf("Failed to create transaction: %s\n", err)
	return
}

result, err := txn.Submit("CAR10", "Archie")
if err != nil {
	fmt.Printf("Failed to submit transaction: %s\n", err)
	return
}

fmt.Println(string(result))

Output:

type Wallet 

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

A Wallet stores identity information used to connect to a Hyperledger Fabric network. Instances are created using factory methods on the implementing objects.

func NewFileSystemWallet 

func NewFileSystemWallet(path string) (*Wallet, error)

NewFileSystemWallet creates an instance of a wallet, held in memory. This implementation is not backed by a persistent store. 

Parameters:
path specifies where on the filesystem to store the wallet.

Returns:
A Wallet object.
Example 
walletPath := filepath.Join("..", "wallet")

wallet, err := NewFileSystemWallet(walletPath)
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	return
}

fmt.Println(wallet)

Output:

func NewInMemoryWallet 

func NewInMemoryWallet() *Wallet

NewInMemoryWallet creates an instance of a wallet, held in memory. 

Returns:
A Wallet object.
Example 
wallet := NewInMemoryWallet()

fmt.Println(wallet)

Output:

func (*Wallet) Exists 

func (w *Wallet) Exists(label string) bool

Exists tests whether the wallet contains an identity for the given label. 

Parameters:
label specifies the name of the identity in the wallet.

Returns:
True if the named identity is in the wallet.

func (*Wallet) Get 

func (w *Wallet) Get(label string) (Identity, error)

Get an identity from the wallet. The implementation class of the identity object will vary depending on its type. 

Parameters:
label specifies the name of the identity in the wallet.

Returns:
The identity object.
Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	return
}

id, err := wallet.Get("appUser")

fmt.Println(id)

Output:

func (*Wallet) List 

func (w *Wallet) List() ([]string, error)

List returns the labels of all identities in the wallet. 

Returns:
A list of identity labels in the wallet.
Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	return
}

labels, err := wallet.List()

fmt.Println(labels)

Output:

func (*Wallet) Put 

func (w *Wallet) Put(label string, id Identity) error

Put an identity into the wallet 

Parameters:
label specifies the name to be associated with the identity.
id specifies the identity to store in the wallet.
Example 
// A new transient wallet
wallet := NewInMemoryWallet()
wallet.Put("testUser", NewX509Identity("Org1MSP", "--Cert PEM--", "--Key PEM--"))

Output:

func (*Wallet) Remove 

func (w *Wallet) Remove(label string) error

Remove an identity from the wallet. If the identity does not exist, this method does nothing. 

Parameters:
label specifies the name of the identity in the wallet.
Example 
// A wallet existing in the 'wallet' folder
wallet, err := NewFileSystemWallet("wallet")
if err != nil {
	fmt.Printf("Failed to create wallet: %s\n", err)
	return
}

wallet.Remove("appUser")

Output:

type WalletStore 

type WalletStore interface {
	Put(label string, stream []byte) error
	Get(label string) ([]byte, error)
	List() ([]string, error)
	Exists(label string) bool
	Remove(label string) error
}

WalletStore is the interface for implementations that provide backing storage for identities in a wallet. To create create a new backing store, implement all the methods defined in this interface and provide a factory method that wraps an instance of this in a new Wallet object. E.g: 

  func NewMyWallet() *Wallet {
	   store := &myWalletStore{ }
	   return &Wallet{store}
  }

type X509Identity 

type X509Identity struct {
	Version     int         `json:"version"`
	MspID       string      `json:"mspId"`
	IDType      string      `json:"type"`
	Credentials credentials `json:"credentials"`
}

X509Identity represents an X509 identity

func NewX509Identity 

func NewX509Identity(mspid string, cert string, key string) *X509Identity

NewX509Identity creates an X509 identity for storage in a wallet

Example 
// create new X.509 identity
id := NewX509Identity("Org1MSP", "--Cert PEM--", "--Key PEM--")

// put it in a wallet
wallet := NewInMemoryWallet()
wallet.Put("testUser", id)

Output:

func (*X509Identity) Certificate 

func (x *X509Identity) Certificate() string

Certificate returns the X509 certificate PEM

func (*X509Identity) Key 

func (x *X509Identity) Key() string

Key returns the private key PEM

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.