Rootstock Go CLI

A command-line interface (CLI) tool written in Go for interacting with the Rootstock blockchain.
This tool provides comprehensive functionality to connect to an Ethereum-compatible RPC endpoint and manage wallets, query balances, send transactions, and interact with the Rootstock network.

Features

Wallet Management

• Create Wallet: Generate new wallets with password protection
• Import Wallet: Import existing wallets using private keys
• List Wallets: View all available wallets with optional names
• Export Wallet: Export wallet private key to the console
• Check Balance: Query RBTC balance for any wallet address

Transaction Operations

• Send Transactions: Transfer RBTC between wallets with configurable gas settings

Security Features

• Password Protection: All wallets are encrypted with user-defined passwords
• Secure Keystore: Wallets are stored in encrypted keystore files
• Private Key Management: Secure handling of private keys with optional display

Prerequisites

• Go 1.24.4 or higher
• Access to an Rootstock RPC endpoint

Installation

Option 1: Build from Source

1. Clone the repository:

git clone https://github.com/rsksmart/rsk-go-cli.git
cd rsk-go-cli

2. Build the application:

make build

Or build manually:

go build -o rsk-go-cli main.go

3. Make the binary executable:

chmod +x rsk-go-cli

Option 2: Run Directly

You can also run the application directly without building:

go run main.go

Environment Setup

Required Environment Variables

Create a .env file in the project root with the following variables:

# RSK RPC endpoint (required)
RPC_URL=https://public-node.testnet.rsk.co

RPC URL Options

You can use different Rootstock RPC endpoints:

• Mainnet: https://public-node.rsk.co
• Testnet: https://public-node.testnet.rsk.co

Example .env File

# RSK Testnet
RPC_URL=https://public-node.testnet.rsk.co

# Or for Mainnet
# RPC_URL=https://public-node.rsk.co

Usage

Basic Commands

# Show help
./rsk-go-cli --help

# Show wallet commands
./rsk-go-cli wallet --help

Wallet Management

Create a New Wallet

./rsk-go-cli wallet create

Create with private key display:

./rsk-go-cli wallet create --show-private-key

Import Existing Wallet

./rsk-go-cli wallet import

The command will prompt you to securely enter your private key. The input will not be displayed on screen for security.

Import Wallet Private Key to Console

./rsk-go-cli wallet export -j --name "My Wallet"

./rsk-go-cli wallet export -j --address 0xWALLET_ADDRESS

List All Wallets

./rsk-go-cli wallet list

Check Wallet Balance

# By address
./rsk-go-cli wallet balance --address 0xWALLET_ADDRESS

# By wallet name
./rsk-go-cli wallet balance --name "My Wallet"

Transfer RBTC

# Basic transfer
./rsk-go-cli transfer --from-address 0xFROM_ADDRESS --to-address 0xTO_ADDRESS --amount 0.1

# Transfer with custom gas settings
./rsk-go-cli transfer --from-address 0xFROM_ADDRESS --to-address 0xTO_ADDRESS --amount 0.1 --gas-limit 50000 --gas-price 0.001

# Transfer using wallet names
./rsk-go-cli transfer --from-name "My Wallet" --to-address 0xTO_ADDRESS --amount 0.1

# Transfer with automatic gas price (recommended)
./rsk-go-cli transfer --from-address 0xFROM_ADDRESS --to-address 0xTO_ADDRESS --amount 0.1

Command Options

Transfer Command Options

• --from-address or -f: Source wallet address
• --from-name or -n: Source wallet name
• --to-address or -t: Destination wallet address
• --to-nameor -m: Destination wallet name
• --amount: Amount to send in RBTC (required)
• --gas-limit or -g: Gas limit (default: 21000 for simple transfers)
• --gas-price: Gas price in Gwei (optional, automatically uses network-suggested price if not specified). Gas price must be between 0.0001 and 0.1 Gwei.

