{"analyzedAt":"2022-12-14T18:24:47.938Z","collected":{"metadata":{"name":"@axelar-network/axelar-local-dev","scope":"axelar-network","version":"1.2.3","description":"This environment allows you to set up a local instances of the Axelar Gateways, instantiate your application-level executor contracts on the source/destination chains, and simulate message relaying between them.","date":"2022-12-14T09:26:37.176Z","publisher":{"username":"nptytn","email":"nptytn2@gmail.com"},"maintainers":[{"username":"kiryl-axelar","email":"kiryl@axelar.network"},{"username":"eng_axelar","email":"eng@axelar.network"},{"username":"vlad-axelar","email":"vladimir@axelar.network"},{"username":"nptytn","email":"nptytn2@gmail.com"},{"username":"photomorph","email":"christian@axelar.network"},{"username":"canhtrinh","email":"canh.coding@gmail.com"}],"repository":{"type":"git","url":"git+https://github.com/axelarnetwork/axelar-local-dev.git"},"links":{"npm":"https://www.npmjs.com/package/%40axelar-network%2Faxelar-local-dev","homepage":"https://github.com/axelarnetwork/axelar-local-dev#readme","repository":"https://github.com/axelarnetwork/axelar-local-dev","bugs":"https://github.com/axelarnetwork/axelar-local-dev/issues"},"license":"ISC","dependencies":{"@axelar-network/axelar-cgp-aptos":"^1.0.2","@axelar-network/axelar-cgp-solidity":"^4.3.0","@axelar-network/axelar-gmp-sdk-solidity":"^1.1.0","aptos":"^1.3.16","ethers":"^5.6.5","fs-extra":"^10.1.0","ganache":"^7.1.0","lodash":"^4.17.21","npm-run-all":"^4.1.5"},"devDependencies":{"@babel/eslint-parser":"^7.19.1","@babel/preset-typescript":"^7.18.6","@types/fs-extra":"^9.0.13","@types/jest":"^29.2.1","@types/lodash":"^4.14.186","@types/mocha":"^10.0.0","@types/node":"^18.7.13","@typescript-eslint/eslint-plugin":"^5.41.0","@typescript-eslint/parser":"^5.41.0","chai":"^4.3.6","eslint":"^8.17.0","eslint-config-richardpringle":"^2.0.0","hardhat":"^2.9.9","hardhat-gas-reporter":"^1.0.8","jest":"^29.2.2","prettier":"^2.6.2","prettier-plugin-solidity":"^1.0.0-beta.19","solhint":"^3.3.7","solidity-coverage":"^0.7.21","ts-jest":"^29.0.3","typescript":"^4.7.4"},"releases":[{"from":"2022-11-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":3},{"from":"2022-09-15T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":3},{"from":"2022-06-17T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":7},{"from":"2021-12-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":9},{"from":"2020-12-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":9}],"hasTestScript":true,"readme":"# Axelar Local Development Environment\n\nThis environment allows you to set up a local instances of the Axelar Gateways, instantiate your application-level executor contracts on the source/destination chains, and simulate message relaying between them.\n\n## Install\n\n```\nnpm install axelarnetwork/axelar-local-dev\n```\n\n## Examples\n\nSee [axelar-local-gmp-examples repo](https://github.com/axelarnetwork/axelar-local-gmp-examples/) for example use of this local development environment.\n\n## Simple use\n\nThe following script shows a simple example of how to use this module to create two test blockchains and send some UST from one to the other.\n\n```typescript\nimport { createNetwork, relay } from \"@axelar-network/axelar-local-dev\";\n\nasync function main() {\n  // create eth network\n  const eth = await createNetwork({\n    name: \"Ethereum\",\n  });\n  // deploy eth token\n  await eth.deployToken(\"USDC\", \"aUSDC\", 6, BigInt(100_000e6));\n\n  // create avalanche network\n  const avalanche = await createNetwork({\n    name: \"Avalanche\",\n  });\n  // deploy avalanche token\n  await avalanche.deployToken(\"USDC\", \"aUSDC\", 6, BigInt(100_000e6));\n\n  // extract user accounts\n  const [ethUserWallet] = eth.userWallets;\n  const [avalancheUserWallet] = avalanche.userWallets;\n\n  // mint tokens on source chain\n  await eth.giveToken(ethUserWallet.address, \"aUSDC\", BigInt(100e6));\n\n  // extract token contracts\n  const usdcEthContract = await eth.getTokenContract(\"aUSDC\");\n  const usdcAvalancheContract = await avalanche.getTokenContract(\"aUSDC\");\n\n  // approve gateway to use token on source chain\n  const ethApproveTx = await usdcEthContract\n    .connect(ethUserWallet)\n    .approve(eth.gateway.address, 100e6);\n  await ethApproveTx.wait();\n\n  // ask gateway on source chain to send tokens to destination chain\n  const ethGatewayTx = await eth.gateway\n    .connect(ethUserWallet)\n    .sendToken(avalanche.name, avalancheUserWallet.address, \"aUSDC\", 100e6);\n  await ethGatewayTx.wait();\n\n  // relay transactions\n  await relay();\n\n  console.log(\n    (await usdcEthContract.balanceOf(ethUserWallet.address)) / 1e6,\n    \"aUSDC\"\n  );\n  console.log(\n    (await usdcAvalancheContract.balanceOf(avalancheUserWallet.address)) / 1e6,\n    \"aUSDC\"\n  );\n}\n\nmain();\n\n```\n\nSimply run `node <path to the above script>` to test it. Additional examples are present in the `examples` directory and can be run with:\n\n```\nnode node_modules/@axelar-network/axelar-local-dev/examples/<example_dir>/<file_name>.js\n```\n\n## Functionality\n\nThis module exports the following types:\n\n- `CreateLocalOptions`: Options to setup multiple local chains using `createAndExport` (see below). All are optional.\n  - `chainOutputPath`: A path to save a json file with all the information for the chains that are setup.\n  - `accountsToFund`: A list of addresses to fund.\n  - `fundAmount`: A string representing the amount of ether to fund accounts with. Defaults to `100 ETH`.\n  - `chains`: A list with all of the chain names (also determines the number of created networks). Defaults to `[\"Moonbeam\", \"Avalanche\", \"Fantom\", \"Ethereum\", \"Polygon\"]`.\n  - `relayInterval`?: amount of time between relay of events in miliseconds. Defaults to `2000`.\n  - `port`: Port to listen to. Defaults to `8500`.\n  - `afterRelay`: A function `(relayData: RelayData) => void` which will be called after each relay. Mainly to be used for debugging.\n  - `callback`: A function `(network: Network, info: any) => Promise<null>` that will be called right after setting up each network. Use this to setup additional features, like deploying contracts that already exist on testnet/mainnet.\n- `CloneLocalOptions`: An extension of `CreateLocalOptions` that also includes:\n  - `env`: a `string` whose value is either `mainnet` or `testnet`, or an `array` of `ChainCloneData`.\n  - `chains`: These now act as a filter for which chains to fork. Defaults to all the chains.\n  - `networkInfo`: The `NetworkInfo` (see below) which overwrites the default parameters.\n- `Network`: This object type is used to handle most functionality within the module. It has the following properties:\n  - `name`: The name of the network.\n  - `chainId`: The chainId of the network.\n  - `provider`: The `ethers.Provider` for the network.\n  - `userWallets`: A list of funded `ethers.Wallet` objects.\n  - `gateway`: An `ethets.Contract` object corresponding to the Axelar Gateway on the network.\n  - `gasReceiver`: An `ethets.Contract` object corresponding to the AxelarGasReceiver that receives gas for remote execution. It expects gas between the same two `relay()`s to funtion properly.\n  - `ust`: An `ethets.Contract` object corresponding to the IERC20 of the Axelar Wrapped UST on this network.\n  - `ownerWallet`, `operatorWallet`, `relayerWallet`, `adminWallets` `threshold` `lastRelayedBlock`: These are for configuring the gateway and relaying.\n  - `deployToken(name, symbol, decimals, cap)`: Deploys a new token on the network. For a token to be supported properly it needs to be deployed on all created networks.\n  - `getTokenContract(sybmol)`: Returns an `ethers.Contract` linked to the ERC20 token represented by `symbol`.\n  - `giveToken(address, symbol, amount)`: Gives `amount` of `symbol` token to `address`.\n  - `getInfo()`: Returns an object with all the information about the `Network`.\n  - `relay()`: This method is either equivalent to calling the local instance of this module's `relay()` (see below) or, for remote networks, the host's instance of `relay()`.\n- `NetworkOptions` This type is used as an input to create networks and can include the following. All are optional.\n  - `ganacheOptions`: Additional options to be passed into `require(ganache).provider`.\n  - `dbPath`: Where to save/find the db for a network already created. Will not save unless specified.\n  - `port`: Which port to listen to for this network. Will not listen to any port unless specified.\n  - `name`: The name of the network. Defaults to `Chain {n}` where `n` is the index of the network.\n  - `chainId`: The chainId of the network, defaults to `n`.\n  - `seed`: A seed that determines the addresses of funded accounts and contract addresses.\n- `ChainCloneData`: Data needed to for a network. `mainnetInfo` and `testnetInfo` can both be used as `ChainCloneData`.\n  - `name`: Name of the network to create.\n    `gateway`: The (preexisting) address of the gateway.\n    `rpc`: A url to an RPC to connect to the chain to fork.\n    `chainId`: The chain id, as a `Number`.\n    `gasReceiver`: The (preexisting) address of the gasReceiver.\n    `constAddressDeployer`: The (preexisting) address of the constAddressDeployer.;\n    `tokenName`: The name of the native token on this chain.\n    `tokenSymbol`: The symbol of the native token on this chain.\n    `tokens`: An object with all the registered axelar tokens\n- `NetworkSetup`: This type is used as an input to setup networks and can include the following. All but `ownerKey` are optional.\n  - `name`: The name of the network. Defaults to `Chain {n}` where `n` is the index of the network.\n  - `chainId`: The chainId of the network, defaults to `n`.\n  - `ownerKey`: A funded `ethers.Wallet` that will be used for deployments.\n  - `userKeys`: A list funded `ethers.Wallet`.\n  - `operatorKey`, `relayerKey`, `adminKeys`, `threshold`: Optional info for gateway setup.\n- `NetworkInfo`: Information of a chain, used to get an already setup network. They can be obtained by `getInfo()` for any existing network.\n  - `name`: The name of the network. Defaults to `Chain {n}` where `n` is the index of the network.\n  - `chainId`: The chainId of the network, defaults to `n`.\n  - `userKeys`: The user private keys.\n  - `ownerKey`: The owner private key.\n  - `operatorKey`: The operator private key.\n  - `relayerKey`: The relayer private key.\n  - `adminKeys`: The admin private key.\n  - `threshold`: The threshold of signers on the gateway.\n  - `lastRelayedBlock`: The last block that events were replayed up to.\n  - `gatewayAddress`: The address of the Axelar gateway.\n  - `usdcAddress`: The address of USDC.\n  - `gasReceiverAddress`: The address of the `gasReceiver` contract.\n  - `constAddressDeployerAddress`: The address of the `constAddressDeployer` contract.\n\n\nThe following is exported by this module.\n\n- `createAndExport(CreateLocalOptions)`: Creates and sets up a number of networks, and listens for RPC for all of them on a single port.\n- `forkAndExport(CloneLocalOptions)`: Like the above but forks either mainnet or testnet. Takes longer and spams RPCs so only use if you need something else deployed.\n- `createNetwork(NetworkOptions)`: Creates a new `Network`. \n- `getNetwork(urlOrProvider, NetworkInfo=null)`: Return `Network` hosted elsewhere into this instance.\n- `setupNetwork(urlOrProvider, NetworkSetup)`: Deploy the gateway and USDC Token on a remote blockchain and return the corresponding `Network`. The only value that is required in `NetworkSetup` is `ownerKey` which is a wallet of a funded account.\n- `listen(port, callback = null)`: This will serve all the created networks on port `port`. Each network is served at `/i` where `i` is the index of the network in `networks` (the first network created is at `/0` and so on).\n- `getAllNetworks(url)`: This will retreive all the networks served by `listen` called from a different instance.\n- `relay()`: A function that passes all the messages to all the gateways and calls the appropriate `IAxelarExecutable` contracts.\n- `getDepostiAddress(sourceNetwork, destinationNetwork, destinationAddress, symbol)`: This function generates a deposit address on `network1` that will route any funds of type `symbol` deposited there (minus some fee) to the `destinationAddress` in `network2`.\n- `getFee(sourceNetwork, destinationNetwork, symbol)`: returns the fee for transferring funds. Is set to a constant `1,000,000`.\n- `getGasPrice(sourceNetwork, destinationNetwork, tokenOnSource)`: returns the gas price to execute on `destinationChain`, to be payed in `sourceChain` in token specified by `tokenOnSource` (which is given as an address). `tokenOnSource=AddressZero` corresponds to the native token of the source chain. It always returns `1` but may change in the future.\n- `stop(network)`: Destroys the network and removes it from the list of tracked networks.\n- `stopAll()`: Stops all tracked networks.\n- `networks`: A list of all the `Network`s in this instance.\n\n## Smart Contracts\n\nTo use the Networks created you need to interact with the deployed `AxelarGateway` contract. You can send remote contract calls to the contracts implementing the `IAxelarExecutable` interface.\n\n### `AxelarGateway`\n\nThis contract exposes three functions to use:\n\n- `sendToken(string destinationChain, string destinationAddress, string symbol, uint256 amount)`: The `destinationChain` has to match the network name for the token to reach its destination after relaying. The `destinationAddress` is the human-readable version of the address, prefixed with `0x`. This is a `string` instead of an `address` because in the real world you can send token to non-evm chains that have other address formats as well. `tokenSymbol` has to match one of the tokens that are deployed in the network, by default just UST but additional tokens can be added (see `deployToken` under `Network`).\n- `callContract(string destinationChain, string contractDestinationAddress, bytes payload)`: See above for `destinationChain` and `contractDestinationAddress`. `payload` is the information passed to the contract on the destination chain. Use `abi.encode` to produce `payload`s.\n- `callContractWithToken(string destinationChain, string contractDestinationAddress, bytes payload, string symbol, uint256 amount)`: This is a combination of the above two functions, but the token has to arrive at the contract that is executing.\n\n### `IAxelarExecutable`\n\nThis interface is to be implemented for a contract to be able to receive remote contract calls. There are two functions that can be overriden, but depending on the use you may only choose to override one of them only.\n\n- `_execute(string memory sourceChain, string memory sourceAddress, bytes calldata payload)`: This will automatically be called when Axelar relays all messages. `sourceChain` and `sourceAddress` can be used to validate who is making the contract call, and `payload` can be decoded with `abi.decode` to produce any data needed.\n- `_executeWithToken(string memory sourceChain, string memory sourceAddress, bytes calldata payload, string memory symbol, uinst256 amount)`: This is the same as above but it is guaranteed to have also received `amount` token specified by `symbol`. You can use \\_getTokenAddress(symbol) to obtain the address of the ERC20 token received.\n\n### `AxelarGasReceiver`\n\nThis contract is automatically deployed and can be used to pay gas for the destination contract execution on the source chain. Smart contracts calling `callContract` and `callContractWithToken` should also handle paying for gas. It exposes [many functions](https://github.com/axelarnetwork/axelar-cgp-solidity/blob/feat/gas-receiver/src/util/AxelarGasReceiver.sol), but the main ones are\n\n- `receiveGas(string destinationChain, string destinationAddress, bytes payload, address gasToken, uint256 gasAmount)`: Receives `gasAmount` of `gasToken` to execute the contract call specified. The execution will use a gasLimit of `gasAmount / getGasPrice(...)` (see [above](#functionality) for `getGasPrice`).\n- `receiveGasNative(string destinationChain, string destinationAddress, bytes payload)`: As above with the native token as the `gasToken` and `msg.value` as the `gasAmount`.\n- `receiveGasWithToken(string destinationChain, string destinationAddress, bytes payload, string symbol, uint256 amountThrough, address gasToken, uint256 gasAmount)`, `receiveGasNtiveWithToken(string destinationChain, string destinationAddress, bytes payload, string symbol, uint256 amountThrough)`: Similar to the above functions but they are for `callContractWithToken` instead of `callContract`.\n- `ReceiveGas(Native)AndCallRemote(WithToken)(...)`: There are four such functions that will also pass the call to the gateway after receiving gas, for convenience.\n\n## Aptos\n\nWe also support a local develompent environment for aptos cross chain communication. This only supports general message passing. `AptosNetwork` is a generalization of `AptosClient` (avaliable in the `aptos` package) that includes (among others that are mainly used for intrnal purposes):\n\n- `getResourceAccountAddress(MaybeHexString sourceAddress, MaybeHexString seed)`: Predicts the aptos resource address for an account with a certain seed.\n- `deploy(string modulePath , string[] compiledModules, MaybeHexString seed)`: Deploy `compiledModules` found in `modulePath`. Seed is optional, if it is included then the modules are deployed as a resource.\n- `submitTransactionAndWait(MaybeHexString from, EntryFunctionPayload txData)`: A wrapper for aptos' submit transaction workflow, for ease of use.\n\nAdditionaly we export two utility functions\n\n- `createAptosNetwork(config?: {nodeUrl: string, faucetUrl: string})`: This funds the `owner` account and uses it to deploy the gateway module. `nodeUrl` defaults to `http://localhost:8080` and `faucetUrl` defaults to `http://localhost:8081`\n- `loadAptosNetwork(string nodeUrl)`: This loads the an preconfigured `AptosNetwork`. It is useful so that relaying works properly to said aptos network works properly.\n\n`createAndExport` (see above) will try to also call `createAptosNetwork` so that realying works to aptos as well."},"npm":{"downloads":[{"from":"2022-12-13T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":47},{"from":"2022-12-07T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":344},{"from":"2022-11-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":641},{"from":"2022-09-15T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":1759},{"from":"2022-06-17T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":2320},{"from":"2021-12-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":2395}],"starsCount":0},"github":{"starsCount":8,"forksCount":4,"subscribersCount":4,"issues":{"count":44,"openCount":6,"distribution":{"3600":18,"10800":8,"32400":1,"97200":2,"291600":3,"874800":2,"2624400":5,"7873200":2,"23619600":3,"70858800":0,"212576400":0},"isDisabled":false},"contributors":[{"username":"Foivos","commitsCount":128},{"username":"npty","commitsCount":63},{"username":"re1ro","commitsCount":15},{"username":"vladwulf","commitsCount":6},{"username":"eguajardo","commitsCount":4},{"username":"0x1NotMe","commitsCount":4},{"username":"canhtrinh","commitsCount":2},{"username":"ggutoski","commitsCount":2}],"commits":[{"from":"2022-12-07T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":5},{"from":"2022-11-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":20},{"from":"2022-09-15T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":73},{"from":"2022-06-17T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":121},{"from":"2021-12-14T00:00:00.000Z","to":"2022-12-14T00:00:00.000Z","count":224}]},"source":{"files":{"readmeSize":15530,"testsSize":27683,"hasNpmIgnore":true},"linters":["eslint","prettier"],"outdatedDependencies":{"@axelar-network/axelar-gmp-sdk-solidity":{"required":"^1.1.0","stable":"2.0.0","latest":"2.0.0"},"fs-extra":{"required":"^10.1.0","stable":"11.1.0","latest":"11.1.0"}}}},"evaluation":{"quality":{"carefulness":0.9199999999999999,"tests":0.6,"health":0.5555555555555556,"branding":0},"popularity":{"communityInterest":24,"downloadsCount":586.3333333333334,"downloadsAcceleration":5.28306697108067,"dependentsCount":0},"maintenance":{"releasesFrequency":1,"commitsFrequency":1,"openIssues":1,"issuesDistribution":0.9679350188164109}},"score":{"final":0.6098241469097263,"detail":{"quality":0.8112750823463882,"popularity":0.046988080741713664,"maintenance":0.9999879827034572}}}