Interface Contract

Represents a smart contract, and allows applications to:

For more complex transaction invocations, such as including private data, transactions can be evaluated or submitted using evaluate or submit respectively. The result of a submitted transaction can be accessed prior to its commit to the ledger using submitAsync.

Example: Evaluate transaction

const result = await contract.evaluate('transactionName', {
    arguments: ['one', 'two'],
    // Specify additional proposal options here
});

Example: Submit transaction

const result = await contract.submit('transactionName', {
    arguments: ['one', 'two'],
    // Specify additional proposal options here
});

Example: Async submit

const commit = await contract.submitAsync('transactionName', {
    arguments: ['one', 'two']
});
const result = commit.getResult();

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

const status = await commit.getStatus();
if (!status.successful) {
    throw new Error(`transaction ${status.transactionId} failed with status code ${status.code}`);
}

A finer-grained transaction flow can be employed by using newProposal. This allows retry of individual steps in the flow in response to errors.

Example: Fine-grained submit transaction

const proposal = contract.newProposal('transactionName');
const transaction = await proposal.endorse();
const commit = await transaction.submit();

const result = transaction.getResult();
const status = await commit.getStatus();

Off-line signing

By default, proposal, transaction and commit status messages will be signed using the signing implementation specified when connecting the Gateway. In cases where an external client holds the signing credentials, a default signing implementation can be omitted 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. With the serialized message and signature received from the client to create a signed proposal, transaction or commit using the Gateway.newSignedProposal, Gateway.newSignedTransaction or Gateway.newSignedCommit methods respectively.

Note that the message digest is created with the hash implementation specified by the hash option passed to the connect function 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.

Example: Off-line signing

const unsignedProposal = contract.newProposal('transactionName');
const proposalBytes = unsignedProposal.getBytes();
const proposalDigest = unsignedProposal.getDigest();
const proposalSignature = // Generate signature from digest
const signedProposal = gateway.newSignedProposal(proposalBytes, proposalSignature);

const unsignedTransaction = await signedProposal.endorse();
const transactionBytes = unsignedTransaction.getBytes();
const transactionDigest = unsignedTransaction.getDigest();
const transactionSignature = // Generate signature from digest
const signedTransaction = gateway.newSignedTransaction(transactionBytes, transactionSignature);

const unsignedCommit = await signedTransaction.submit();
const commitBytes = unsignedCommit.getBytes();
const commitDigest = unsignedCommit.getDigest();
const commitSignature = // Generate signature from digest
const signedCommit = gateway.newSignedCommit(commitBytes, commitSignature);

const result = signedTransaction.getResult();
const status = await signedCommit.getStatus();
interface Contract {
    evaluate(transactionName: string, options?: ProposalOptions): Promise<Uint8Array>;
    evaluateTransaction(name: string, ...args: (string | Uint8Array)[]): Promise<Uint8Array>;
    getChaincodeName(): string;
    getContractName(): undefined | string;
    newProposal(transactionName: string, options?: ProposalOptions): Proposal;
    submit(transactionName: string, options?: ProposalOptions): Promise<Uint8Array>;
    submitAsync(transactionName: string, options?: ProposalOptions): Promise<SubmittedTransaction>;
    submitTransaction(name: string, ...args: (string | Uint8Array)[]): Promise<Uint8Array>;
}

Methods

evaluate evaluateTransaction getChaincodeName getContractName newProposal submit submitAsync submitTransaction

Methods

evaluate

  • evaluate(transactionName, options?): Promise<Uint8Array>

  • 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.

    Parameters

    • transactionName: string

      Name of the transaction to invoke.

    • Optionaloptions: ProposalOptions

      Transaction invocation options.

    Returns Promise<Uint8Array>

    The result returned by the transaction function.

    Throws

    GatewayError Thrown if the gRPC service invocation fails.

evaluateTransaction

  • evaluateTransaction(name, ...args): Promise<Uint8Array>

  • 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.evaluate(name, { arguments: [ arg1, arg2 ] });

    Parameters

    • name: string

      Name of the transaction to invoke.

    • Rest...args: (string | Uint8Array)[]

      Transaction arguments.

    Returns Promise<Uint8Array>

    The result returned by the transaction function.

    Throws

    GatewayError Thrown if the gRPC service invocation fails.

getChaincodeName

  • getChaincodeName(): string

  • Get the name of the chaincode that contains this smart contract.

    Returns string

    The chaincode name.

getContractName

  • getContractName(): undefined | string

  • Get the name of the smart contract within the chaincode.

    Returns undefined | string

    The contract name, or undefined for the default smart contract.

newProposal

  • newProposal(transactionName, options?): Proposal

  • Create a transaction proposal that can be evaluated or endorsed. Supports off-line signing flow.

    Parameters

    • transactionName: string

      Name of the transaction to invoke.

    • Optionaloptions: ProposalOptions

      Transaction invocation options.

    Returns Proposal

submit

  • submit(transactionName, options?): Promise<Uint8Array>

  • 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.

    Parameters

    • transactionName: string

      Name of the transaction to invoke.

    • Optionaloptions: ProposalOptions

      Transaction invocation options.

    Returns Promise<Uint8Array>

    The result returned by the transaction function.

    Throws

    EndorseError Thrown if the endorse invocation fails.

    Throws

    SubmitError Thrown if the submit invocation fails.

    Throws

    CommitStatusError Thrown if the commit status invocation fails.

    Throws

    CommitError Thrown if the transaction commits unsuccessfully.

submitAsync

  • submitAsync(transactionName, options?): Promise<SubmittedTransaction>

  • Submit a transaction to the ledger and return immediately after successfully sending to the orderer. The transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be committed to the ledger. The submitted transaction that is returned can be used to obtain to the transaction result, and to wait for it to be committed to the ledger.

    Parameters

    • transactionName: string

      Name of the transaction to invoke.

    • Optionaloptions: ProposalOptions

      Transaction invocation options.

    Returns Promise<SubmittedTransaction>

    A submitted transaction, providing access to the transaction result and commit status.

    Throws

    GatewayError Thrown if the gRPC service invocation fails.

submitTransaction

  • submitTransaction(name, ...args): Promise<Uint8Array>

  • 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.submit(name, { arguments: [ arg1, arg2 ] });

    Parameters

    • name: string

      Name of the transaction to be invoked.

    • Rest...args: (string | Uint8Array)[]

      Transaction arguments.

    Returns Promise<Uint8Array>

    The result returned by the transaction function.

    Throws

    EndorseError Thrown if the endorse invocation fails.

    Throws

    SubmitError Thrown if the submit invocation fails.

    Throws

    CommitStatusError Thrown if the commit status invocation fails.

    Throws

    CommitError Thrown if the transaction commits unsuccessfully.

Settings

Member Visibility

On This Page

Off-line signing
Methods