Merge pull request #1343 from poanetwork/1342

Document Explorer.Chain.SmartContract

apps/explorer/lib/explorer/chain/address.ex

@@ -22,7 +22,9 @@ defmodule Explorer.Chain.Address do
    * `fetched_coin_balance_block_number` - the `t:Explorer.Chain.Block.t/0` `t:Explorer.Chain.Block.block_number/0` for
      which `fetched_coin_balance` was fetched
    * `hash` - the hash of the address's public key
-   * `contract_code` - the code of the contract when an Address is a contract
+   * `contract_code` - the binary code of the contract when an Address is a contract.  The human-readable
+     Solidity source code is in `smart_contract` `t:Explorer.Chain.SmartContract.t/0` `contract_source_code` *if* the
+    contract has been verified
    * `names` - names known for the address
    * `inserted_at` - when this address was inserted
    * `updated_at` when this address was last updated

apps/explorer/lib/explorer/chain/smart_contract.ex

@@ -12,12 +12,189 @@ defmodule Explorer.Chain.SmartContract do
 
   use Explorer.Schema
 
+  @typedoc """
+  The name of a parameter to a function or event.
+  """
+  @type parameter_name :: String.t()
+
+  @typedoc """
+  Canonical Input or output [type](https://solidity.readthedocs.io/en/develop/abi-spec.html#types).
+
+  * `"address"` - equivalent to `uint160`, except for the assumed interpretation and language typing. For computing the
+    function selector, `address` is used.
+  * `"bool"` - equivalent to uint8 restricted to the values 0 and 1. For computing the function selector, bool is used.
+  * `bytes`: dynamic sized byte sequence
+  * `"bytes<M>"` - binary type of `M` bytes, `0 < M <= 32`.
+  * `"fixed"` - synonym for `"fixed128x18".  For computing the function selection, `"fixed128x8"` has to be used.
+  * `"fixed<M>x<N>"` - signed fixed-point decimal number of `M` bits, `8 <= M <= 256`, `M % 8 ==0`, and `0 < N <= 80`,
+    which denotes the value `v` as `v / (10 ** N)`.
+  * `"function" - an address (`20` bytes) followed by a function selector (`4` bytes). Encoded identical to `bytes24`.
+  * `"int"` - synonym for `"int256"`. For computing the function selector `"int256"` has to be used.
+  * `"int<M>"` - two’s complement signed integer type of `M` bits, `0 < M <= 256`, `M % 8 == 0`.
+  * `"string"` - dynamic sized unicode string assumed to be UTF-8 encoded.
+  * `"tuple"` - a tuple.
+  * `"(<T1>,<T2>,...,<Tn>)"` - tuple consisting of the `t:type/0`s `<T1>`, …, `Tn`, `n >= 0`.
+  * `"<type>[]"` - a variable-length array of elements of the given `type`.
+  * `"<type>[M]"` - a fixed-length array of `M` elements, `M >= 0`, of the given `t:type/0`.
+  * `"ufixed"` - synonym for `"ufixed128x18".  For computing the function selection, `"ufixed128x8"` has to be used.
+  * `"ufixed<M>x<N>"` - unsigned variant of `"fixed<M>x<N>"`
+  * `"uint"` - synonym for `"uint256"`. For computing the function selector `"uint256"` has to be used.
+  * `"uint<M>"` - unsigned integer type of `M` bits, `0 < M <= 256`, `M % 8 == 0.` e.g. `uint32`, `uint8`, `uint256`.
+  """
+  @type type :: String.t()
+
+  @typedoc """
+  Name of component.
+  """
+  @type component_name :: String.t()
+
+  @typedoc """
+  A component of a [tuple](https://solidity.readthedocs.io/en/develop/abi-spec.html#handling-tuple-types).
+
+  * `"name"` - name of the component.
+  * `"type"` - `t:type/0`.
+  """
+  @type component :: %{String.t() => component_name() | type()}
+
+  @typedoc """
+  The components of a [tuple](https://solidity.readthedocs.io/en/develop/abi-spec.html#handling-tuple-types).
+  """
+  @type components :: [component()]
+
+  @typedoc """
+  * `"event"`
+  """
+  @type event_type :: String.t()
+
+  @typedoc """
+  Name of an event in an `t:abi/0`.
+  """
+  @type event_name :: String.t()
+
+  @typedoc """
+  * `true` - if field is part of the `t:Explorer.Chain.Log.t/0` `topics`.
+  * `false` - if field is part of the `t:Explorer.Chain.Log.t/0` `data`.
+  """
+  @type indexed :: boolean()
+
+  @typedoc """
+  * `"name"` - `t:parameter_name/0`.
+  * `"type"` - `t:type/0`.
+  * `"components" `- `t:components/0` used when `"type"` is a tuple type.
+  * `"indexed"` - `t:indexed/0`.
+  """
+  @type event_input :: %{String.t() => parameter_name() | type() | components() | indexed()}
+
+  @typedoc """
+  * `true` - event was declared as `anonymous`.
+  * `false` - otherwise.
+  """
+  @type anonymous :: boolean()
+
+  @typedoc """
+  * `"type" - `t:event_type/0`
+  * `"name"` - `t:event_name/0`
+  * `"inputs"` - `t:list/0` of `t:event_input/0`.
+  * `"anonymous"` - t:anonymous/0`
+  """
+  @type event_description :: %{String.t() => term()}
+
+  @typedoc """
+  * `"function"`
+  * `"constructor"`
+  * `"fallback"` - the default, unnamed function
+  """
+  @type function_type :: String.t()
+
+  @typedoc """
+  Name of a function in an `t:abi/0`.
+  """
+  @type function_name :: String.t()
+
+  @typedoc """
+  * `"name"` - t:parameter_name/0`.
+  * `"type"` - `t:type/0`.
+  * `"components"` - `t:components/0` used when `"type"` is a tuple type.
+  """
+  @type function_input :: %{String.t() => parameter_name() | type() | components()}
+
+  @typedoc """
+  * `"type" - `t:type/0`
+  """
+  @type function_output :: %{String.t() => type()}
+
+  @typedoc """
+  * `"pure"` - [specified to not read blockchain state](https://solidity.readthedocs.io/en/develop/contracts.html#pure-functions).
+  * `"view"` - [specified to not modify the blockchain state](https://solidity.readthedocs.io/en/develop/contracts.html#view-functions).
+  * `"nonpayable"` - function does not accept Ether.
+    **NOTE**: Sending non-zero Ether to non-payable function will revert the transaction.
+  * `"payable"` - function accepts Ether.
+  """
+  @type state_mutability :: String.t()
+
+  @typedoc """
+  **Deprecated:** Use `t:function_description/0` `"stateMutability"`:
+
+  * `true` - `"payable"`
+  * `false` - `"pure"`, `"view"`, or `"nonpayable"`.
+  """
+  @type payable :: boolean()
+
+  @typedoc """
+  **Deprecated:** Use `t:function_description/0` `"stateMutability"`:
+
+  * `true` - `"pure"` or `"view"`.
+  * `false` - `"nonpayable"` or `"payable"`.
+  """
+  @type constant :: boolean()
+
+  @typedoc """
+  The [function description](https://solidity.readthedocs.io/en/develop/abi-spec.html#json) for a function in the
+  `t:abi.t/0`.
+
+  * `"type"` - `t:function_type/0`
+  * `"name" - `t:function_name/0`
+  * `"inputs` - `t:list/0` of `t:function_input/0`.
+  * `"outputs" - `t:list/0` of `t:output/0`.
+  * `"stateMutability"` - `t:state_mutability/0`
+  * `"payable"` - `t:payable/0`.
+    **WARNING:** Deprecated and will be removed in the future.  Use `"stateMutability"` instead.
+  * `"constant"` - `t:constant/0`.
+    **WARNING:** Deprecated and will be removed in the future.  Use `"stateMutability"` instead.
+  """
+  @type function_description :: %{
+          String.t() =>
+            function_type()
+            | function_name()
+            | [function_input()]
+            | [function_output()]
+            | state_mutability()
+            | payable()
+            | constant()
+        }
+
+  @typedoc """
+  The [JSON ABI specification](https://solidity.readthedocs.io/en/develop/abi-spec.html#json) for a contract.
+  """
+  @type abi :: [event_description | function_description]
+
+  @typedoc """
+  * `name` - the human-readable name of the smart contract.
+  * `compiler_version` - the version of the Solidity compiler used to compile `contract_source_code` with `optimization`
+    into `address` `t:Explorer.Chain.Address.t/0` `contract_code`.
+  * `optimization` - whether optimizations were turned on when compiling `contract_source_code` into `address`
+    `t:Explorer.Chain.Address.t/0` `contract_code`.
+  * `contract_source_code` - the Solidity source code that was compiled by `compiler_version` with `optimization` to
+    produce `address` `t:Explorer.Chain.Address.t/0` `contract_code`.
+  * `abi` - The [JSON ABI specification](https://solidity.readthedocs.io/en/develop/abi-spec.html#json) for this
+    contract.
+  """
   @type t :: %Explorer.Chain.SmartContract{
           name: String.t(),
           compiler_version: String.t(),
           optimization: boolean,
           contract_source_code: String.t(),
-          abi: {:array, :map}
+          abi: [function_description]
         }
 
   schema "smart_contracts" do