witnet-solidity-bridge

Solidity source code of the smart contracts composing the Witnet EVM Bridge framework. This framework enables smart contracts operating in a long range of EVM-compatible chains to interact with the Witnet Oracle Blockchain for retrieving and aggregating offchain public data, or as an entropy source for randomness generation.

Install the package

$ pnpm install

Deploying the Witnet EVM Bridge on a new chain

Pre-assessment

Should any artifact require customized contract implementations:

• Please add source files accordingly to contracts/core/customs.

• Set up new artifact names, and eventual new construction parameters, if required, to settings/artifacts and settings/specs, respectively.

• Run regression tests: $ pnpm run test

Prepare the environment

• Add a new network configuration to settings/networks. The network name should follow the pattern <ecosystem>:<chain-name>.

• Make sure you run an ETH/RPC provider for the specified host and port, capable of intercepting eth_sendTransaction calls (e.g. web3-ethrpc-gateway).

Run the script

$ pnpm run migrate <ecosytem>:<chain-name>

Upgrding the Witnet EVM Bridge on an existing chain

When modifying the existing source code, or the contents of settings/artifacts or settings/specs, you may need to upgrade some of the artifacts on certain networks. Just add the --artifacts parameter and a comma-separated list of the artifacts you need to upgrade. For instance:

$ pnpm run migrate <ecosystem>:<chain-name> WitnetErrorsLib,WitnetPriceFeeds

When specifying deployable library artifacts, the depending contracts will be attempted to be upgraded as well.

With respect to deployable contracts, you shall be asked to confirm manually before actually performing a contract upgrade. You can automate all potentially involved upgrades by adding the parameter --upgrade-all.

Reasons for an upgrade to fail:

• You have no credentials.
• You're attempting to upgrade a contract with the same implementation logic as it currently has.
• The parameters passed to the upgrade call, as specified in settings/specs are not accepted for some reason (see actual revert message for further info).

Package exported modules

require("witnet-solidity-bridge")

Javacript methods and resources:

• List of supported EVM ecosystems:
  • supportedEcosystems()
• List of supported EVM chains:
  • supportedNetworks()
• WEB addresses at a given chain:
  • getAddresses(network)
• WEB artifacts:
  • assets.WitnetOracle
  • assets.WitnetPriceFeeds
  • assets.WitnetPriceRouteSolver
  • assets.WitnetRequest
  • assets.WitnetRequestBytecodes
  • assets.WitnetRequestFactory
  • assets.WitnetRequestTemplate
  • assets.WitnetUpgrableBase

require("witnet-solidity-bridge/utils")

Javascript utils methods:

• fromAscii(str)
• getRealmNetworkFromArgs()
• getRealmNetworkFromString()
• getWitnetArtifactsFromArgs()
• getWitnetRequestMethodString(method)
• isDryRun(network)
• isNullAddress(addr)
• padLeft(str, char, size)
• prompt(text)
• readJsonFromFile(filename)
• overwriteJsonFile(filname, extra)
• traceHeader(header)
• traceTx(tx)
• traceVerify(network, verifyArgs)