fabric-sdk-go: github.com/hyperledger/fabric-sdk-go/pkg/gateway Index | Examples | Files

package gateway

import "github.com/hyperledger/fabric-sdk-go/pkg/gateway"

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/master/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.

Code:

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

Index

Examples

Package Files

contract.go filesystemwallet.go gateway.go identity.go inmemorywallet.go network.go spi.go transaction.go wallet.go x509identity.go

type ConfigOption Uses

type ConfigOption = func(*Gateway) error

ConfigOption specifies the gateway configuration source.

func WithConfig Uses

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

Code:

// 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()

func WithSDK Uses

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

Code:

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

type Contract Uses

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 Uses

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.

Code:

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

func (*Contract) EvaluateTransaction Uses

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.

Code:

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

func (*Contract) Name Uses

func (c *Contract) Name() string

Name returns the name of the smart contract

func (*Contract) RegisterEvent Uses

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.

Code:

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

func (*Contract) SubmitTransaction Uses

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.

Code:

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

func (*Contract) Unregister Uses

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 Uses

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

Gateway is the entry point to a Fabric network

func Connect Uses

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.

Code:

// 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()

func (*Gateway) Close Uses

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 Uses

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

Code:

gw := myGateway()

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

fmt.Println(network.Name())

type Identity Uses

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

Identity represents a specific identity format

type IdentityOption Uses

type IdentityOption = func(*Gateway) error

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

func WithIdentity Uses

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

Code:

// 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()

func WithUser Uses

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

Code:

// 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()

type Network Uses

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 Uses

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

Code:

network := myNetwork()

contract := network.GetContract("fabcar")

fmt.Println(contract.Name())

func (*Network) GetContractWithName Uses

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 Uses

func (n *Network) Name() string

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

func (*Network) RegisterBlockEvent Uses

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.

Code:

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")
}

func (*Network) RegisterFilteredBlockEvent Uses

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.

Code:

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")
}

func (*Network) Unregister Uses

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 Uses

type Option = func(*Gateway) error

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

func WithTimeout Uses

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.

Code:

// 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()

type Transaction Uses

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 Uses

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.

Code:

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

func (*Transaction) RegisterCommitEvent Uses

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.

Code:

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

func (*Transaction) Submit Uses

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.

Code:

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

type TransactionOption Uses

type TransactionOption = func(*Transaction) error

TransactionOption functional arguments can be supplied when creating a transaction object

func WithEndorsingPeers Uses

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

Code:

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

func WithTransient Uses

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.

Code:

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

type Wallet Uses

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 Uses

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.

Code:

walletPath := filepath.Join("..", "wallet")

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

fmt.Println(wallet)

func NewInMemoryWallet Uses

func NewInMemoryWallet() *Wallet

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

Returns:
A Wallet object.

Code:

wallet := NewInMemoryWallet()

fmt.Println(wallet)

func (*Wallet) Exists Uses

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 Uses

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.

Code:

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

func (*Wallet) List Uses

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.

Code:

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

func (*Wallet) Put Uses

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.

Code:

// A new transient wallet
wallet := NewInMemoryWallet()
wallet.Put("testUser", NewX509Identity("Org1MSP", "--Cert PEM--", "--Key PEM--"))

func (*Wallet) Remove Uses

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.

Code:

// 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")

type WalletStore Uses

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 Uses

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 Uses

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

NewX509Identity creates an X509 identity for storage in a wallet

Code:

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

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

func (*X509Identity) Certificate Uses

func (x *X509Identity) Certificate() string

Certificate returns the X509 certificate PEM

func (*X509Identity) Key Uses

func (x *X509Identity) Key() string

Key returns the private key PEM

Package gateway imports 24 packages (graph) and is imported by 1 packages. Updated 2020-10-22. Refresh now. Tools for package owners.