Torram Blockchain

This guide provides step-by-step instructions for setting up a Cosmos-SDK-based blockchain using torramd with multiple validators.

Prerequisites

Ensure you have torramd installed and configured on your system before proceeding by running make install.

Get API Key

1. To get the API Key, visit https://ordiscan.com/docs/api/account and generate your API Key.
2. On this machine, the API Key is bc4afe7d-59ae-44bd-9d13-f4dcb4227af7.
3. Save it in the .env file.
4. Replace it with your own API Key and then run the command below.

echo 'export ORDI_API_KEY="bc4afe7d-59ae-44bd-9d13-f4dcb4227af7"' >> ~/.bashrc
source ~/.bashrc

Get API Key

1. To get the API Key, visit https://ordiscan.com/docs/api/account and generate your API Key.
2. On this machine, the API Key is bc4afe7d-59ae-44bd-9d13-f4dcb4227af7.
3. Save it in the .env file.
4. Replace it with your own API Key and then run the command below.

echo 'export ORDI_API_KEY="bc4afe7d-59ae-44bd-9d13-f4dcb4227af7"' >> ~/.bashrc
source ~/.bashrc

Setting Up Multiple Validators

1. Genesis Validator Setup

First, initialize and start the genesis validator:

# Initialize the chain
make init

# Start the genesis validator
torramd start

2. Additional Validator Setup

For each additional validator, follow these steps:

1. Initialize the Chain

# Initialize the chain
make init

2. Initialize the Database

If the database is not already set up, run the following command to initialize it:

make run-database

3. Start the Blockchain Node

Begin running your blockchain node with a specified minimum gas price for transactions.

4. Configure P2P Connection

