Search documentation of Cartouche

# Cartouche.Trace (Cartouche v0.1.3)

Copy Markdown View Source

Represents an Ethereum transaction trace, which contains information about the call graph of an executed transaction.

See `Cartouche.RPC.trace_transaction` for getting traces from an Ethereum JSON-RPC host.

See also:

- Alchemy docs: https://docs.alchemy.com/reference/trace-transaction
- Infura docs: https://docs.infura.io/networks/ethereum/json-rpc-methods/trace-methods/trace_transaction
- Infura trace object: https://docs.infura.io/networks/ethereum/json-rpc-methods/trace-methods/#trace

## Summary

### Types

t()

### Functions

deserialize(params)

Deserializes a single trace result from `trace_transction`. Note: a JSON-RPC response will return an array of such traces.

deserialize_many(traces)

Deserializes an array of trace results from `trace_transction`.

serialize(trace)

Serializes a single trace to a corresponding json map.

## Types

# t()

    @type t() :: %Cartouche.Trace{
      action: Cartouche.Trace.Action.t(),
      block_hash: <<_::256>>,
      block_number: integer(),
      error: String.t() | nil,
      gas_used: integer(),
      output: binary() | nil,
      result_address: <<_::160>> | nil,
      result_code: binary() | nil,
      subtraces: integer(),
      trace_address: [<<_::160>> | integer()],
      transaction_hash: <<_::256>>,
      transaction_position: integer(),
      type: String.t()
    }

## Functions

# deserialize(params)

    @spec deserialize(map()) :: t() | no_return()

Deserializes a single trace result from `trace_transction`. Note: a JSON-RPC response will return an array of such traces.

