Wrapped/WIT contracts and CLI tools

A command-line tool and smart contract suite to wrap and unwrap $WIT coins between Witnet and Ethereum blockchains, using specific RPC endpoints for each.

✨ Overview

This repository contains:

• A CLI tool (witwrap) to interact with both Witnet and Ethereum RPCs to:

  • Wrap native $WIT coins from Witnet into ERC-20 tokens on Ethereum.
  • Unwrap ERC-20 $WIT tokens on Ethereum back into native coins on Witnet.
  • Check out both wrapped and under-custody $WIT suppies on Ethereum and Witnet.
  • Notarize Proof-of-Reserve reports on Witnet and then push them on-chain into Ethereum.
  • Get list of supported EVM testnets and mainnets.
  • Get relevant info about the ERC-20 contract on each supported network.
  • Get history of transfer, wrap and unwrap transactions.
  • Measure actual time taken by cross-chain transactions.

• A Javascript library allowing scripts to introspect supported networks, ABIs, addresses and settings, as well as some related helper methods.

• The full Solidity source code of both the canonical and bridged versions of the Wrapped/WIT ERC-20 token deployed on Ethereum and other Superchain-compliant networks.

📦 Installation

CLI binary

Install the witwrap binary:

$ npm install -g @witnet/wrapped-wit

NPM module

• Add the @witnet/wrapped-wit module to your Github project:

  $ npm install --save-dev @witnet/wrapped-wit

• Import from Javascript:

  const { WrappedWIT } = require("@witnet/wrapped-wit")

• Import from Typescript:

  import { WrappedWIT } from "@witnet/wrapped-wit"

⚙️ Requirements

• Node.js >= 20
• Wallets with sufficient $ETH and $WIT for transacting on both Ethereum and Witnet networks.

🔧 Configuration

The CLI can be configured using a .env file or by setting the following two variables:

  ETHRPC_PRIVATE_KEYS=["your_eth_private_key_1", ..., "your_eth_private_key_n"]
  WITNET_SDK_WALLET_MASTER_KEY="xprv_string_here_as_exported_from_mww_or_sheikah"

You can optionally:

• Settle your preferred ETH/RPC provider when launching the local gateway (see below).
• Settle your preferred WIT/RPC provider by using the command-line option --witnet, where suitable.

🛠️ Usage

  $ witwrap <command> [<args>] [<flags>] [<options>] [--help]

Commands

You need to have a local ETH/RPC gateway running in order to get access to extra commands. You will only be able to wrap and unwrap $WIT coins if you connect to an EVM network where the canonical version of the ERC-20 token is available (see supported networks below).

---

$ witwrap networks

Lists supported EVM networks.

Flags:

• --mainnets: Just list the mainnets.
• --testnets: Just list the testnets.

---

$ witwrap gateway <evm_network>

Launches a local ETH/RPC signing gateway to the specified evm_network, listening on port 8545 if no otherwise specified.

Options:

• --port: Port where the new gateway should be listening on.
• --remote: URL of the ETH/RPC remote provider to use instead of the gateway's default for the specified network.

Launch a gateway to your preferred EVM network on a different terminal so you can augment the available commands of the witwrap CLI binary. If you launch the gateway on a port other than default's, you'll need to specify --port <PORT> when invoking other commands of the witwrap binary.

---

$ witwrap contract

Shows the address and other relevant data of the WrappedWIT contract that's available on the connected EVM network.

Flags:

• --verbose: Outputs extra information.

---

$ witwrap supply

Shows wrapped $WIT supply information on the connected EVM network. It also detects if the total reserve supply in Ethereum is outdated with respect the actual under-custody supply on Witnet, asking you whether you wish to permissionlessly contribute by notarizing (in Witnet) and pushing (in Ethereum) a fresh new Proof-of-Reserve report.

Flags:

• --verbose: Outputs history of Proof-of-Reserve update reports.

Options:

• --limit: Limit number of history records.
• --from: EVM signer address to use when pushing a fresh new Proof-of-Reserve report into Ethereum.
• --gasPrice: Max. EVM gas price to pay when pushing a Proof-of-Reserve report into Ethereum.

---

$ witwrap transfers

Shows the history of recent transfers of wrapped $WIT on the connected EVM network. It also allows you to transfer wrapped $WIT tokens in Ethereum, as long the signing addresses of your EVM gateway holds some wrapped $WIT balance.

Flags:

• --burns: Also show history of burnt $WIT (either unwrapped to Witnet, or bridged to other EVM networks).
• --mints: Also show history of minted $WIT (either wrapped from Witnet, or bridged from other EVM networks).

Options:

