SVM Receipts Encoding

[YaronWittenstein]

Overview

This SMIP documents the exact binary encoding of Receipts. It'll also include ASCII charts to make it (hopefully) nicer to read.

Goals and motivation

The primary motivation for the SMIP is to give a full spec to be implemented by go-svm. After a transaction has completed, SVM will pass back a blob back (using the svm_byte_array) to go-svm.

In order to enable go-svm to reason about this blob it must know how to decode it properly.

High-level design

SVM has 3 types of Receipts - one for each kind of Transaction:

• Deploy Receipt - A receipt returned after running a Deploy transaction.
• Spawn Receipt - A receipt returned after running a Spawn transaction.
• Call Receipt - A receipt returned after running a Call transaction.

In order to simplify things, each encoded Receipt of a successful transaction starts the same:

• Transaction type - 1 byte
• Version - 2 bytes

Additionally, there is only one encoding Receipt for failed transactions. There was not good reason to keep a different Error encoding for each kind of transaction. So this design also reduces the amount of work for implementing this spec.

Proposed implementation

Here is the current Receipts encoding implementation for SVM v0.3

Successful Deploy Receipt

+-----------------------------------------------------------------------+
|          |             |             |                    |           |
| tx type  |   version   |  is_success | Template `Address` | gas_used  |
| (1 byte) |  (2 bytes)  |  (1 byte)   |     (20 bytes)     | (8 bytes) |
|          |             |             |                    |           |
+-----------------------------------------------------------------------+

• tx type - Should be 0
• is_success - Should be 1
• version - Should be 0
• Template Address - The Address of the new Template
• gas_used - u64 in Big-Endian

Successful Spawn Receipt`

+---------------------------------------------------------+
|           |            |             |                  |
|  tx type  |  version   | is_success  |  Account Address |
| (1 byte)  | (2 bytes)  |  (1 byte)   |    (20 bytes)    |
|           |            |             |                  |
+---------------------------------------------------------+
|              |              |              |            |
|  init State  | returndata   |  returndata  |  gas_used  |
|  (32 bytes)  |  byte-size   |   (Blob)     | (8 bytes)  |
|              |  (2 bytes)   |              |            |
|              |              |              |            |
+---------------------------------------------------------+
|           |          |         |                        |
|  #logs    |  log #1  |  . . .  |       log #N           |
| (1 byte)  |  (Blob)  |         |       (Blob)           |
|           |          |         |                        |
+---------------------------------------------------------+

• tx type - Should be 1
• is_success - Should be 1
• version - Should be 0
• Account Address - The Address of the new Account
• init State - The new Global-State Root Hash
• returndata - The returndata given as a blob
• gas_used - u64 in Big-Endian
• logs - TBD

Successful Call Receipt

 +--------------------------------------------------+
|           |            |            |             |
|  tx type  |  version   | is_success |  new State  |
| (1 byte)  |  (2 bytes) |  (1 byte)  | (32 bytes)  |
|           |            |            |             |
+---------------------------------------------------+
|              |             |                      |
|  returndata  | returndata  |      gas_used        |
|   byte-size  |   (Blob)    |      (8 bytes)       |
|   (2 bytes)  |             |                      |
|              |             |                      |
+---------------------------------------------------+
|           |          |         |                  |
|  #logs    |  log #1  |  . . .  |     log #N       |
| (1 byte)  |  (Blob)  |         |     (Blob)       |
|           |          |         |                  |
+---------------------------------------------------+

• tx type - Should be 2
• is_success - Should be 1
• version - Should be 0
• init State - The new Global-State Root Hash
• returndata - The returndata given as a blob
• gas_used - u64 in Big-Endian
• logs - TBD

Failed Transaction Receipts

+-------------------------------------------------------+
|          |              |             |               |
|  tx type |   version    |  is_success |  error code   |
| (1 byte) |  (2 bytes)   |   (1 byte)  |   (1 byte)    |
|          |              |             |               |  
+-------------------------------------------------------+
|          |          |         |            |          |
|  #logs   |  log #1  |  . . .  |  log #N-1  |  log #N  |
| (1 byte) |          |         |            |          |
|          |          |         |            |          |
+-------------------------------------------------------+
|                                                       |
|                     Error Blob                        |
|                                                       |
+-------------------------------------------------------+

• tx type - The transaction type
• is_success - Should be 0
• version - Should be 0
• error code - The erorr code
• logs - TBD
• Error blob - see Error Blob section below.

Error Blob

The Error Blob is determined by the error code field.

Important:

Each Error Message Field is truncated to fit into at most 255 bytes. In such a case the Message might not make a valid UTF-String.

OOG (Out-of-Gas)

Error Blob is empty

Template Not Found

+---------------------+
|  Template Address   |
|     (20 bytes)      |
+---------------------+

Account Not Found

+---------------------+
|   Account Address   |
|     (20 bytes)      |
+---------------------+

Compilation Failed

+-------------------+-----------------+-----------------+
|  Template Address | Account Address |     Message     |
|   (20 bytes)      |  (20 bytes)     |  (UTF-8 String) |
+-------------------+-----------------+-----------------+

Instantiation Failed

+-------------------+-----------------+-----------------+
|  Template Address | Account Address |     Message     |
|   (20 bytes)      |  (20 bytes)     |  (UTF-8 String) |
+-------------------+-----------------+-----------------+

Function Not Found

+-------------------+-----------------+--------------+
|  Template Address | Account Address |   Function   |
|   (20 bytes)      |  (20 bytes)     |   (String)   |
+-------------------+-----------------+--------------+

Function Failed

+-------------------+------------------+------------+----------------+
|  Template Address |  Account Address |  Function  |    Message     |
|   (20 bytes)      |   (20 bytes)     |  (String)  | (UTF-8 String) |
+-------------------+------------------+------------+----------------+

Function Not Allowed

+-------------------+-------------------+------------+----------------+
|  Template Address |  Account Address  |  Function  |    Message     |
|   (20 bytes       |   (20 bytes)      |  (String)  | (UTF-8 String) |
+-------------------+-------------------+------------+----------------+

Function Invalid Signature

+-------------------+-------------------+------------+
|  Template Address |  Account Address  |  Function  |     
|   (20 bytes)      |   (20 bytes)      |  (String)  |
+-------------------+-------------------+------------+

Questions/concerns

• Are there any other fields we'd like to be become a part of the Receipts? It can even be a field given in the Transactions or something related to the Context (layer for example) of the running transaction.

• There is an existing implementation under svm-codec that transforms each Receipt into a JSON form. So svm_codec WASM API can be easily extended to expose that functionality as well. We'll revist this topic when the Node API (gRPC) will be implemented for v0.3

Dependencies and interactions

As described above, since the communication between go-svm and SVM is by passing blobs - this spec should be implemented by go-svm.

Any non-Rust client that we'd like to integrate with SVM will have go through the FFI layer and implement this SMIP spec.

Stakeholders and reviewers

@YaronWittenstein @neysofu @sudachen @noamnelke @lrettig @avive

[neysofu]

This SMIP is partially outdated due to replacing our custom encoding with SSZ. Also, the new transaction syntax redefines deploy transactions as call's, effectively removing the need to have a custom encoding for them. Similarly, spawn receipts will most likely be replaced with self-spawn receipts due to transaction types unification. See also https://github.com/spacemeshos/pm/issues/108.