## Examples

    iex> use Cartouche.Hex
    iex> %{
    ...>   "action" => %{
    ...>     "callType" => "call",
    ...>     "from" => "0x83806d539d4ea1c140489a06660319c9a303f874",
    ...>     "gas" => "0x1a1f8",
    ...>     "input" => "0x",
    ...>     "to" => "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
    ...>     "value" => "0x7a16c911b4d00000"
    ...>   },
    ...>   "blockHash" => "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
    ...>   "blockNumber" => 3068185,
    ...>   "result" => %{
    ...>     "gasUsed" => "0x2982",
    ...>     "output" => "0x"
    ...>   },
    ...>   "subtraces" => 2,
    ...>   "traceAddress" => ["0x1c39ba39e4735cb65978d4db400ddd70a72dc750"],
    ...>   "transactionHash" => "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
    ...>   "transactionPosition" => 2,
    ...>   "type" => "call"
    ...> }
    ...> |> Cartouche.Trace.deserialize()
    %Cartouche.Trace{
      action: %Cartouche.Trace.Action{
        call_type: "call",
        from: ~h[0x83806d539d4ea1c140489a06660319c9a303f874],
        gas: 0x01a1f8,
        input: <<>>,
        to: ~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750],
        value: 0x7a16c911b4d00000,
      },
      block_hash: ~h[0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add],
      block_number: 3068185,
      gas_used: 0x2982,
      output: <<>>,
      subtraces: 2,
      trace_address: [~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750]],
      transaction_hash: ~h[0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3],
      transaction_position: 2,
      type: "call"
    }

    iex> use Cartouche.Hex
    iex> %{
    ...>   "action" => %{
    ...>     "from" => "0x9d8ec03e9ddb71f04da9db1e38837aaac1782a97",
    ...>     "gas" => "0x4ad07",
    ...>     "init" =>
    ...>       " ",
    ...>     "value" => "0x0"
    ...>   },
    ...>   "blockHash" => "0x151ccedeab15a443b3c45719ff00404d9b1d431454e6f63c845b22c46c9d25e2",
    ...>   "blockNumber" => 10_493_512,
    ...>   "result" => %{
    ...>     "address" => "0x107eed62216e0f83218858cef6830d1b17ad6bc3",
    ...>     "code" =>
    ...>       " ",
    ...>     "gasUsed" => "0xebe8"
    ...>   },
    ...>   "subtraces" => 0,
    ...>   "traceAddress" => [0],
    ...>   "transactionHash" => "0xd2cb84e759a8882f8c3de29b673f6a602e0cae7f37a440b957526ef76eb05303",
    ...>   "transactionPosition" => 0,
    ...>   "type" => "create"
    ...> }
    ...> |> Cartouche.Trace.deserialize()
    %Cartouche.Trace{
      action: %Cartouche.Trace.Action{
        call_type: nil,
        init: ~h[ ],
        from: ~h[0x9d8ec03e9ddb71f04da9db1e38837aaac1782a97],
        gas: 306439,
        input: nil,
        to: nil,
        value: 0
      },
      block_hash: ~h[0x151ccedeab15a443b3c45719ff00404d9b1d431454e6f63c845b22c46c9d25e2],
      block_number: 10493512,
      gas_used: 60392,
      output: nil,
      result_address: ~h[0x107eed62216e0f83218858cef6830d1b17ad6bc3],
      result_code: ~h[ ],
      subtraces: 0,
      trace_address: [0],
      transaction_hash: ~h[0xd2cb84e759a8882f8c3de29b673f6a602e0cae7f37a440b957526ef76eb05303],
      transaction_position: 0,
      type: "create"
    }

    iex> use Cartouche.Hex
    iex> %{
    ...>   "action" => %{
    ...>     "callType" => "call",
    ...>     "from" => "0x9d8ec03e9ddb71f04da9db1e38837aaac1782a97",
    ...>     "gas" => "0x3b933",
    ...>     "input" =>
    ...>       " ",
    ...>     "to" => "0x107eed62216e0f83218858cef6830d1b17ad6bc3",
    ...>     "value" => "0x0"
    ...>   },
    ...>   "blockHash" => "0x151ccedeab15a443b3c45719ff00404d9b1d431454e6f63c845b22c46c9d25e2",
    ...>   "blockNumber" => 10_493_512,
    ...>   "error" => "Reverted",
    ...>   "result" => %{"gasUsed" => "0x1bfa6", "output" => "0x01020304"},
    ...>   "subtraces" => 1,
    ...>   "traceAddress" => [1],
    ...>   "transactionHash" => "0xd2cb84e759a8882f8c3de29b673f6a602e0cae7f37a440b957526ef76eb05303",
    ...>   "transactionPosition" => 0,
    ...>   "type" => "call"
    ...> }
    ...> |> Cartouche.Trace.deserialize()
    %Cartouche.Trace{
      action: %Cartouche.Trace.Action{
        call_type: "call",
        from: ~h[0x9d8ec03e9ddb71f04da9db1e38837aaac1782a97],
        gas: 0x3b933,
        input: ~h[ ],
        to: ~h[0x107eed62216e0f83218858cef6830d1b17ad6bc3],
        value: 0x0,
      },
      block_hash: ~h[0x151ccedeab15a443b3c45719ff00404d9b1d431454e6f63c845b22c46c9d25e2],
      block_number: 10_493_512,
      gas_used: 0x1bfa6,
      error: "Reverted",
      output: ~h[0x01020304],
      subtraces: 1,
      trace_address: [1],
      transaction_hash: ~h[0xd2cb84e759a8882f8c3de29b673f6a602e0cae7f37a440b957526ef76eb05303],
      transaction_position: 0,
      type: "call"
    }

    iex> use Cartouche.Hex
    iex> %{
    ...>   "action" => %{
    ...>     "callType" => "call",
    ...>     "from" => "0x0000000000000000000000000000000000000000",
    ...>     "gas" => "0x1dcd0f58",
    ...>     "input" =>
    ...>       "0xd1692f56000000000000000000000000142da9114e5a98e015aa95afca0585e84832a612000000000000000000000000142da9114e5a98e015aa95afca0585e84832a6120000000000000000000000000000000000000000000000000000000000000000",
    ...>     "to" => "0x13172ee393713fba9925a9a752341ebd31e8d9a7",
    ...>     "value" => "0x0"
    ...>   },
    ...>   "error" => "Reverted",
    ...>   "result" => %{"gasUsed" => "0x1d55dd47", "output" => "0x"},
    ...>   "subtraces" => 1,
    ...>   "traceAddress" => [],
    ...>   "type" => "call"
    ...> }
    ...> |> Cartouche.Trace.deserialize()
    %Cartouche.Trace{
      action: %Cartouche.Trace.Action{
        call_type: "call",
        from: ~h[0x0000000000000000000000000000000000000000],
        gas: 0x1dcd0f58,
        input: ~h[0xd1692f56000000000000000000000000142da9114e5a98e015aa95afca0585e84832a612000000000000000000000000142da9114e5a98e015aa95afca0585e84832a6120000000000000000000000000000000000000000000000000000000000000000],
        to: ~h[0x13172ee393713fba9925a9a752341ebd31e8d9a7],
        value: 0x0,
      },
      block_hash: nil,
      block_number: nil,
      gas_used: 0x1d55dd47,
      error: "Reverted",
      output: <<>>,
      subtraces: 1,
      trace_address: [],
      transaction_hash: nil,
      type: "call"
    }

    iex> use Cartouche.Hex
    iex> %{
    ...>   "action" => %{
    ...>     "from" => "0x13172ee393713fba9925a9a752341ebd31e8d9a7",
    ...>     "gas" => "0x1d555c99",
    ...>     "init" =>
    ...>       " ",
    ...>     "value" => "0x0"
    ...>   },
    ...>   "error" => "contract address collision",
    ...>   "result" => nil,
    ...>   "subtraces" => 0,
    ...>   "traceAddress" => [0],
    ...>   "type" => "create"
    ...> }
    ...> |> Cartouche.Trace.deserialize()
    %Cartouche.Trace{
      action: %Cartouche.Trace.Action{
        from: ~h[0x13172ee393713fba9925a9a752341ebd31e8d9a7],
        gas: 0x1d555c99,
        init: ~h[ ],
        value: 0x0,
      },
      error: "contract address collision",
      subtraces: 0,
      trace_address: [0],
      type: "create"
    }