Balance Command Options

• --address or -a: Wallet address to check
• --name or -n: Wallet name to check

Development

Running Tests

go test ./...

Linting

make lint

Gas Management

The CLI provides intelligent gas handling for transactions:

Gas Limit

• Default: 21,000 gas units (standard for simple RBTC transfers)
• Custom: Set your own gas limit using --gas-limit flag
• When to adjust: Increase for complex transactions, smart contract interactions, or when you need more computational resources

Gas Price

• Automatic (Recommended): When --gas-price is not specified, the CLI automatically fetches the network's suggested gas price using eth_gasPrice
• Manual: Set your own gas price in Gwei using --gas-price flag
• Network Optimization: Automatic gas pricing ensures your transactions are processed efficiently without overpaying

Gas Cost Calculation

• Real-time Estimation: Shows estimated gas cost in RBTC before transaction execution
• Total Cost Display: Displays the complete transaction cost (transfer amount + gas fees)
• Balance Validation: Automatically checks if you have sufficient balance to cover both the transfer amount and gas fees

Example Gas Scenarios

# Let the network decide gas price (recommended for most users)
./rsk-go-cli wallet transfer --from-address 0x... --to-address 0x... --amount 0.1

# Set custom gas price (advanced users who want to control transaction priority)
./rsk-go-cli wallet transfer --from-address 0x... --to-address 0x... --amount 0.1 --gas-price 0.001

# Set custom gas limit for complex transactions
./rsk-go-cli wallet transfer --from-address 0x... --to-address 0x... --amount 0.1 --gas-limit 22000

Security Considerations

• Password Security: Use strong, unique passwords for your wallets
• Private Key Safety: Never share your private keys or keystore files
• Network Security: Ensure you're connecting to legitimate Rootstock RPC endpoints
• File Permissions: The application creates a .rsk-go-cli directory in your home folder with restricted permissions

Troubleshooting

Common Issues

1. RPC_URL not set: Ensure your .env file contains the RPC_URL variable
2. Connection errors: Verify your RPC endpoint is accessible and correct
3. Permission errors: Check that the application has write permissions to your home directory
4. Wallet not found: Ensure the wallet address or name is correct
5. Gas estimation failures: If automatic gas pricing fails, try specifying --gas-price manually

Getting Help

• Check the help command: ./rsk-go-cli --help
• Review command-specific help: ./rsk-go-cli wallet --help
• Ensure your .env file is properly configured

Contributing

We welcome contributions from the community. Please fork the repository and submit pull requests with your changes. Ensure your code adheres to the project's main objective.

Support

For any questions or support, please open an issue on the repository or reach out to the maintainers.

Disclaimer

The software provided in this GitHub repository is offered "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.

• Testing: The software has not undergone testing of any kind, and its functionality, accuracy, reliability, and suitability for any purpose are not guaranteed.
• Use at Your Own Risk: The user assumes all risks associated with the use of this software. The author(s) of this software shall not be held liable for any damages, including but not limited to direct, indirect, incidental, special, consequential, or punitive damages arising out of the use of or inability to use this software, even if advised of the possibility of such damages.
• No Liability: The author(s) of this software are not liable for any loss or damage, including without limitation, any loss of profits, business interruption, loss of information or data, or other pecuniary loss arising out of the use of or inability to use this software.
• Sole Responsibility: The user acknowledges that they are solely responsible for the outcome of the use of this software, including any decisions made or actions taken based on the software's output or functionality.
• No Endorsement: Mention of any specific product, service, or organization does not constitute or imply endorsement by the author(s) of this software.
• Modification and Distribution: This software may be modified and distributed under the terms of the license provided with the software. By modifying or distributing this software, you agree to be bound by the terms of the license.
• Assumption of Risk: By using this software, the user acknowledges and agrees that they have read, understood, and accepted the terms of this disclaimer and assumes all risks associated with the use of this software.