[openapi] rename evmEventParam -> evmAbiParam, add runtime tx fields

[api] add abi parsed fields to runtime tx endpoints [db] add check/comment to runtime_transactions evm_fn_params update descriptions; rename err params->revert_params misc
oasisprotocol · Jan 17, 2024 · 33a72e9 · 33a72e9
1 parent f2dc8d8
commit 33a72e9
Show file tree

Hide file tree

Showing 5 changed files with 61 additions and 23 deletions.
diff --git a/analyzer/runtime/extract.go b/analyzer/runtime/extract.go
@@ -88,7 +88,7 @@ type EventData struct {
 	WithScope        ScopedSdkEvent
 	EvmLogName       string
 	EvmLogSignature  ethCommon.Hash
-	EvmLogParams     []*apiTypes.EvmEventParam
+	EvmLogParams     []*apiTypes.EvmAbiParam
 	RelatedAddresses map[apiTypes.Address]bool
 }
 
@@ -904,7 +904,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 					}
 					eventData.EvmLogName = apiTypes.Erc20Transfer
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "from",
 							EvmType: "address",
@@ -945,7 +945,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 					}
 					eventData.EvmLogName = apiTypes.Erc20Approval
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "owner",
 							EvmType: "address",
@@ -1012,7 +1012,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 					registerNFTTransfer(blockData.PossibleNFTs, eventAddr, tokenID, toZero, toAddr)
 					eventData.EvmLogName = evmabi.ERC721.Events["Transfer"].Name
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "from",
 							EvmType: "address",
@@ -1054,7 +1054,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 					registerNFTExist(blockData.PossibleNFTs, eventAddr, tokenID)
 					eventData.EvmLogName = evmabi.ERC721.Events["Approval"].Name
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "owner",
 							EvmType: "address",
@@ -1095,7 +1095,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 					}
 					eventData.EvmLogName = evmabi.ERC721.Events["ApprovalForAll"].Name
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "owner",
 							EvmType: "address",
@@ -1145,7 +1145,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 
 					eventData.EvmLogName = evmabi.WROSE.Events["Deposit"].Name
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "dst",
 							EvmType: "address",