# deserialize_many(traces)

    @spec deserialize_many([map()]) :: [t()] | no_return()

Deserializes an array of trace results from `trace_transction`.

## Examples

    iex> use Cartouche.Hex
    iex> [%{
    ...>   "action" => %{
    ...>     "callType" => "call",
    ...>     "from" => "0x83806d539d4ea1c140489a06660319c9a303f874",
    ...>     "gas" => "0x1a1f8",
    ...>     "input" => "0x",
    ...>     "to" => "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
    ...>     "value" => "0x7a16c911b4d00000"
    ...>   },
    ...>   "blockHash" => "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
    ...>   "blockNumber" => 3068185,
    ...>   "result" => %{
    ...>     "gasUsed" => "0x2982",
    ...>     "output" => "0x"
    ...>   },
    ...>   "subtraces" => 2,
    ...>   "traceAddress" => ["0x1c39ba39e4735cb65978d4db400ddd70a72dc750"],
    ...>   "transactionHash" => "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
    ...>   "transactionPosition" => 2,
    ...>   "type" => "call"
    ...> }]
    ...> |> Cartouche.Trace.deserialize_many()
    [
      %Cartouche.Trace{
        action: %Cartouche.Trace.Action{
          call_type: "call",
          from: ~h[0x83806d539d4ea1c140489a06660319c9a303f874],
          gas: 0x01a1f8,
          input: <<>>,
          to: ~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750],
          value: 0x7a16c911b4d00000,
        },
        block_hash: ~h[0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add],
        block_number: 3068185,
        gas_used: 0x2982,
        output: <<>>,
        subtraces: 2,
        trace_address: [~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750]],
        transaction_hash: ~h[0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3],
        transaction_position: 2,
        type: "call"
      }
    ]

# serialize(trace)

    @spec serialize(t()) :: map()

Serializes a single trace to a corresponding json map.

## Examples

    iex> use Cartouche.Hex
    iex> %Cartouche.Trace{
    ...>   action: %Cartouche.Trace.Action{
    ...>     call_type: "call",
    ...>     from: ~h[0x83806d539d4ea1c140489a06660319c9a303f874],
    ...>     gas: 0x01a1f8,
    ...>     input: <<>>,
    ...>     to: ~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750],
    ...>     value: 0x7a16c911b4d00000,
    ...>   },
    ...>   block_hash: ~h[0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add],
    ...>   block_number: 3068185,
    ...>   gas_used: 0x2982,
    ...>   output: <<>>,
    ...>   subtraces: 2,
    ...>   trace_address: [~h[0x1c39ba39e4735cb65978d4db400ddd70a72dc750]],
    ...>   transaction_hash: ~h[0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3],
    ...>   transaction_position: 2,
    ...>   type: "call"
    ...> }
    ...> |> Cartouche.Trace.serialize()
    %{
      action: %{
        callType: "call",
        from: "0x83806d539D4Ea1c140489A06660319C9A303f874",
        gas: "0x1A1F8",
        input: "0x",
        to: "0x1C39BA39e4735CB65978d4Db400dDD70a72DC750",
        value: "0x7A16C911B4D00000",
        init: nil
      },
      blockHash: "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
      blockNumber: "0x2ED119",
      error: nil,
      result: %{
        gasUsed: "0x2982",
        code: nil,
        address: nil,
        output: "0x"
      },
      subtraces: 2,
      traceAddress: ["0x1C39BA39e4735CB65978d4Db400dDD70a72DC750"],
      transactionHash: "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
      transactionPosition: 2,
      type: "call"
    }