Package org.hyperledger.fabric.client

Interface Contract

public interface Contract
Represents a smart contract instance in a network. Applications should get a Contract instance from a Network using the getContract method.

The Contract allows applications to:

For more complex transaction invocations, such as including transient data, the transaction proposal can be built using newProposal(String). Once built, the proposal can either be evaluated, or can be sent for endorsement and the resulting transaction object can be submitted to the orderer to be committed to the ledger. This flow can also be used to asynchronously submit transactions, which allows the transaction result to be accessed prior to its commit to the ledger.

Evaluate transaction example:


     byte[] result = contract.newProposal("transactionName")
             .addArguments("one", "two")
             // Specify additional proposal options, such as transient data
             .build()
             .evaluate();

Submit transaction example:


     byte[] result = contract.newProposal("transactionName")
             .addArguments("one", "two")
             // Specify additional proposal options, such as transient data
             .build()
             .endorse()
             .submit();

Async submit example


     SubmittedTransaction commit = contract.newProposal("transactionName")
             .build()
             .endorse()
             .submitAsync();
     byte[] result = commit.getResult();

     // Update UI or reply to REST request before waiting for commit status

     Status status = commit.getStatus();
     if (!status.isSuccessful()) {
         // Commit failure
     }

Off-line signing

By default, proposal and transaction messages will be signed using the signing implementation specified when connecting the Gateway. In cases where an external client holds the signing credentials, a signing implementation can be omitted when connecting the Gateway and off-line signing can be carried out by:

  1. Returning the serialized proposal, transaction or commit status message along with its digest to the client for them to generate a signature.
  2. On receipt of the serialized message and signature from the client, creating a signed proposal, transaction or commit using the Gateway.newSignedProposal(byte[], byte[]), Gateway.newSignedTransaction(byte[], byte[]) or Gateway.newSignedCommit(byte[], byte[]) methods respectively.

Note that the message digest is created with the hash implementation specified by the Gateway.Builder.hash(Function) option used to create the Gateway instance. For off-line signing implementations that require the entire message content, a NONE (or no-op) hash implementation should be specified.

Signing of a proposal that can then be evaluated or endorsed:


     Proposal unsignedProposal = contract.newProposal("transactionName").build();
     byte[] proposalBytes = unsignedProposal.getBytes();
     byte[] proposalDigest = unsignedProposal.getDigest();
     // Generate signature from digest
     Proposal signedProposal = gateway.newSignedProposal(proposalBytes, proposalSignature);

Signing of an endorsed transaction that can then be submitted to the orderer:


     Transaction unsignedTransaction = signedProposal.endorse();
     byte[] transactionBytes = unsignedTransaction.getBytes();
     byte[] transactionDigest = unsignedTransaction.getDigest();
     // Generate signature from digest
     Transaction signedTransaction = gateway.newSignedTransaction(transactionBytes, transactionSignature);

