Caliper ethereum documentation needs a complete overhaul

[davidkel]

Following on from #1566 it seems that the documentation for the ethereum connector is difficult to follow for example

URL of the RPC endpoint to connect to. Only websocket is currently supported.
Deployer address with which deploy required contracts
Deployer address private key the private key of the deployer address
Deployer address password to unlock the deployer address
Address from which invoke methods of the benchmark
Private Key the private key of the benchmark address
Password to unlock the benchmark address
Number of confirmation blocks to wait to consider a transaction as successfully accepted in the chain
Contracts configuration

don't match the actual keys to be used even though the links do jump to a section that gives the correct key.

It also provides no detail on how to work with an already deployed contract (which you can skip installing via the --caliper-flow-skip-install when launching caliper. To do this you just need to add the address to the contracts definition within the network config file and you can remove the path information, as follows

{
    "caliper": {
        "blockchain": "ethereum",
    },
    "ethereum": {
        "url": "ws://localhost:8545",
        "contractDeployerAddress": "0xc0A8e4D217eB85b812aeb1226fAb6F588943C2C2",
        "contractDeployerAddressPassword": "password",
        "fromAddress": "0xc0A8e4D217eB85b812aeb1226fAb6F588943C2C2",
        "fromAddressPassword": "password",
        "transactionConfirmationBlocks": 12,
        "contracts": {
            "simple": {
                "address": "0xc24f4561B8F1159E8D8661B282A2974cD48058C2"
                "gas": {
                    "open": 45000,
                    "query": 100000,
                    "transfer": 70000
                }
            }
        }
    }
}

I'm sure there is a lot more that's not good in the documentation here

[rmarede]

I have tested this --caliper-flow-skip-install option in my local besu network and I believe the ethereum connector is not yet prepared to use it. Using this flag on the caliper launch manager command effectively skips the smart contract installation phase, which reflects on the ethereum connector not executing the installSmartContract() function. However, it's in this function that the ethereum connector currently fetches the contract abi (defined in the Contract Definition file), and saves it in memory to later pass as arguments to the workers. Thus, using this flag results in the following error when generating the worker's context: Error: You must provide the json interface of the contract when instantiating a contract object.

[davidkel]

@rmarede In this case as installSmartContract is the only part of the code that uses the contract definition file, the way round it is to put the abi definition directly into the network configuration file ie

{
    "caliper": {
        "blockchain": "ethereum",
    },
    "ethereum": {
        "url": "ws://localhost:8545",
        "contractDeployerAddress": "0xc0A8e4D217eB85b812aeb1226fAb6F588943C2C2",
        "contractDeployerAddressPassword": "password",
        "fromAddress": "0xc0A8e4D217eB85b812aeb1226fAb6F588943C2C2",
        "fromAddressPassword": "password",
        "transactionConfirmationBlocks": 12,
        "contracts": {
            "simple": {
                "address": "0xc24f4561B8F1159E8D8661B282A2974cD48058C2"
                "gas": {
                    "open": 45000,
                    "query": 100000,
                    "transfer": 70000
                },
                "abi": [...]
            }
        }
    }
}

[davidkel]

Also for reference the fromAddressSeed looks like it is mandatory if you want to use more than 1 worker. At least for Besu anyway, not sure about other ethereum based networks

[rmarede]

Some other stuff I believe to be outdated on the ethereum documentation (correct me if I am wrong):

In the transaction data section there's references to the invokeSmartContract and queryState functions which I believe to be deprecated and replaced by the sendRequests function.

In the network config file section it is mentioned that a "special registry contract" should be pre-deployed on the network. I haven't found any information about this registry contract anywhere else, so I wonder if this is some kind of special smart contract native to ethereum networks (which most developers don't need to worry about) or if it's just outdated.

[rmarede]

@davidkel If that's ok I can update the documentation with these topics we've been discussing

[davidkel]

@rmarede Please do. Any improvements to the documention are definitely welcome, many thanks for offering.

[davidkel]

Closing for now as definitely got some improvements to the documentation