• --limit: Limit number of history records.
• --since: Process events starting from the specified EVM block number.
• --from: Filter transfers from the specified EVM address (required when ordering a new transfer).
• --into: Filter transfers to the specified EVM address (required when ordering a new transfer).
• --value: Amount of $WIT to transfer between the specified addresses.
• --gasPrice: Max. EVM gas price to pay when transferring $WIT.

---

$ witwrap wrappings

Shows the history of past wrapping transactions, as well as an up-to-date list with the status of on-going wrapping workflows. It also allows you to initiate a wrap transaction on Witnet, and validate it on Ethereum when finalized.

Flags:

• --check: Show the time difference since the moment when the wrap transaction took place on Witnet, and when it got ultimately verified on Ethereum.

Options:

• --limit: Limit number of history records.
• --since: Process events starting from the specified EVM block number.
• --from: Filter wrappings from the specified WIT address (required when initiating a new wrap).
• --into: Filter wrappings to the specified EVM address (required when initiating a new wrap).
• --value: Amount of $WIT to be wrapped between the specified addresses.
• --vtt-hash: Request the validation on Ethereum of some not-yet verified wrapping transaction that took place on Witnet.
• --gasPrice: Max. EVM gas price to pay when querying the validation of some --vtt-hash.

---

$ witwrap unwrappings

Shows the history of past unwrapping transactions. It also allows you to unwrap $WIT tokens that you hold on any of the EVM gateway signing addresses, as long as there's enough under-custody reserve supply on the ERC-20 contract.

Flags:

• --check: Show the time difference since the moment when the unwrap transaction took place on Ethereum, and the unwrapped amount got ultimately transferred to the recipient on Witnet.

Options:

• --limit: Limit number of history records.
• --since: Process events starting from the specified EVM block number.
• --from: Filter unwrappings from the specified EVM address (required when ordering a new unwrap).
• --into: Filter unwrappings to the specified WIT address (required when ordering a new unwrap).
• --value: Amount of $WIT to be unwrapped between the specified addresses.
• --gasPrice: Max. EVM gas price to pay when querying the unwrapping of the specified amount.

📄 Smart Contracts

This repository includes the Solidity contracts that power the Ethereum side of the Wrapped/WIT, both on its canonical and Superchain-bridge versions.

Contracts are located in the contracts/ folder:

• WrappedWIT.sol

  The canonical version of the ERC-20 token contract for $WIT on Ethereum. It relies on the Wit/Oracle contract framework for validating both Proof-of-Reserve reports and cross-chain wrapping and unwrapping transactions.

• WrappedWITSuperchain.sol

  The "bridged" version of the ERC-20 token contract that allows wrapped $WIT tokens to be bridged out to a set of Superchain-compliant networks (see below). This version does not support wrapping nor unwrapping transactions with the Witnet network.

🧪 Supported Networks

Mainnets

Soon ^TM.

Testnets

EVM Network	ERC-20 Contract	Witnet Network
Ethereum Sepolia	WrappedWIT	Testnet
Base Sepolia	WrappedWITSuperchain
Celo Alfajores	WrappedWITSuperchain
Optimism Sepolia	WrappedWITSuperchain

🚀 Examples

Wrap 10,000.0 $WIT to Ethereum

It involves a two-step workflow:

• First, transfer 10,000.0 $WIT to the Wrapped/WIT custodian's address in Witnet:
  • witwrap wrappings --from <witnet_wallet_address> --into <evm_recipient> --value 10000.0
  • Wait a few minutes until the value transfer gets finalized in Witnet.
• Second, request the Wrapped/WIT contract to verify finality of the value transfer transaction in Witnet:
  • witwrap wrappings --vtt-hash <vtt_hash>
  • Wait a few minutes until the Wit/Oracle on Ethereum validates the finality of the specified value transfer in Witnet.
• You can at all times filter and check the status of pending wrapping transactions:
  • witwrap wrappings [--from <witnet_wallet_addres>] [--into <evm_recipient>]

Once the finality of the value transfer transaction that took place in Witnet gets verified in Ethereum, you shall see increased the $WIT balance of the specified <evm_recipient> address.

Unwrap 500.0 $WIT to Witnet

Just one single step required:

• witwrap unwrappings --from <evm_sender> --into <witnet_recipient> --value 500.0

In a matter of a few seconds, you should see increased the $WIT balance of the specified <witnet_recipient> address.

🔐 Security

• Do not share your private keys.
• Use trusted RPC endpoints when using others that the ones settled as default.
• Consider hardware wallets or key vaults for production usage.

📚 Documentation

Learn more about Witnet, the $WIT coin and the Wit/Oracle framework for smart contracts at:

👉 https://docs.witnet.io 👉 https://witnet.io 👉 https://witnet.foundation/

🧾 License

MIT © 2025 — Maintained by the Witnet Project.