@@ -1179,7 +1179,7 @@ func extractEvents(blockData *BlockData, relatedAccountAddresses map[apiTypes.Ad
 
 					eventData.EvmLogName = evmabi.WROSE.Events["Withdrawal"].Name
 					eventData.EvmLogSignature = ethCommon.BytesToHash(event.Topics[0])
-					eventData.EvmLogParams = []*apiTypes.EvmEventParam{
+					eventData.EvmLogParams = []*apiTypes.EvmAbiParam{
 						{
 							Name:    "src",
 							EvmType: "address",

diff --git a/api/spec/v1.yaml b/api/spec/v1.yaml
@@ -1524,8 +1524,29 @@ components:
           description: The status code of a failed transaction.
         message:
           type: string
-          description: The message of a failed transaction.
-
+          description: |
+            The message of a failed transaction.
+            This field, like `code` and `module`, can represent an error that originated
+            anywhere in the paratime, i.e. either inside or outside a smart contract.
+
+            A common special case worth calling out: When the paratime is 
+            EVM-compatible (e.g. Emerald or Sapphire) and the error originates 
+            inside a smart contract (using `revert` in solidity), the following 
+            will be true:
+            - `module` will be "evm" and `code` will be 8; see [here](https://github.com/oasisprotocol/oasis-sdk/blob/runtime-sdk/v0.8.3/runtime-sdk/modules/evm/src/lib.rs#L128) for other possible errors in the `evm` module.
+            - `message` will contain the best-effort human-readable revert reason.
+        revert_params:
+          type: array
+          items:
+            $ref: '#/components/schemas/EvmAbiParam'
+          description: |
+            The error parameters, as decoded using the contract abi. Present only when
+            - the error originated from within a smart contract (e.g. via `revert` in Solidity), and 
+            - the contract is verified or the revert reason is a plain String.
+            If this field is present, `message` will include the name of the error, e.g. 'InsufficentBalance'.
+            Note that users should be cautious when evaluating error data since the
+            data origin is not tracked and error information can be faked.
+            
     ConsensusEventType:
       type: string
       enum:
@@ -2247,17 +2268,16 @@ components:
           type: string
           nullable: true
           description: |
-            If the event type is `evm.log`, this field describes the human-readable type of evm event, e.g.
-            `Transfer`. We currently only support two types of evm events, ERC20 `Transfer` and `Approve`.
+            If the event type is `evm.log`, this field describes the human-readable type of 
+            evm event, e.g. `Transfer`. 
             Absent if the event type is not `evm.log`.
           example: 'Transfer'
         evm_log_params:
           type: array
           items:
-            $ref: '#/components/schemas/EvmEventParam'
+            $ref: '#/components/schemas/EvmAbiParam'
           description: |
-            The decoded `evm.log` event data. We currently support only two types of evm events, ERC20 `Transfer`
-            and `Approve`.
+            The decoded `evm.log` event data.
             Absent if the event type is not `evm.log`.
         evm_token:
           $ref: '#/components/schemas/EvmEventToken'
@@ -2278,7 +2298,7 @@ components:
         - evm.log
       example: *runtime_event_type_1
 
-    EvmEventParam:
+    EvmAbiParam:
       type: object
       required: [name, evm_type, value]
       properties:
@@ -2287,11 +2307,11 @@ components:
           description: The parameter name.
         evm_type:
           type: string
-          description: The solidity type of the event parameter.
+          description: The solidity type of the parameter.
         value:
           description: The parameter value.
       description: |
-        A decoded parameter of an event emitted from an EVM runtime.
+        A decoded parameter of an event or error emitted from an EVM runtime.
         Values of EVM type `int128`, `uint128`, `int256`, `uint256`, `fixed`, and `ufixed` are represented as strings.
         Values of EVM type `address` and `address payable` are represented as lowercase hex strings with a "0x" prefix.
         Values of EVM type `bytes` and `bytes<N>` are represented as base64 strings.
@@ -2530,6 +2550,19 @@ components:
           description: |
             Whether this transaction successfully executed.
             Can be absent (meaning "unknown") for confidential runtimes.
+        evm_fn_name:
+          type: string
+          description: |
+            The name of the smart contract function called by the transaction.
+            Only present for `evm.log` transaction calls to contracts that have been verified.
+          example: "acceptTaskResults"
+        evm_fn_params:
+          type: array
+          items:
+            $ref: '#/components/schemas/EvmAbiParam'
+          description: |
+            The decoded parameters with which the smart contract function was called.
+            Only present for `evm.log` transaction calls to contracts that have been verified.
         error:
           $ref: '#/components/schemas/TxError'
           description: Error details of a failed transaction.

diff --git a/storage/client/client.go b/storage/client/client.go
@@ -1247,9 +1247,12 @@ func (c *StorageClient) RuntimeTransactions(ctx context.Context, p apiTypes.GetR
 			&encryptionEnvelope.ResultNonce,
 			&encryptionEnvelope.Result,
 			&t.Success,
+			&t.EvmFnName,
+			&t.EvmFnParams,
 			&t.Error.Module,
 			&t.Error.Code,
 			&t.Error.Message,
+			&t.Error.RevertParams,
 		); err != nil {
 			return nil, wrapError(err)
 		}

diff --git a/storage/client/queries/queries.go b/storage/client/queries/queries.go
@@ -336,9 +336,12 @@ const (
 			txs.evm_encrypted_result_nonce,
 			txs.evm_encrypted_result_data,
 			txs.success,
+			txs.evm_fn_name,
+			txs.evm_fn_params,
 			txs.error_module,
 			txs.error_code,
-			txs.error_message
+			txs.error_message,
+			txs.error_params
 		FROM chain.runtime_transactions AS txs
 		LEFT JOIN chain.runtime_transaction_signers AS signer0 ON
 			(signer0.runtime = txs.runtime) AND

diff --git a/storage/migrations/01_runtimes.up.sql b/storage/migrations/01_runtimes.up.sql
@@ -54,11 +54,10 @@ CREATE TABLE chain.runtime_transactions
   amount      UINT_NUMERIC, -- Exact semantics depend on method. Extracted from body; for convenience only.
 
   -- For evm.Call transactions, we store both the name of the function and
-  -- the function parameters.
+  -- the function parameters. The parameters are stored in an ordered JSON array,
+  -- and each each parameter is a JSON object: {name: ..., evm_type: ..., value: ...}
   evm_fn_name TEXT,
-  -- The function parameter values. Refer to the abi to see the parameter
-  -- names. Note that the parameters may be unnamed.
-  evm_fn_params JSONB,
+  evm_fn_params JSONB CHECK (jsonb_typeof(evm_fn_params)='array'),
 
   -- Encrypted data in encrypted Ethereum-format transactions.
   evm_encrypted_format call_format,