How to listen for transactions receipts

Use the Orchestrate SDK to listen for successful transactions (mined) on any Blockchain network. The process of sending transactions on Ethereum is asynchronous, meaning that Orchestrate notifies Kafka once the transaction receipt is ready.

Orchestrate allows you to:

• Listen and decode the events of transactions from smart contracts registered in Orchestrate.
• Listen to all external transactions of the network.

Get a transaction receipt

Prerequisites

• A registered chain
• A running listener (see example below)
• A successfully sent transaction

Steps

1. Instantiate a consumer connected to Kafka: const consumer = new Consumer(['localhost:9092']).
2. Execute the connect() function of the consumer.
3. Register an event listener on the consumer (see example below).
4. Execute the consume() function on the consumer.

important

For each successfully received transaction receipt, we recommend executing the commit() function to notify Kafka the message has been successfully processed and that it should not be read again even if the listener restarts.

JavaScript (SDK)

await consumer.connect();

// Register the event listener before calling consume
consumer.on(EventType.Response, async (message: ResponseMessage) => {
  const { offset, topic, value } = message.content();

  console.log("Message received !", {
    Id: value.id,
    jobUUID: value.jobUUID,
    offset,
    topic,
    chain: value.chain,
  });

  if (value.errors && value.errors.length !== 0) {
    console.log("Transaction failed!", {
      errors: value.errors,
      txContext: value.txContext,
    });
  } else {
    console.log("Receipt:", value.receipt);
  }

  // We commit every message
  await message.commit();
});

await consumer.consume();

Output on successful transaction

Message received ! {
  Id: '34e7fb86-a971-462b-bd96-ad973eb31e6e',
  jobUUID: '83e8defa-2c0c-4a03-b56d-a6949a1c98b0',
  offset: '0',
  topic: 'topic-tx-decoded',
  chain: 'besu'
}
Receipt: {
  blockHash: '0x42ba84709344d4456c77f138b26be875ce6b9197f2864956c0edc2b75208e4c1',
  blockNumber: 21,
  txIndex: 0,
  txHash: '0xd1e8a764c563d315267389aa5e08de797a8879038f555b484f86fa490c5717ee',
  status: true,
  contractAddress: '0x2F4aeA4fcff7b774fccd649818285C69a9e87A76',
  gasUsed: 1017305,
  cumulativeGasUsed: 1017305,
  postState: undefined,
  bloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000008000000000000000000000000000020000000000020000000000000000000800000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000002000000000000000000000000000000000000000000000040000020000400000000000000000000000000000000000000000400000000000000000000',
  logs: [
    {
      address: '0x2F4aeA4fcff7b774fccd649818285C69a9e87A76',
      topics: [Array],
      data: '0x00000000000000000000000000000000000000000000021e19e0c9bab2400000',
      event: 'Transfer(address,address,uint256)',
      decodedData: [Object],
      blockNumber: 21,
      txHash: '0xd1e8a764c563d315267389aa5e08de797a8879038f555b484f86fa490c5717ee',
      txIndex: 0,
      blockHash: '0x42ba84709344d4456c77f138b26be875ce6b9197f2864956c0edc2b75208e4c1',
      index: 0,
      removed: false
    }
  ],
  revertReason: undefined,
  output: undefined,
  privateFrom: undefined,
  privateFor: [],
  privacyGroupId: undefined
}

Transaction failures

When Orchestrate sends a transaction, it goes through two processes. During the first process, Orchestrate builds and checks the transaction and routes it to the right chain and node. During the second process, the target node handles the transaction and adds it to the blockchain.

These two processes are executed one after the other and both processes trigger events. The first event indicates the success of the first phase, between orchestrate and the blockchain, and the second event indicates the success on the blockchain itself.

If the transaction fails during the first process, the console log displays Transaction failed! and does not generate a receipt.

If the transaction connects to the blockchain, it attempts to complete the second process. If the second phase is successful, the transaction goes through and generates the transaction receipt. The status field in the transaction receipt displays true.

If the second phase fails, the transaction does not go through, but still generates a receipt. In this case, the status field in the transaction receipt displays false. Refer to the revert reason to determine why the contract might have failed.

Revert reason

The revert reason displays in the transaction receipt if an error occurs during execution of a smart contract. Smart contracts must use the revert or require features to be able to return a revert reason.

For example, the ERC20 token smart contract can return a revert reason when not enough tokens are available at the source address when transferring tokens. The message "ERC20: transfer amount exceeds allowance" is then returned to the user in the transaction receipt.

Requirements

• The revert reason must be configured on nodes. For instance on Hyperledger Besu, the --revert-reason-enabled option must be set.
• The smart contract to which transactions are sent must implement a revert reason on failure.

Read the revert reason

Orchestrate helps by decoding the revert reason and displays the clear message in the output. Simply retrieve the revertReason field of the receipt.

Decoded revert reason

The revertReason property in the transaction receipt JSON output has the decoded ERC20: transfer amount exceeds balance string value instead of the encoded raw value.