mx-bon-supernova-scripts

Requirements

Ensure Python and pip are installed.

Clone the repository and change the current working directory

Clone using SSH

git clone git@github.com:multiversx/mx-bon-supernova-scripts.git

Clone using HTTPS

git clone https://github.com/multiversx/mx-bon-supernova-scripts.git

Change the working directory

cd mx-bon-supernova-scripts

Install venv and create a virtual environment

After installing venv we can create a virtual environment and install the required dependencies.

python3 -m venv ./venv
source ./venv/bin/activate
pip install -r ./requirements.txt --upgrade

Usage

This CLI application manages MultiversX wallets and provides funding capabilities across shards, with support for intra-shard and cross-shard transactions.

Features

• Create Wallets: Creates .pem walllets
• Load Wallets: Automatically loads all .pem wallet files from a specified directory
• Shard Organization: Organizes wallets into three lists based on their shard (0, 1, or 2)
• Funding: Distributes funds from a whale wallet to all loaded wallets
• Intra-Shard Transfers: Create multiple transactions within a single shard
• Cross-Shard Transfers: Create multiple transactions between different shards
• Relayer Support: Use specific or random relayers for transactions

Commands

1. Create Wallets

Generate new wallets and save them as PEM files in a specified directory.

Basic usage:

python3 main.py create-wallets --wallets-dir ./wallets --number-of-wallets 100

Arguments:

• --wallets-dir (required): Directory where the new wallet PEM files will be saved (created if it does not exist)
• --number-of-wallets (required): Number of wallets to create

---

2. Fund Wallets

Fund all loaded wallets from a whale wallet.

Distribute a specific amount:

python3 main.py fund --wallets-dir ./wallets --whale whale.pem --amount 1000000000000000000 --network https://devnet-gateway.multiversx.com

Distribute all available balance:

python3 main.py fund --wallets-dir ./wallets --whale whale.pem --network https://devnet-gateway.multiversx.com

Arguments:

• --wallets-dir (required): Directory containing wallet PEM files
• --whale (required): Path to whale wallet PEM file
• --network (required): Network gateway URL or node URL
• --amount (optional): Total amount to distribute in atomic units (e.g., 1000000000000000000 = 1 EGLD). If not specified, distributes all available balance minus transaction fee reserve.

---

3. Transfer Intra-Shard

Create 99 transactions from each wallet in a shard to randomly selected wallets in the same shard.

Basic usage:

python3 main.py transfer-intrashard --wallets-dir ./wallets --shard 0 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com

With specific relayer:

python3 main.py transfer-intrashard --wallets-dir ./wallets --shard 0 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com --relayer erd1...

With random relayers:

python3 main.py transfer-intrashard --wallets-dir ./wallets --shard 0 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com --random-relayer

Arguments:

• --wallets-dir (required): Directory containing wallet PEM files
• --network (required): Network gateway URL or node URL
• --shard (required): Shard number (0, 1, or 2)
• --amount (required): Amount per transaction in atomic units
• --relayer (optional): Specific relayer address from the same shard
• --random-relayer (optional): Use random relayers from the same shard for each transaction

Note: You cannot specify both --relayer and --random-relayer at the same time.

---

4. Transfer Cross-Shard

Create 99 transactions from each wallet in source shard to randomly selected wallets in destination shard.

Basic usage:

python3 main.py transfer-crossshard --wallets-dir ./wallets --source-shard 0 --destination-shard 1 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com

With specific relayer:

python3 main.py transfer-crossshard --wallets-dir ./wallets --source-shard 0 --destination-shard 1 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com --relayer erd1...

With random relayers:

python3 main.py transfer-crossshard --wallets-dir ./wallets --source-shard 0 --destination-shard 1 --amount 1000000000000000 --network https://devnet-gateway.multiversx.com --random-relayer

Arguments:

• --wallets-dir (required): Directory containing wallet PEM files
• --network (required): Network gateway URL or node URL
• --source-shard (required): Source shard number (0, 1, or 2)
• --destination-shard (required): Destination shard number (0, 1, or 2)
• --amount (required): Amount per transaction in atomic units
• --relayer (optional): Specific relayer address from the source shard
• --random-relayer (optional): Use random relayers from the source shard for each transaction

Note: You cannot specify both --relayer and --random-relayer at the same time. Source and destination shards must be different.

---

Example Directory Structure

mx-bon-supernova-scripts/
├── main.py
├── requirements.txt
├── README.md
├── wallets/
│   ├── wallet1.pem
│   ├── wallet2.pem
│   └── wallet3.pem
└── whale.pem

Notes

• All amounts are in atomic units (1 EGLD = 10^18 atomic units)
• When distributing all balance, the script reserves funds for transaction fees automatically
• Wallets are automatically organized by shard using the AddressComputer from the MultiversX SDK
• Transactions are sent in batches of 1000 for better performance
• For transfer-intrashard and transfer-crossshard commands:
  • Each wallet sends 99 transactions to randomly selected receivers
  • Receivers can be repeated (random selection with replacement)
  • For intra-shard transfers, a wallet can send to itself
  • Relayers must be from the same shard as the sender (source shard for cross-shard transfers)
  • Relayer transactions are properly signed with relayer signatures