Docs: HL Burrow Documentation and RTD Fixes

docs/source/_static/theme_overrides.css

@@ -0,0 +1,15 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+      word-break: break-word !important;
+   }
+
+   .wy-table-responsive {
+      overflow: auto !important;
+   }
+
+}

docs/source/build/index.rst

@@ -265,17 +265,19 @@ Also as long as this page can be deprecated (or just not complete) you can brows
 Main Parameters
 """""""""""""""
 
-+--------------+-----------------+---------+------------------------------------------------------------------------+
-| Parameter    | Possible values | Default | Description                                                            |
-+==============+=================+=========+========================================================================+
-| TESTING      |      ON/OFF     | ON      | Enables or disables build of the tests                                 |
-+--------------+                 +---------+------------------------------------------------------------------------+
-| BENCHMARKING |                 | OFF     | Enables or disables build of the Google Benchmarks library             |
-+--------------+                 +---------+------------------------------------------------------------------------+
-| COVERAGE     |                 | OFF     | Enables or disables lcov setting for code coverage generation          |
-+--------------+                 +---------+------------------------------------------------------------------------+
-| USE_LIBURSA  |                 | OFF     | Enables usage of the HL Ursa cryptography instead of the standard one  |
-+--------------+-----------------+---------+------------------------------------------------------------------------+
++----------------------------------+-----------------+---------+------------------------------------------------------------------------+
+| Parameter                        | Possible values | Default | Description                                                            |
++==================================+=================+=========+========================================================================+
+| TESTING                          |      ON/OFF     | ON      | Enables or disables build of the tests                                 |
++----------------------------------+                 +---------+------------------------------------------------------------------------+
+| BENCHMARKING                     |                 | OFF     | Enables or disables build of the Google Benchmarks library             |
++----------------------------------+                 +---------+------------------------------------------------------------------------+
+| COVERAGE                         |                 | OFF     | Enables or disables lcov setting for code coverage generation          |
++----------------------------------+                 +---------+------------------------------------------------------------------------+
+| USE_LIBURSA                      |                 | OFF     | Enables usage of the HL Ursa cryptography instead of the standard one  |
++----------------------------------+                 +---------+------------------------------------------------------------------------+
+| USE_BURROW                       |                 | OFF     | Enables the HL Burrow EVM integration                                  |
++----------------------------------+-----------------+---------+------------------------------------------------------------------------+
 
 .. note:: If you would like to use HL Ursa cryptography for your build, please install `Rust <https://www.rust-lang.org/tools/install>`_ in addition to other dependencies. Learn more about HL Ursa integration `here <../integrations/index.html#hyperledger-ursa>`_.
 

docs/source/conf.py

@@ -2,6 +2,9 @@
 import sys
 import sphinx_rtd_theme
 import yaml
+from sphinx.highlighting import lexers
+from pygments_lexer_solidity import SolidityLexer
+lexers['solidity'] = SolidityLexer()
 
 sys.path.insert(0, os.path.abspath('.'))
 
@@ -25,6 +28,13 @@
     'sphinx_extensions.iroha_permissions'
 ]
 
+html_static_path = ['_static']
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+     }
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/source/develop/api/commands.rst

@@ -200,6 +200,54 @@ Possible Stateful Validation Errors
     "3", "No such account", "Cannot find account to append role to", "Make sure account id is correct"
     "4", "No such role", "Cannot find role with such name", "Make sure role id is correct"
 
+Call engine
+-----------
+
+Purpose
+^^^^^^^
+
+The purpose of call engine command is to deploy a new contract to the Iroha EVM or to call a method of an already existing smart contract.
+An execution of a smart contract can potentially modify the state of the ledger provided the transaction that contains this command is accepted to a block and the block is committed.
+
+Schema
+^^^^^^
+
+.. code-block:: proto
+
+    message CallEngine {
+        string caller = 1;  // hex string
+        oneof opt_callee {
+            string callee = 2;  // hex string
+        }
+        string input = 3;   // hex string
+    }
+
+Structure
+^^^^^^^^^
+
+.. csv-table::
+    :header: "Field", "Description", "Constraint", "Example"
+
+    "Caller", "Iroha account ID of an account on whose behalf the command is run", "<account_name>@<domain_id>", "test@mydomain"
+    "Callee", "the EVM address of a deployed smart contract", "20-bytes string in hex representation", "7C370993FD90AF204FD582004E2E54E6A94F2651"
+    "Input", "Bytecode of a smart contract for a newly deployed contracts or ABI-encoded string of the contract method selector followed by the `set of its arguments <https://solidity.readthedocs.io/en/v0.6.5/abi-spec.html>`_", "Hex string", "40c10f19000000000000000000000000969453762b0c739dd285b31635efa00e24c2562800000000000000000000000000000000000000000000000000000000000004d2"
+
+Validation
+^^^^^^^^^^
+
+1. Caller is a valid Iroha account ID
+2. The transaction creator has a role with either CanCallEngine permission
+
+Possible Stateful Validation Errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. csv-table::
+    :header: "Code", "Error Name", "Description", "How to solve"
+
+    "1", "Engine is not configured", "This error means that Iroha was built without Burrow EVM", "See `Build <../../build/index.html#main-parameters>`_ section of documentation to build Iroha correctly"
+    "2", "No such permissions", "Command’s creator does not have a permission to call EVM engine", "Grant the necessary permission"
+    "3", "CallEngine error", "Code execution in EVM failed; the reason can be both in the contract code itself or be rooted in nested Iroha commands call", "Investigation of the error root cause is required in order to diagnose the issue"
+
 Create account
 --------------
 

docs/source/develop/api/queries.rst

@@ -15,6 +15,84 @@ The validation for all queries includes:
 - query counter — checked to be incremented with every subsequent query from query creator
 - roles — depending on the query creator's role: the range of state available to query can relate to to the same account, account in the domain, to the whole chain, or not allowed at all
 
+Engine Receipts
+^^^^^^^^^^^^^^^
+
+Purpose
+-------
+
+Retrieve a receipt of a CallEngine command.
+Similar to the eth.GetTransactionReceipt API call of Ethereum JSON RPC API.
+Allows to access the event log created during computations inside the EVM.
+
+Request Schema
+--------------
+
+.. code-block:: proto
+
+   message GetEngineReceipts{
+    string tx_hash = 1;     // hex string
+}
+
+Request Structure
+-----------------
+
+.. csv-table::
+    :header: "Field", "Description", "Constraint", "Example"
+    :widths: 15, 30, 20, 15
+
+    "Transaction Hash", "hash of the transaction that has the CallEngine command", "hash in hex format", "5241f70cf3adbc180199c1d2d02db82334137aede5f5ed35d649bbbc75ab2634"
+
+Response Schema
+---------------
+
+.. code-block:: proto
+
+    message EngineReceiptsResponse {
+        repeated EngineReceipt engine_receipt = 1;
+    }
+    message EngineReceipt {
+        int32 command_index = 1;
+        string caller = 2;
+        oneof opt_to_contract_address {
+            CallResult call_result = 3;
+            string contract_address = 4;
+        }
+        repeated EngineLog logs = 5;
+    }
+    message EngineLog {
+        string address = 1;     // hex string
+        string data = 2;            // hex string
+        repeated string topics = 3; // hex string
+    }
+
+Response Structure
+------------------
+
+.. csv-table::
+    :header: "Field", "Description", "Constraint", "Example"
+    :widths: 15, 30, 20, 15
+
+    "Command Index", "Index of the CallEngine command in the transaction", "non-negative integer", "0"
+    "Tx Hash", "Hash of the transaction that contained the CallEngine command", "hash in hex format", "5241f70cf3adbc180199c1d2d02db82334137aede5f5ed35d649bbbc75ab2634"
+    "Tx Index", "Index of the transaction in the block", "non-negative integer", "3"
+    "Block Hash", "Hash of the block that contains the transaction with CallEngine command", "hash in hex format", "bf85ed02c52f8aed04e88cca3ce4595000ca10fe7ab5e07fc96f1d005eb6bedc"
+    "Block Height", "Block’s ordinal number in the chain", "non-negative integer", "19"
+    "From", "Transaction sender account ID", "<account_name>@<domain_id>", "admin@test"
+    "To", "EVM address of a contract - the Callee of the original CallEngine command", "20-bytes string in hex representation", "7C370993FD90AF204FD582004E2E54E6A94F2651"
+    "Contract Address", "EVM address of a newly deployed contract", "20-bytes string in hex representation", "7C370993FD90AF204FD582004E2E54E6A94F2651"
+    "Engine Log", "Array of EVM event logs created during smart contract execution. Each log entry is a tuple (Address, [Topic], Data), where Address is the contract caller EVM address, topics are 32-byte strings and Data is an arbitrary length byte array (in hex)", "From Ethereum Yellow Paper: Log entry O ≡ (Oa,(Ot0, Ot1, ...), Od), where Oa ∈ B20 ∧ ∀x ∈ Ot : x ∈ B32 ∧ Od ∈ B", "(577266A3CE7DD267A4C14039416B725786605FF4, [3990DB2D31862302A685E8086B5755072A6E2B5B780AF1EE81ECE35EE3CD3345, 000000000000000000000000969453762B0C739DD285B31635EFA00E24C25628], 0000000000000000000000007203DF5D7B4F198848477D7F9EE080B207E544DD000000000000000000000000000000000000000000000000000000000000006D)"
+
+
+Possible Stateful Validation Errors
+-----------------------------------
+
+.. csv-table::
+    :header: "Code", "Error Name", "Description", "How to solve"
+
+    "2", "No such permissions", "Query’s creator does not have any of the permissions to get the call engine receipt", "Grant the necessary permission"
+    "3", "Invalid signatures", "Signatures of this query did not pass validation", "Add more signatures and make sure query's signatures are a subset of account's signatories"
+
 Get Account
 ^^^^^^^^^^^
 

docs/source/integrations/burrow.rst

@@ -0,0 +1,90 @@
+HL Burrow Integration
+=====================
+
+As Iroha maintainers, we have received many questions and requests for custom smart-contracts support from our users.
+And to provide them more freedom in fulfilling their business needs, we integrated HL Burrow EVM – another great project of the Hyperledger greenhouse, – into Iroha.
+
+.. note:: In the context of Iroha, HL Burrow provides an Ethereum Virtual Machine that can run Solidity smart-contracts.
+	We did our best to provide you with the best user experience possible – and to use it with Iroha, you only need to add a `CMake flag during Iroha build <../build/index.html#cmake-parameters>`_ and it will start working right away.
+
+You can read about Solidity smart-contract language `here <https://solidity.readthedocs.io/>`_, if you are new to this language.
+
+How it works
+------------
+
+For this integration, we have created a special `Call Engine command <../develop/api/commands.html#call-engine>`_ in Iroha, as well as a special `Engine Receipts query <../develop/api/queries.html#engine-receipts>`_ for retrieving the results of the command.
+
+The command
+^^^^^^^^^^^
+
+In the command, you can:
+
+**Сreate a new contract account in EVM**
+
+If the *callee* in the `CallEngine <../develop/api/commands.html#call-engine>`_ is not specified and the *input* parameter contains some bytecode, a new contract account is created.
+
+**Call a method of a previously deployed contract**
+
+If the *callee* is specified, then the input is treated as an ABI-encoded selector of a method of the callee contract followed by the arguments.
+
+.. hint:: It is much like deploying a contract or calling a contract function in Ethereum depending on the contents of the `data` field of the `eth_sendTransaction <https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendtransaction>`_ message call.
+	See `ABI-specification <https://solidity.readthedocs.io/en/v0.6.5/abi-spec.html>`_ for details.
+
+The query
+^^^^^^^^^
+
+To query the outcome of a `CallEngine <../develop/api/commands.html#call-engine>`_ command one should use the `Engine Receipts query <../develop/api/queries.html#engine-receipts>`_.
+The output of any computations inside the EVM will not be available for the caller until it has been written to the ledger (that is, the block that has the respective Iroha transaction has been committed).
+Among the other `data <../develop/api/queries.html#response-structure>`_, the *EngineReceipts* query will return an array of log entries generated in the EVM during the *CallEngine* execution.
+
+.. hint:: A common way for dApps developers to let interested parties see the outcome of a contract execution is to emit an event with some data before exiting a contract function so that this data is written to the *Event Log*.
+	`Ethereum Yellow Paper <https://ethereum.github.io/yellowpaper/paper.pdf>`_ defines a log entry as a 3-tuple containing the emitter’s address, an array of 32-byte long topics and a byte array of some data.
+
+Running Native Iroha Commands in EVM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With HL Burrow integration, you can also use native commands to change the state of Iroha.
+
+The integration mechanism of Burrow EVM empowers Iroha application developers with a tool able to directly act on the Iroha state from smart contracts code thus providing foundation for programmable business logic extensions of the built-in Iroha commands system.
+Conditional asset transfers, transaction fees, non-fungible assets and so on are just a few examples of such extensions.
+The tricky part here is that the Iroha data model is quite different from that of Ethereum.
+For instance, in Ethereum there is only one kind of built-in asset (`Eth`) therefore getting an account balance in EVM context simply means returning the balance property of the account.
+In Iroha, on the other hand, an account can have multiple assets, or not have assets at all, so any function that returns an account balance must take at least one extra argument – the asset ID.
+Same logic applies to transferring/sending assets from account to account.
+
+As a solution to this data model mismatch problem we introduce so-called Service Contracts in Burrow that are “aware” of the Iroha data model and expose an API to interact with Iroha state (query balances, transfer assets and so on).
+From the Burrow EVM perspective such Service Contract is hosted in a Native external VM and is callable via the same interfaces as if it was deployed at some special address in the EVM itself.
+
+.. note:: You can check out `Burrow documentation <https://wiki.hyperledger.org/display/burrow/Burrow+-+The+Boring+Blockchain>`_ for more information on Natives and external dispatchers.
+
+Schematically the interaction between different parts of the system looks as follows:
+
+.. image:: ../../image_assets/burrow/natives.png
+
+Current release of the Iroha EVM wrapper contains a single service contract deployed at the address `A6ABC17819738299B3B2C1CE46D55C74F04E290C` (the last 20 bytes of the *keccak256* hash of the string *ServiceContract*) which exposes 2 methods to query Iroha assets balances and transfer assets between accounts.
+The signatures of these two methods look like this:
+
+	**function** getAssetBalance(string memory *accountID*, string memory *assetID*) public view
+	returns (string memory *result*) {}
+
+	**function** transferAsset(string memory *src*, string memory *dst*, string memory *assetID*,
+	string memory *amount*) public view returns (string memory *result*) {}
+
+.. hint:: From a developer’s perspective calling a function of a native contract is no different from calling a method of any other smart contract provided the address of the latter is known:
+
+	bytes memory payload = abi.encodeWithSignature("getOtherAssetBalance(string,string)", "myacc@test", "coin#test");
+
+	(bool success, bytes memory ret) = address(0xA6ABC17819738299B3B2C1CE46D55C74F04E290C).delegatecall(payload);
+
+Here a special kind of EVM message calls is used - the **delegatecall**, which allows a contract to dynamically load and run code from a different address at runtime in its own execution context.
+
+.. seealso:: Now, let's move to the usage `examples <burrow_example.html>`_
+
+
+
+
+
+
+
+
+