Skip to content

Commit

Permalink
deploy: af9a64a
Browse files Browse the repository at this point in the history
  • Loading branch information
@nguyer
nguyer committed Apr 12, 2024
1 parent 1a3cdc8 commit ae8cfe1
Show file tree
Hide file tree
Showing 2 changed files with 905 additions and 779 deletions.
120 changes: 120 additions & 0 deletions head/architecture/blockchain_connector_framework.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,11 @@ <h2 class="no_toc text-delta" id="table-of-contents">
</li>
<li><a href="#policy-manager" id="markdown-toc-policy-manager">Policy Manager</a></li>
<li><a href="#event-streams" id="markdown-toc-event-streams">Event Streams</a></li>
<li><a href="#blockchain-error-messages" id="markdown-toc-blockchain-error-messages">Blockchain error messages</a> <ol>
<li><a href="#format-of-a-firefly-evmconnect-error-message" id="markdown-toc-format-of-a-firefly-evmconnect-error-message">Format of a <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> error message</a></li>
<li><a href="#retrieving-evm-blockchain-transaction-errors" id="markdown-toc-retrieving-evm-blockchain-transaction-errors">Retrieving EVM blockchain transaction errors</a></li>
</ol>
</li>
</ol><hr />

<iframe width="736" height="414" src="https://www.youtube.com/embed/Bwx7MWjP1z0?start=259" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen=""></iframe>
Expand Down Expand Up @@ -601,6 +606,121 @@ <h2 id="event-streams">
</ul>

<p><a href="../images/firefly_connector_toolkit_event_streams.jpg"><img src="/firefly/head/images/firefly_connector_toolkit_event_streams.jpg" alt="FireFly Connector Toolkit Event Streams" /></a></p>
<h2 id="blockchain-error-messages">


<a href="#blockchain-error-messages" class="anchor-heading" aria-labelledby="blockchain-error-messages"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Blockchain error messages


</h2>


<p>The receipt for a FireFly blockchain operation contains an <code class="language-plaintext highlighter-rouge">extraInfo</code> section that records additional information about the transaction. For example:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>"receipt": {
...
"extraInfo": [
{
{
"contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436",
"cumulativeGasUsed":"33812",
"from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae",
"to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3",
"gasUsed":"33812",
"status":"0",
"errorMessage":"Not enough tokens",
}
}
],
...
},
</code></pre></div></div>

<p>The <code class="language-plaintext highlighter-rouge">errorMessage</code> field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in <code class="language-plaintext highlighter-rouge">errorMessage</code> field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked.</p>
<h3 id="format-of-a-firefly-evmconnect-error-message">


<a href="#format-of-a-firefly-evmconnect-error-message" class="anchor-heading" aria-labelledby="format-of-a-firefly-evmconnect-error-message"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Format of a <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> error message


</h3>


<p>The following section describes the way that the <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> plugin uses the <code class="language-plaintext highlighter-rouge">errorMessage</code> field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow.</p>

<p>The <code class="language-plaintext highlighter-rouge">errorMessage</code> field for a <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> transaction may contain one of the following:</p>

<ol>
<li>An error message from the FireFly blockchain connector
<ul>
<li>For example <code class="language-plaintext highlighter-rouge">"FF23054", "Error return value unavailable"</code></li>
</ul>
</li>
<li>A decoded error string from the blockchain transaction
<ul>
<li>For example <code class="language-plaintext highlighter-rouge">Not enough tokens</code></li>
<li>This could be an error string from a smart contract e.g. <code class="language-plaintext highlighter-rouge">require(requestedTokens &lt;= allowance, "Not enough tokens");</code></li>
</ul>
</li>
<li>An un-decoded byte string from the blockchain transaction
<ul>
<li>For example
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010
</code></pre></div> </div>
</li>
<li>This could be a custom error from a smart contract e.g.
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>error AllowanceTooSmall(uint256 requested, uint256 allowance);
...
revert AllowanceTooSmall({ requested: 100, allowance: 20 });
</code></pre></div> </div>
</li>
<li>If an error reason cannot be decoded the <code class="language-plaintext highlighter-rouge">returnValue</code> of the <code class="language-plaintext highlighter-rouge">extraInfo</code> will be set to the raw byte string. For example:
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>"receipt": {
...
"extraInfo": [
{
{
"contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436",
"cumulativeGasUsed":"33812",
"from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae",
"to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3",
"gasUsed":"33812",
"status":"0",
"errorMessage":"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010",
"returnValue":"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010"
}
}
],
...
},
</code></pre></div> </div>
</li>
</ul>
</li>
</ol>
<h3 id="retrieving-evm-blockchain-transaction-errors">


<a href="#retrieving-evm-blockchain-transaction-errors" class="anchor-heading" aria-labelledby="retrieving-evm-blockchain-transaction-errors"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Retrieving EVM blockchain transaction errors


</h3>


<p>The ability of a blockchain connector such as <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the <code class="language-plaintext highlighter-rouge">REVERT</code> op code, with a <code class="language-plaintext highlighter-rouge">REASON</code> set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu™ provides the <code class="language-plaintext highlighter-rouge">--revert-reason-enabled</code> configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final <code class="language-plaintext highlighter-rouge">REVERT</code> <code class="language-plaintext highlighter-rouge">REASON</code>. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks.</p>

<p>The <code class="language-plaintext highlighter-rouge">firefly-evmconnect</code> blockchain connector attempts to obtain the reason for a transaction revert and include it in the <code class="language-plaintext highlighter-rouge">extraInfo</code> field. It uses the following mechanisms, in this order:</p>

<ol>
<li>Checks if the blockchain transaction receipt contains the revert reason.</li>
<li>If the revert reason is not in the receipt, and the <code class="language-plaintext highlighter-rouge">connector.traceTXForRevertReason</code> configuration option is set to <code class="language-plaintext highlighter-rouge">true</code>, calls <code class="language-plaintext highlighter-rouge">debug_traceTransaction</code> to obtain a full trace of the transaction and extract the revert reason. By default, <code class="language-plaintext highlighter-rouge">connector.traceTXForRevertReason</code> is set to <code class="language-plaintext highlighter-rouge">false</code> to avoid submitting high-resource requests to the EVM client.</li>
</ol>

<p>If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way:</p>
<ul>
<li>Attempts to decode the bytes as the standard <code class="language-plaintext highlighter-rouge">Error(string)</code> signature format and includes the decoded string in the <code class="language-plaintext highlighter-rouge">errorMessage</code></li>
<li>If the reason is not a standard <code class="language-plaintext highlighter-rouge">Error(String)</code> error, sets the <code class="language-plaintext highlighter-rouge">errorMessage</code> to <code class="language-plaintext highlighter-rouge">FF23053: Error return value for custom error: &lt;raw hex string&gt;</code> and includes the raw byte string in the <code class="language-plaintext highlighter-rouge">returnValue</code> field.</li>
</ul>



Expand Down
Loading

0 comments on commit ae8cfe1

Please sign in to comment.