From f5d644c611b2fa6ece1006dd20ec3a54254a6287 Mon Sep 17 00:00:00 2001 From: Daniel Perez Date: Thu, 25 Jul 2024 00:17:29 +0100 Subject: [PATCH] Add more documentation --- docs/src/SUMMARY.md | 3 ++ docs/src/account_management.md | 34 ++++++++++++++++++++ docs/src/accounts_management.md | 1 + docs/src/contracts_management.md | 44 ++++++++++++++++++++++++++ docs/src/interacting_with_contracts.md | 29 +++++++++++++++++ 5 files changed, 111 insertions(+) create mode 100644 docs/src/account_management.md create mode 100644 docs/src/accounts_management.md create mode 100644 docs/src/contracts_management.md create mode 100644 docs/src/interacting_with_contracts.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index fd3155f..626c0cd 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -9,6 +9,9 @@ # Guides +- [Account management](./account_management.md) +- [Contracts management](./contracts_management.md) +- [Interacting with contracts](./interacting_with_contracts.md) - [Differences with Solidity](./differences_with_solidity.md) # Reference diff --git a/docs/src/account_management.md b/docs/src/account_management.md new file mode 100644 index 0000000..e63b04d --- /dev/null +++ b/docs/src/account_management.md @@ -0,0 +1,34 @@ +# Account management + +Loading an account is needed to send transactions to smart contract. +Eclair currently supports loading an account using a private key or a Ledger device. + +## Using a private key + +Accounts can be loaded from a private key, using the `repl.loadPrivateKey` function: + +```javascript +>> repl.loadPrivateKey() // usage with no argument +Enter private key: +0xec1a77322592C180Ca626C2f9DDe3976E5712011 +>> repl.loadPrivateKey("4546df48889621143395cf30567352fab50ed9c48149836e726550f1361e43df") // passing the private key as an argument +0xec1a77322592C180Ca626C2f9DDe3976E5712011 +>> repl.account +0xec1a77322592C180Ca626C2f9DDe3976E5712011 +``` + +## Using a ledger + +Accounts can be read from a Ledger device, using the `repl.loadLedger` function. +The `repl.listLedgerWallets()` function can be used to list the available wallets on the Ledger device. +The index of the wallet to load should be passed as an argument to the `repl.loadLedger` function. +Note that only the ledger live derivation is supported for now. + +```javascript +>> repl.listLedgerWallets() +[0x4d09e5617C38F8A9884d79464B7BE1b12353eD05, 0x669F44bB2DFb534707E6FAE940d7558ab0FE254D, 0x5Ac61EbcEbf7De5D19a807752f13Cd7a9Af4Ffc4, 0xb3eBAf4686741C8a7A2Adf7738A1a84a883127c2, 0xC033068376264C0a5971b706894d3fc0eB93A2dD] +>>> repl.loadLedger(1) +0x669F44bB2DFb534707E6FAE940d7558ab0FE254D +>> repl.account +0x669F44bB2DFb534707E6FAE940d7558ab0FE254D +``` diff --git a/docs/src/accounts_management.md b/docs/src/accounts_management.md new file mode 100644 index 0000000..91947ed --- /dev/null +++ b/docs/src/accounts_management.md @@ -0,0 +1 @@ +# Account management diff --git a/docs/src/contracts_management.md b/docs/src/contracts_management.md new file mode 100644 index 0000000..0e6b3c0 --- /dev/null +++ b/docs/src/contracts_management.md @@ -0,0 +1,44 @@ +# Contracts management + +Eclair provides different ways to load contracts (or rather contract ABIs) to be able to interact with them. + +## Loading from existing project + +If `eclair` is ran in a directory using Foundry, Brownie or Hardhat, all the compiled contracts in the project will be loaded automatically. +No additional setup is needed. A list of all loaded contracts can be viewed using `repl.types`. +One caveat is that Eclair does not currently supports multiple contracts with the same name, so last occurrence will overwrite the previous one. + +## Loading from an ABI file + +Contracts can be loaded from a JSON ABI file using the `repl.loadAbi` function. +The first argument is the name of the contract, which will be defined in the environment. +The second argument is the path to the JSON file containing the ABI. + +```javascript +repl.loadAbi("ERC20", "path/to/abi.json") +``` + +If the ABI is nested in the JSON file (e.g. under the `abi` key), the key can be specified as a third argument. + +```javascript +repl.loadAbi("ERC20", "path/to/abi.json", "abi") +``` + +## Fetching ABIs from Etherscan + +Contracts can be loaded from Etherscan using the `repl.fetchAbi` function. +Note that this requires an [Etherscan API key to be set](./configuration.md). +The first argument is, as for `loadAbi` the name of the contract, and the second argument is the address of the contract. + +```javascript +dai = repl.fetchAbi("DAI", 0x6B175474E89094C44Da98b954EedeAC495271d0F) +>> dai +DAI(0x6B175474E89094C44Da98b954EedeAC495271d0F) +``` + +For contracts that use a proxy pattern, the process can be split into two steps. + +```javascript +repl.fetchAbi("USDC", 0x43506849D7C04F9138D1A2050bbF3A0c054402dd); // implementation address +usdc = USDC(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48); // proxy address +``` diff --git a/docs/src/interacting_with_contracts.md b/docs/src/interacting_with_contracts.md new file mode 100644 index 0000000..19e1a0b --- /dev/null +++ b/docs/src/interacting_with_contracts.md @@ -0,0 +1,29 @@ +# Interacting with contracts + +Eclair provides a simple way to interact with smart contracts using familiar Solidity syntax. + +## Calling contracts and sending transactions + +For any contract loaded, all the functions of the contract defined in its ABI are available as methods on the contract object. + +By default, calling a view function will call it and return the result, while calling a non-view function will send a transaction and returns the transaction hash. +Sending a transaction requires an [account to be loaded](./account_management.md). + +The behavior can be changed by using one of the following method on the returned function object: + +* `call`: Call the function and return the result +* `send`: Sends a transaction to the function and return the result +* `encode`: ABI-encodes the function call + +```javascript +>> dai = repl.fetchAbi("DAI", 0x6B175474E89094C44Da98b954EedeAC495271d0F) +>> dai.balanceOf(0x4DEDf26112B3Ec8eC46e7E31EA5e123490B05B8B) +49984400000000000000000000 +>> repl.loadPrivateKey() +>> dai.balanceOf.send(0x4DEDf26112B3Ec8eC46e7E31EA5e123490B05B8B) +Transaction(0x6a2f1b956769d06257475d18ceeec9ee9487d91c97d36346a3cc84d568e36e5c) +>> dai.balanceOf.encode(0x4DEDf26112B3Ec8eC46e7E31EA5e123490B05B8B) +0x70a082310000000000000000000000004dedf26112b3ec8ec46e7e31ea5e123490b05b8b +>> dai.transfer(0x4DEDf26112B3Ec8eC46e7E31EA5e123490B05B8B, 1e18) +Transaction(0xf3e85039345ff864bb216b10e84c7d009e99ec55b370dae22706b0d48ea41583) +```