/cli-bidding

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Table of Contents

  1. Quick Guide
  2. Auction
  3. Usage
  4. Test

Quick Guide

  1. Edit the config/.env.example and save it as config/.env:

        NODE_ETHEREUM_URL=<you_ethereum_node>
    PRIVATE_KEY_CLI_BIDDING=<your_private_key>

    Your PRIVATE_KEY_CLI_BIDDING should have ether to pay the gas for the ethereum transactions and HEZ to pay the bid costs.

    If you will use a custom contracts, you should edit the config/addressSC file and add your smart contract address in the corresponding network id.

  2. npm i

  3. Register an operator in the auction with: node src/biddingCLI.js register --url https://www.example.com

  4. Display the information regarding the current open slots and current bidding price with: node src/biddingCLI.js slotinfo

  5. Bid for a slot X with Y amount: node src/biddingCLI.js bid --amount Y --slot X --bidAmount Y more information in usage

Auction

The auction is the forging consensus protocol of Hermez. In order to forge a batch in Hermez, a coordinator must bid for a slot which is a period of 40 ethereum blocks. The best bid wins the slot and therefore has the right to forge as many batches as possible in that period. This cli aims to easily interact with the Hermez Auction smart contract to facilitate this bidding task. Further information on the auction mechanism can be found in documentation

Usage

Commands

  • register: Register a coordinator in the HermezAuction contract
  • slotinfo: Display the information regarding the current open slots and current bidding price
  • bid: Bid for a slot
  • multibid: Bid for multiple slots
  • getHezBalances: Display the current HEZ balance of the ethereum account and inside the HermezAuction contract
  • claimhez: Claim the HEZ inside HermezAuction contract
  • Currentbids: isplay the current bids information starting from the actual slot, that were done by the wallet.

Register

Register a coordinator in the auction with a given URL. In order to make bids a coordinator must be registered first

⚠️ Be aware of using https

Options

  • URL [--url] <URL>
node src/biddingCLI.js register --url https://www.example.com

Slotinfo

Display the information regarding the current open slots and current bidding price. Optionally, a startingSlot and endingSlot to check the bidding price for that slot range. The range must be inside the openSlots.

If no slots range is specified, the 5 first open slots will be displayed. HEZ amounts are displayed dividing the amount by its decimals, wich are 18.

Options

  • startingSlot [--st | --startingSlot] <slot> (optional)
  • endingSlot [-e | --endingSlot] <slot> (optional)
node src/biddingCLI.js slotinfo --startingSlot 4150 --endingSlot 4170

or

node src/biddingCLI.js slotinfo

Bid

Bid for a especific slot. The bidAmount is the HEZ amount that will be bidded for that slot. The amount is the HEZ that will be transfer to the HermezAuction smart contract The amount and bidAmount are different parameters because there's some cases when the user could choose to not transfer HEZ to the auction (amount = 0) because there's already enough pending balance in the contract (see getHezBalances).

By default the permit option is active which means that the the bid transaction will do also an approve of tokens. In case that the user already approve enough tokens to make the amount transfer, is not necessary to activate this option

The units are by default ether, this means that all the input amounts are multiplied by 1e18. The user could choose wei instead, where the amounts are not multiplied.

Options

  • slot [-s | --slot] <slot>
  • bidAmount [-b | --bidAmount] <token amount>
  • amount [-a | --amount] <token amount>
  • usePermit [-p | --usePermit] <bool> (default: true)
  • units [-u | --units] <"ether" || "wei"> (default: ether) )
node src/biddingCLI.js bid --amount 1 --slot 100 --bidAmount 1

or equivalent:

node src/biddingCLI.js bid --amount 1000000000000000000 --slot 100 --bidAmount 1000000000000000000 --units "wei"

MultiBid

Bid for a set of slots. User must define the StartingSlot and endingSlot. The call will bid for that range of slots, both included.

The maxBid parameter will be the maximum amount of HEZ that the user is willing to pay for a slot, and the minBid the minimum HEZ. The Smart contract will choose always the minimum value between minBid < value <= maxBid to bid for each slot. If a slot cost more than the maxBid, the smart contract will skip that slot, and will bid for the rest.

Optionally, user can define the slotSets which can choose if he want to bid for a especific set of slots. There's 6 set of slots in the HermezAuction, every one of each could have a different minimum bids and therefore different HEZ price. That's why the user could want only bid for the "cheap" ones for example. Let's say, coordinator only want to bid for the slotSet 1 & slotSet 2, he should input the following: --slotSets false,true,true,false,false,false

The amount is the HEZ that will be transfered to the HermezAuction smart contract. User must be aware that the sum of the bidding of all the slots must be bigger or equal than the amount plus the pending balance in the auction: HEZ cost of all slots <= amount + pendingBalance

By default the permit option is active which means that the the bid transaction will do also an approve of tokens. In case that the user already approve enough tokens to make the amount transfer, is not necessary to activate this option.

The units are by default ether, this means that all the amounts are multiplied by 1e18. The user could choose wei instead, where the amounts are not multiplied.

Options

  • startingSlot [--st | --startingSlot] <slot>
  • endingSlot [-e | --endingSlot] <slot>
  • slotSets [--ss | --slotSets] <bool[6]> (optional)
  • maxBid [--max | --maxBid] <token amount>
  • minBid [--min | --minBid] <token amount>
  • amount [-a | --amount] <token amount>
  • usePermit [-p | --usePermit] <bool> (default: true)
  • units [-u | --units] <"ether" || "wei"> (default: "ether")

)

node src/biddingCLI.js multibid --amount 10 --startingSlot 22 --endingSlot 27 --slotSet true,true,true,true,false,false --maxBid 4 --minBid 3

GetHezBalances

Display the current HEZ balance of the ethereum account and inside the HermezAuction contract

node src/biddingCLI.js getHezBalances

Claimhez

Claim the pending HEZ inside HermezAuction contract

node src/biddingCLI.js claimhez

CurrentWinningbids

Display the current winning bids information starting from the actual slot, that were done by the wallet. If the option --all true is activated, display all the current winning bids from all the address instead.

Options

  • all [--all] <bool> (default false)
node src/biddingCLI.js currentwinningbids

Test

How to run the test in root repository:

  1. npm i
  2. npx ganache-cli
  3. Open another terminal and execute npx mocha test/biddingCLI.test.js