How to ensure all the deposits to exchange accounts are reflected properly?

Accounts, including exchange accounts, can receive funds in two ways: an “external”, or “top-level” transfer (eg. if f1XXX sends a message to f1ZZZ that transfers 1 FIL), and “internal” transfers” that result from a subinvocation. An example of “internal” transfers in Filecoin today is our multisig support: f1XXX could send a top-level message to a multisig f2YYY, which then transfers 1 FIL to f1ZZZ as a result.

If you already support multisig f2 transactions on Filecoin, then there should be no change for you. However, if this sounds unfamiliar, please keep reading 😉

With the introduction of Eth accounts and user actors, exchanges can expect funds (FIL) to be transferred from some user actors (smart contracts) to exchange accounts. The actor-to-actor calls may also trigger the funds’ transfer.

• Therefore, expand to see the recommended way to ensure exchanges capture ALL the funds deposited to the exchange accounts, from any Filecoin account type.

  • ❗Before starting your lotus node, make sure to set env var export LOTUS_VM_ENABLE_TRACING=1 to get all the execution trace with Subcall details, so as to get ALL value transfer details not only from the message itself but any internal actor-to-actor calls.

  • Get all the messages(CIDs) as you do today.

  • Call StateCompute on each tipsets, which returns all the message details in that tipsets, including Subcalls (internal actor-to-actor invocations), in the execution trace (expand to see examples).

    • StateCompute

      curl -X POST \\
          -H "Content-Type: application/json" \\
          --data '{ "jsonrpc": "2.0", "method":"Filecoin.StateCompute", "params": [92147, [], [{"/": "bafy2bzaceddyanp7mtdmva3fa2w4t3jnsugvp57ye3fveupfp2v2ytzp4wiji"}]], "id": 0
          }' \\
          '<http://127.0.0.1:8080/rpc/v0>'
      

      where

      • 92147 is the tipset epoch/height
      • bafy2bzaceddyanp7mtdmva3fa2w4t3jnsugvp57ye3fveupfp2v2ytzp4wiji is the TipsetKey

  • Make the deposit/reflect on the account balance for any trace that shows the ExitCode == 0(successful tx) && Value ≠ 0 && To address is an exchange account. (expand to see more instructions)

    Sample output for a StateCompute

    statecomputeputput.json

    Message CID bafy2bzaceamuucesbpmdh63v2z5qtob2zcrq4lrshvyltiukollwjlhasxqmcbafy2bzaceamuucesbpmdh63v2z5qtob2zcrq4lrshvyltiukollwjlhasxqmc , where you can see that the ExitCode = 0, which means the message was successful. The Value is 0 means no deposit is needed.

    "MsgCid": {
              "/": "bafy2bzaceamuucesbpmdh63v2z5qtob2zcrq4lrshvyltiukollwjlhasxqmc"
            },
            "Msg": {
              "Version": 0,
              "To": "t01129",
              "From": "t3r3nqkq7ybn2ozj4lvvpdwayyy3b5v6l7gnrgg7yd5d42ti65qfaamvdphnqscek3ruoo7rnulixbsyh52tla",
              "Nonce": 9048,
              "Value": "0",
              "GasLimit": 42467353,
              "GasFeeCap": "100509",
              "GasPremium": "99455",
              "Method": 16,
              "Params": "gUoAAx6qpQO79S9j",
              "CID": {
                "/": "bafy2bzaceamuucesbpmdh63v2z5qtob2zcrq4lrshvyltiukollwjlhasxqmc"
              }
            },
            "MsgRct": {
              "ExitCode": 0,
              "Return": "SgADHqqlA7v1L2M=",
              "GasUsed": 34040183,
              "EventsRoot": null
            },
    

    The message includes multiple Subcalls, as expected the ExitCode is also 0 given the tx was successful, and the first subcall includes a tx From t01129 To t01073 with Value = 57549992223764197219. Say t01073 is an exchange account, then 57549992223764197219attoFil is deposited to this exchange account, and the exchange account balance should reflect this deposit.

    "Subcalls": [
                {
                  "Msg": {
                    "Version": 0,
                    "To": "t01073",
                    "From": "t01129",
                    "Nonce": 0,
                    "Value": "57549992223764197219",
                    "GasLimit": 0,
                    "GasFeeCap": "0",
                    "GasPremium": "0",
                    "Method": 0,
                    "Params": null,
                    "CID": {
                      "/": "bafy2bzacec3ya3bceclisbn7gqqpu42imn4f5epthq2kwkopl4cdplrdh434m"
                    }
                  },
                  "MsgRct": {
                    "ExitCode": 0,
                    "Return": null,
                    "GasUsed": 0,
                    "EventsRoot": null
                  },
                  "Error": "",
                  "Duration": 0,
                  "GasCharges": [
                    {
                      "Name": "OnValueTransfer",
                      "loc": null,
                      "tg": 6000,
                      "cg": 6000,
                      "sg": 0,
                      "vtg": 0,
                      "vcg": 0,
                      "vsg": 0,
                      "tt": 0
                    }
                  ],
               ...
    

  • *As you noticed in the above example, f0 id addresses are used in the Subcalls. To get the id address of any exchange accounts (if you don't store them already), call StateLookupRobustAddress (expand to see an example)

    curl -X POST \\
        -H "Content-Type: application/json" \\
        --data '{ "jsonrpc": "2.0", "method":"Filecoin.StateLookupRobustAddress", "params": ["t01129", null], "id": 0
        }' \\
        '<http://127.0.0.1:8080/rpc/v1>'
    {"jsonrpc":"2.0","result":"t2faszykfxoksf6odwrizh5m5enw6y3hlnyvqmdmi","id":0}
    

New builtin actors: EthAccount, EVM, and Placeholder

Some of the exchanges are filtering transactions according to the actor code CIDs. In this upgrade, we will introduce three new actors (all under f410 address class): EthAccount, EVM, and Placeholder. Their actor CIDs will be documented in the lotus v1.20.0 release note, or you can find it here in the final release.