# Get validator ID and configure peers
VALIDATOR_ID=$(curl -s http://34.57.91.248:26657/status | jq -r '.result.node_info.id')
CONFIG_DIR="$HOME/.torramd/config"
sed -i.bak'' "s/^seeds =.*/seeds = \"$VALIDATOR_ID@34.57.91.248:26656\"/" "$CONFIG_DIR/config.toml"
sed -i.bak'' "s/^persistent_peers =.*/persistent_peers = \"$VALIDATOR_ID@34.57.91.248:26656\"/" "$CONFIG_DIR/config.toml"

5. Configure State Sync

sed -i.bak'' 's|enable = true|enable = false|' "$CONFIG_DIR/config.toml"
sed -i.bak'' 's|^rpc_servers =.*|rpc_servers = "http://34.57.91.248:26657,http://34.57.91.248:26657"|' "$CONFIG_DIR/config.toml"
TRUST_HASH=$(curl -s "http://34.57.91.248:26657/block?height=$1" | jq -r .result.block_id.hash)
sed -i.bak -e "s/trust_height = 0/trust_height = 1/" $CONFIG_DIR/config.toml
sed -i.bak -e "s/trust_hash = \"\"/trust_hash = \"$TRUST_HASH\"/" $CONFIG_DIR/config.toml

6. List Keys

torramd keys list --keyring-backend test
torramd keys show torram-node --bech val --keyring-backend test

5. Fund New Validator

On the genesis validator, send funds to the new validator:

torramd tx bank send torram-node torram1vk6wdymvxg2drcyu8asl6hsd7jsprpsd8urg3f 10000000torram \
--keyring-backend test \
--chain-id torram \
--from torram-node \
--gas-prices 1torram \
--gas 800000

Verify the balance on the new validator:

torramd query bank balances torram1vk6wdymvxg2drcyu8asl6hsd7jsprpsd8urg3f --node tcp://34.57.91.248:26657

6. Create New Validator

On the new validator node:

1. Create Validator Configuration

# Get validator pubkey
PUBKEY=$(torramd tendermint show-validator)

# Create validator.json
cat > validator.json << EOF
{
    "pubkey": $(echo $PUBKEY),
    "amount": "100000torram",
    "moniker": "torram-node",
    "commission-rate": "0.1",
    "commission-max-rate": "0.2",
    "commission-max-change-rate": "0.01",
    "min-self-delegation": "1"
}
EOF

2. Submit Create-Validator Transaction

torramd tx staking create-validator validator.json \
  --from=torram-node \
  --chain-id=torram \
  --gas="auto" \
  --gas-adjustment="1.5" \
  --fees=30000torram \
  --keyring-backend=test \
  --node tcp://34.57.91.248:26657

3. Delegate Additional Tokens (Optional)

torramd tx staking delegate $(torramd keys show torram-node --bech val -a --keyring-backend test) 1190000torram \
  --from=torram-node \
  --chain-id=torram \
  --gas="auto" \
  --gas-adjustment="1.5" \
  --fees=3000torram \
  --keyring-backend=test \
  --node tcp://34.57.91.248:26657

4. Start the Validator Node

torramd start

Monitoring

You can monitor the status of your validators using the following commands:

# Query validator set
torramd query staking validators --node tcp://34.57.91.248:26657

# Query specific validator
torramd query staking validator <validator-address> --node tcp://34.57.91.248:26657

Running the Relayer

To run the price oracle relayer:

# Navigate to the relayer directory
cd utils/Torram-Relayer/main/

# Install dependencies
go mod tidy

# Start the relayer
go run main.go -wif cQ75Ym4o2xr4g4WpMCcbnQTUsvfytnwQsr4iLhA7dv1QCCzNDSsG -wallet newlegacywallet -rpcuser your_username -rpcpass your_secure_password -rpchost localhost -rpcport 18332

Relayer Operation Flow

The relayer performs several key functions in sequence:

1. Price Data Collection

   [Price Fetcher] Waiting for price data...
   Starting price server on :8081
   Received data: {"height":62,"prices":{"BTC":"105119.135000000000000000","ETH":"3271.015000000000000000"}}
   

2. Data Processing and Merkle Tree Generation

   Processing batch of 10 items
   Extracted height: 44
   Calculated merkle root: f66be90e8e3631c924beda7657cb77799729b5fc9f45c94e62fba2aa5ae2dac9
   

3. Bitcoin Transaction Submission

   Transaction successfully broadcast! TxID: e05c4426c8e9dcec2bb7ff0ecab4a758b637cff987eeb42fa3da652f19896f96
   

4. Confirmation Monitoring The relayer continuously monitors for Bitcoin transaction confirmation:

   Waiting for confirmation of transaction: e05c4426c8e9dcec2bb7ff0ecab4a758b637cff987eeb42fa3da652f19896f96
   Raw API Response: {"confirmed":false}
   Waiting for confirmation... Transaction not yet confirmed
   

5. Transaction Confirmation and Data Update Once confirmed, the relayer updates both chains:

   Transaction confirmed! TxID: e05c4426c8e9dcec2bb7ff0ecab4a758b637cff987eeb42fa3da652f19896f96 at block height 67636
   Successfully submitted and confirmed batch with txHash: e05c4426c8e9dcec2bb7ff0ecab4a758b637cff987eeb42fa3da652f19896f96
   

Data Storage and Verification

The relayer maintains a local database (oracle.txt) with entries like:

{
    "height": 44,
    "prices": {
        "BTC": "105164.795000000000000000",
        "ETH": "3271.620000000000000000"
    },
    "processed": true,
    "tx_hash": "50b2c004a91da8ef2104d91b9fd6e88cba49a4afb88ae271e13774b4607cd27c",
    "cmd_tx_hash": "9308B24B2E78CB643493534CB164A9064D67F5DE2E83AFB9C8C78CF58D104B98"
}

Transaction Verification

You can verify transactions on both chains:

1. Bitcoin Testnet Visit the transaction in the Bitcoin testnet explorer: https://mempool.space/testnet4/tx/50b2c004a91da8ef2104d91b9fd6e88cba49a4afb88ae271e13774b4607cd27c

2. Torram Chain Query the transaction details using the CLI:

   torramd query tx 9308B24B2E78CB643493534CB164A9064D67F5DE2E83AFB9C8C78CF58D104B98 --output json | jq

TSB Relayer for Torram Chain

The TSB (Token Standard for Bitcoin) Relayer enables bidirectional synchronization of token operations between Torram blockchain and Bitcoin. This allows users to create and manage tokens that are synchronized across both chains, providing both the security of Bitcoin and the flexibility of Torram.

Architecture

The TSB Relayer consists of several core components:

1. Relayer Core - The main orchestration component that monitors both chains and synchronizes token operations.
2. Torram Client - Interacts with the Torram blockchain to query and submit transactions.
3. Bitcoin Service - Manages Bitcoin RPC interactions and transaction verification.
4. UTXO Manager - Handles UTXO selection and tracking for Bitcoin transactions.
5. Verification Logic - Validates token proofs across both chains.

Core Features

• Bidirectional Event Monitoring: Watches for events on both Torram and Bitcoin chains.
• Proof Verification: Validates token operations using cryptographic proofs.
• Transaction Construction: Builds and submits transactions to both chains.
• State Management: Tracks operations across both chains to ensure consistency.

Setup

Prerequisites

• Go 1.19 or higher
• Access to a Torram node
• Access to a Bitcoin node (with RPC enabled)
• Cosmos SDK keyring with a funded account

Installation

git clone https://github.com/TorramLabs-Team/TorramChain.git
cd TorramChain
make build-relayer

This will create the relayer binary in ./bin/tsbrelayer.

Configuration

The relayer accepts the following command-line flags:

--chain-id string       Chain ID of the Torram network (default "torram-chain")
--node string           URL of Torram node (default "http://localhost:26657")
--keyring-backend string Keyring backend to use (default "file")
--key-dir string        Directory for keys (default ".torram-keys")
--key-name string       Name of the key to use (required)
--btc-url string        URL of Bitcoin node (default "http://localhost:8332")
--btc-user string       Username for Bitcoin node (required)
--btc-pass string       Password for Bitcoin node (required)
--btc-network string    Bitcoin network (mainnet, testnet, regtest) (default "testnet")
--btc-address string    Bitcoin address for operations (required)
--poll-interval int     Polling interval in seconds (default 30)
--fee-rate float        Bitcoin fee rate in satoshis per byte (default 1.0)
--min-utxo float        Minimum Bitcoin UTXO value (default 0.0001)

Running the Relayer

./bin/tsbrelayer \
  --key-name=mykey \
  --btc-user=bitcoinrpc \
  --btc-pass=rpcpassword \
  --btc-address=tb1q0la2ks3ur9jpge9c8h60ydefww2wxe5j683v8l

Token Operations

The TSB relayer handles the following token operations:

1. Creation: Synchronizes new tokens created on either chain.
2. Transfer: Propagates token transfers across chains.
3. Burning: Ensures tokens burned on one chain are reflected on the other.

Protocol Details

TSB uses a simple protocol for encoding token data in Bitcoin transactions:

• Token creation: TSB:CREATE:<token_id>:<amount>:<type_code>:<metadata>:<timestamp>
• Token transfer: TSB:TRANSFER:<token_id>:<from>:<to>:<amount>
• Token burning: TSB:BURN:<token_id>:<amount>

These operations are embedded in OP_RETURN outputs in Bitcoin transactions.

License

This software is licensed under the MIT License.