Signing of a commit that can be used to obtain the status of a submitted transaction:


     Commit unsignedCommit = signedTransaction.submitAsync();
     byte[] commitBytes = unsignedCommit.getBytes();
     byte[] commitDigest = unsignedCommit.getDigest();
     // Generate signature from digest
     Commit signedCommit = gateway.newSignedCommit(commitBytes, commitDigest);

     byte[] result = signedTransaction.getResult();
     Status status = signedCommit.getStatus();

  • Method Details

    • getChaincodeName

      String getChaincodeName()
      Get the name of the chaincode that contains the smart contract.
      Returns:
      Chaincode name.

    • getContractName

      Optional<String> getContractName()
      Get the name of the smart contract within the chaincode. An empty value indicates that this Contract refers to the chaincode's default smart contract.
      Returns:
      An empty optional for the default smart contract; otherwise the contract name.

    • submitTransaction

      byte[] submitTransaction(String name) throws EndorseException, CommitException, SubmitException, CommitStatusException
      Submit a transaction to the ledger and return its result only after it is committed to the ledger. The transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be committed to the ledger.

      This method is equivalent to:

      
     contract.newProposal(name)
             .build()
             .submit();
      Parameters:
      name - Transaction function name.
      Returns:
      Payload response from the transaction function.
      Throws:
      EndorseException - if the endorse invocation fails.
      SubmitException - if the submit invocation fails.
      CommitStatusException - if the commit status invocation fails.
      CommitException - if the transaction commits unsuccessfully.
      NullPointerException - if the transaction name is null.

    • submitTransaction

      byte[] submitTransaction(String name, String... args) throws EndorseException, SubmitException, CommitStatusException, CommitException
      Submit a transaction to the ledger and return its result only after it is committed to the ledger. The transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be committed to the ledger.

      This method is equivalent to:

      
     contract.newProposal(name)
             .addArguments(arg1, arg2)
             .build()
             .submit();
      Parameters:
      name - Transaction function name.
      args - Transaction function arguments.
      Returns:
      Payload response from the transaction function.
      Throws:
      EndorseException - if the endorse invocation fails.
      SubmitException - if the submit invocation fails.
      CommitStatusException - if the commit status invocation fails.
      CommitException - if the transaction commits unsuccessfully.
      NullPointerException - if the transaction name is null.

    • submitTransaction

      byte[] submitTransaction(String name, byte[]... args) throws EndorseException, CommitException, SubmitException, CommitStatusException
      Submit a transaction to the ledger and return its result only after it is committed to the ledger. The transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be committed to the ledger.

      This method is equivalent to:

      
     contract.newProposal(name)
             .addArguments(arg1, arg2)
             .build()
             .submit();
      Parameters:
      name - Transaction function name.
      args - Transaction function arguments.
      Returns:
      Payload response from the transaction function.
      Throws:
      EndorseException - if the endorse invocation fails.
      SubmitException - if the submit invocation fails.
      CommitStatusException - if the commit status invocation fails.
      CommitException - if the transaction commits unsuccessfully.
      NullPointerException - if the transaction name is null.

    • evaluateTransaction

      byte[] evaluateTransaction(String name) throws GatewayException
      Evaluate a transaction function and return its results. A transaction proposal will be evaluated on endorsing peers but the transaction will not be sent to the ordering service and so will not be committed to the ledger. This can be used for querying the world state.

      This method is equivalent to:

      
     contract.newProposal(name)
             .build()
             .evaluate();
      Parameters:
      name - Transaction function name.
      Returns:
      Payload response from the transaction function.
      Throws:
      GatewayException - if the gRPC service invocation fails.
      NullPointerException - if the transaction name is null.

    • evaluateTransaction

      byte[] evaluateTransaction(String name, String... args) throws GatewayException
      Evaluate a transaction function and return its results. A transaction proposal will be evaluated on endorsing peers but the transaction will not be sent to the ordering service and so will not be committed to the ledger. This can be used for querying the world state.

      This method is equivalent to:

      
     contract.newProposal(name)
             .addArguments(arg1, arg2)
             .build()
             .evaluate();
      Parameters:
      name - Transaction function name.
      args - Transaction function arguments.
      Returns:
      Payload response from the transaction function.
      Throws:
      GatewayException - if the gRPC service invocation fails.
      NullPointerException - if the transaction name is null.

    • evaluateTransaction

      byte[] evaluateTransaction(String name, byte[]... args) throws GatewayException
      Evaluate a transaction function and return its results. A transaction proposal will be evaluated on endorsing peers but the transaction will not be sent to the ordering service and so will not be committed to the ledger. This can be used for querying the world state.

      This method is equivalent to:

      
     contract.newProposal(name)
             .addArguments(arg1, arg2)
             .build()
             .evaluate();
      Parameters:
      name - Transaction function name.
      args - Transaction function arguments.
      Returns:
      Payload response from the transaction function.
      Throws:
      GatewayException - if the gRPC service invocation fails.
      NullPointerException - if the transaction name is null.

    • newProposal

      Proposal.Builder newProposal(String transactionName)
      Build a new proposal that can be evaluated or sent to peers for endorsement. Supports both asynchronous submit of transactions and off-line signing flow.
      Parameters:
      transactionName - The name of the transaction to be invoked.
      Returns:
      A proposal builder.
      Throws:
      NullPointerException - if the transaction name is null.