Document _origin.

Reference: Zilliqa/scilla#921
Zilliqa · Dec 16, 2020 · ac99615 · ac99615
1 parent 196be1b
commit ac99615
Show file tree

Hide file tree

Showing 4 changed files with 14 additions and 5 deletions.
diff --git a/docs/source/interface.rst b/docs/source/interface.rst
@@ -212,7 +212,8 @@ Field         Description
 ===========  ===========================================
 ``_tag``      Transition to be invoked
 ``_amount``   Number of QA to be transferred
-``_sender``   Address of the invoker
+``_sender``   Address of the invoker (in a chain call, this is the immediate caller)
+``_origin``   Address from which the transaction originated
 ``params``    An array of parameter objects
 ===========  ===========================================
 
@@ -240,6 +241,7 @@ an example ``input_message.json`` is given below:
         "_tag"    : "SayHello",
         "_amount" : "0",
         "_sender" : "0x1234567890123456789012345678901234567890",
+        "_origin" : "0x1234567890123456789012345678901234567890",
         "params"  : []
     }
 
@@ -259,6 +261,7 @@ an example ``input_message.json`` is given below:
       "_tag"    : "TransferFrom",
       "_amount" : "0",
       "_sender" : "0x64345678901234567890123456789012345678cd",
+      "_origin" : "0x64345678901234567890123456789012345678cd",
       "params"  : [
         {
           "vname" : "from",
@@ -327,6 +330,7 @@ Say that the contract has been deployed at address ``0x1234567890123456789012345
        "_tag": "MoveAction",
        "_amount": "0",
        "_sender" : "0x64345678901234567890123456789012345678cd",
+       "_origin" : "0x64345678901234567890123456789012345678cd",
        "params": [
            {
                "vname" : "dir",

diff --git a/docs/source/scilla-by-example.rst b/docs/source/scilla-by-example.rst
@@ -632,7 +632,7 @@ procedure with the arguments ``True`` and ``0``:
 
 .. note::
 
-    The special parameters ``_sender`` and ``_amount`` are available to
+    The special parameters ``_sender``, ``_origin`` and ``_amount`` are available to
     a procedure even though the procedure is invoked by a transition
     rather than by an incoming message. It is not necessary to pass
     these special parameters as arguments to the procedure.

diff --git a/docs/source/scilla-checker.rst b/docs/source/scilla-checker.rst
@@ -335,7 +335,7 @@ as representing money. Similarly, a local variable used to initialise
 the ``_amount`` field of an outgoing message is also tagged as
 representing money.
 
-Conversely, the message fields ``_sender``, ``_recipient``, and
+Conversely, the message fields ``_sender``, ``_origin``, ``_recipient``, and
 ``_tag``, the event field ``_eventname``, the exception field
 ``_exception``, and the blockchain field ``BLOCKNUMBER``, are known to
 not represent money, so any variable used to initialise those fields

diff --git a/docs/source/scilla-in-depth.rst b/docs/source/scilla-in-depth.rst
@@ -275,7 +275,12 @@ multiple parameters are separated by ``,``.
     - ``_sender : ByStr20`` : The account address that triggered this
       transition. If the transition was called by a contract account
       instead of a user account, then ``_sender`` is the address of
-      the contract that called this transition.
+      the contract that called this transition. In a chain call, this is
+      always the immediate caller.
+
+    - ``_origin : ByStr20`` : The account address that triggered this
+      transaction (which can possibly be a chain call). This is always
+      a non-contract address.
 
     - ``_amount : Uint128`` : Incoming amount, in QA (see section
       above on the units), sent by the sender. To transfer the money
@@ -344,7 +349,7 @@ procedure does not return a result.
 
 .. note::
 
-   The implicit transition parameters ``_sender`` and ``_amount`` are
+   The implicit transition parameters ``_sender``, ``_origin`` and ``_amount`` are
    implicitly passed to all the procedures that a transition
    calls. There is therefore no need to declare those parameters
    explicitly when defining a procedure.