On-Chain Setup Requirements

This page will take you through setting up the additional requirements for running a Gateway in On-Chain mode including finding an RPC URL, and creating an Ethereum account and keystore.

Page is under construction.
Feedback Welcome!

Complete: needs review

Overview

Livepeer is currently deployed on the Arbitrum L2 network (Arbitrum One).

In order to interact with the Livepeer smart contracts you will need to connect to an Arbitrum RPC.

If you plan to run your Gateway in On-Chain mode, you will need:

• An Ethereum account with funds to pay for transaction fees
• An Ethereum RPC URL to connect to the Arbitrum network where Livepeer is deployed

Required On-Chain Flags

Network Configuration

-network · string · default: "offchain"

Set to the blockchain network arbitrum-one-mainnet

Account Configuration

-ethUrl · string · default: "none"

Ethereum JSON-RPC URL

-ethAcctAddr · string · default: "none"

Your Ethereum PUBLIC Wallet (Account) Address.

The 0x prefix is optional for -ethAcctAddr Livepeer accepts addresses both with and without the prefix.

-ethPassword · string · default: "none"

Password for your KEYSTORE file or

Path to your password.txt file containing the password for your Keystore Account

-ethKeystorePath · string · default: "none"

Path to your encyrpted keystore directory or keyfile containing your private key

Security Notes

• Never share your keystore files - they contain your encrypted private keys
• Use strong passwords for keystore encryption - Back up your keystore securely - The ethPassword only protects the keystore file - your actual private key is stored encrypted within the keystore - Never share your wallet private key. In c ase of accidental public exposure - remove any funds & change your wallet immediately

EASY SETUP

Easy Setup with Livepeer Tooling

Install Your Gateway Software First

-> then come back to this guide.

Livepeer will automatically create a new wallet & keystore for you if you do not provide an existing wallet address after first installing your Gateway software.

The software will detect no keystore exists for that address and ask you to:

• Enter your private key
• Create an account address (wallet) -ethAcctAddr
• Set a password for the keystore encryption -ethPassword
• Create the keystore file -ethKeystorePath

Use the below command to quickstart an on-chain gateway with a new wallet and auto-generate all required parameters.

See RPC URL for instructions on finding or using an alternative Arbitrum RPC URL.

Create New Wallet & Keystore

livepeer -gateway \
-network arbitrum-one-mainnet \
-ethUrl=https://arb1.arbitrum.io/rpc #public RPC: rate-limited
\ -ethAcctAddr="" \
-ethKeystorePath="" \
-ethPassword=""

If you want to bring an existing wallet - put the public address in the -ethAcctAddr flag.

Exisiting Wallet, New Keystore

livepeer -gateway \
    -network arbitrum-one-mainnet \
    -ethUrl=https://arb1.arbitrum.io/rpc #public rate-limited RPC
    \ -ethAcctAddr=<YOUR_WALLET_ADDRESS> \
    -ethKeystorePath=""

Account Data Default Folders

Account data is stored in the ~/.lpData directory by default.

Keystore files are by default created in:

Docker

Docker

#inside container
/root/.lpData/

#on host
/var/lib/docker/volumes/gateway-lpData/_data/

Linux / Mac

Linux/Mac

~/.lpData/arbitrum-one-mainnet/keystore/

Windows

Windows

#C:\Users\YOUR_USERNAME\.lpData\{network}\keystore\
%USERPROFILE%\.lpData\arbitrum-one-mainnet\keystore\

Next Step

Fund Your Gateway

FULL SETUP GUIDE

Comprehensive On-Chain Setup Guide

Full Guide with alternative options for setting up an on-chain Gateway

1. Network `-network`

   -network · string · default: "offchain"

   Set to the blockchain network arbitrum-one-mainnet

2. RPC URL `-ethUrl` flag

   -ethUrl · string · default: "none"

   Ethereum JSON-RPC URL

   Example: https://arb1.arbitrum.io/rpc

   You can use any Arbitrum One RPC URL.

   • Public RPCs
   • Third-party RPC providers
   • Self-hosted RPC

   See All RPC Options

   Public RPCs

   Public RPCs

   Many of the public RPCs apply rate-limits, including the third-party providers. These free-tier RPC’s should be sufficient to run a single Gateway with the latest versions of Livepeer.

   Chainlist provides a full list of public Arbitrum One RPCs (including the Arbitrum public RPC):

   • Original Source Chainlist
   • Dynamically Imported: Arbitrum RPC Reference

   Show >_ Chainlist Arbitrum One RPC List

   You can also check the RPC status on Chainlist

   Third Party RPCs

   Paid RPCs

   If scaling beyond one Gateway, or running a large number of concurrent requests, you will need to pay for additional RPC capacity on one of the RPC providers.

   Some popular third-party RPC providers include:

   Provider	Arbitrum One	Websocket (wss)?	Stylus Tracing?
   Alchemy	✅	✅	Available on paid plans
   Ankr	✅	✅	Available on paid plans
   Chainstack	✅	✅	Available on paid plans
   Infura	✅	✅	Enabled on request
   Moralis	✅
   Quicknode	✅	✅	Testnet supported in free tier

   Arbitrum One shares third-party providers in the Arbitrum Docs

   Self-Hosted RPC

   Self-Hosted RPC

   Alternatively, you can also self-host your own Arbitrum node.

   Self-hosting an RPC is covered in the Arbitrum Self-Hosting Guide
3. ETH Account `-ethAcctAddr`

   Blockchain wallets (accounts) have both a public account address (starting with “0x…”) and a private key.

   This field is for your public wallet address.

   ONLY use your PUBLIC Wallet Address in this field.

   NEVER use your PRIVATE key.

   A public address is akin to your bank account number, a private key is like your bank PIN or password.

   -ethAcctAddr · string · default: "none"

   Livepeer automatically creates a wallet for you if this field is empty.

   -ethAcctAddr=""

   Your public wallet address: 0x...

   Example: 0xc7653d426f2ec8bc33cdde08b15f535e2eb2f523

   
   

   See All Account Setup Options

   You can

   • Use an existing Ethereum wallet address (e.g., from MetaMask, hardware wallet, etc.)
   • Let Livepeer automatically create a new wallet address. See code accountmanager.go

   Existing Address

   You can use any existing Ethereum wallet address which can transact on Arbitrum.

   You will use Arbitrum One Mainnet to transact on the Livepeer network as this is significantly cheaper than using Ethereum, so ensure your wallet can transact on Arbitrum.

   It’s advisable to use a wallet you own the private keys for rather than an exchange wallet.

   The following guides are provided as a reference only - no recommendation is made for any specific wallet provider.

   • Metamask Guide
   • Ledger Guide
   • Trezor Guide

   Automatic Wallet

   Livepeer will automatically create a new wallet for you if you do not provide an existing wallet address. Simply leave the -ethAcctAddr flag empty and Livepeer will create a new wallet (and keystore) for you.

   # Automatic Account Address
   -ethAcctAddr=""
   
4. ETH Password `-ethPassword`

   This is NOT your wallet private key.

   Choose a strong password to secure your keystore file.

   Make sure to never share or lose access to either the password or the keystore file

   Think of this flag as -keystorePassword - it is the path to a password.txt file containing a (strong) password chosen by you.

   This password is used to decrypt the keystore file and access the (encrypted) private key.

   -ethPassword · string · default: "none"

   Path to a password.txt file containing a (strong) password chosen by you.

       # Password File
       -ethPassword=/path/to/password.txt
   

   Livepeer will prompt you for a password and create this automatically on running the Gateway if you leave this flag empty: -ethPassword=""

   
   

   See All Password Setup Options

   Linux / Mac

       # Create keystore directory
       mkdir -p ~/.lpData/keystore
   
       # Place your keystore file
       cp your_keystore_file.json ~/.lpData/keystore/
   
       # Create password file
       echo "your_password" > ~/.lpData/password.txt
   

   Windows

       # Create keystore directory
       mkdir %USERPROFILE%\.lpData\keystore
   
       # Place your keystore file in the directory
       # Create password file
       echo your_password > %USERPROFILE%\.lpData\password.txt
   

   Docker Setup

       services:
       gateway:
           volumes:
           - ./keystore:/root/.lpData/keystore
           - ./password.txt:/root/.lpData/password.txt
   
5. ETH Keystore `-ethKeystorePath`

   -ethKeystorePath · string · default: "none"

   This is the path to your keystore directory or keyfile.

       # Password File
       -ethKeystorePath=/path/to/keystore
   

   Livepeer will create the keystore automatically on running the Gateway if you leave this flag empty: -ethKeystorePath=""

   To bring your existing Ethereum account to Livepeer, you need to create a keystore file with your private key and place it in the correct directory structure.

   The keystore files follow Ethereum’s UTC-timestamp-address format. These files, often referred to as “UTC / JSON Wallets” or “Web3 Secret Storage Definition” files, are encrypted local files that contain your Ethereum private key, allowing access to your account.

   Livepeer uses standard Ethereum keystore encryption, so any tool that creates Ethereum keystores will work. Create a keystore file using Livepeer devtools or Ethereum tooling.

   Create Automatically with Livepeer Tooling

   It’s recommended to let Livepeer devtools automatically create the keystore on first run after installing the Gateway software.

   See Commands to Create Keystore with Livepeer Devtools

   Linux/Mac Command

   Use the command:

   livepeer -gateway \
       -network arbitrum-one-mainnet \
       -ethUrl=<YOUR_ARBITRUM_RPC_URL> \
       -ethAcctAddr=0xYOUR_WALLET_ADDRESS \
       -ethPassword="" #can be omitted
       \ -ethKeystorePath=""  #can be omitted
   

   Enter your private wallet key and password when prompted

   Docker Command

   Docker

   # Run interactively to create keystore
   docker run -it \
       -v gateway-lpData:/root/.lpData \
       livepeer/go-livepeer:latest \
       -gateway \
       -network arbitrum-one-mainnet \
       -ethUrl=<YOUR_ARBITRUM_RPC_URL> \
       -ethAcctAddr=0xYOUR_WALLET_ADDRESS
   

   The keystore will be created in the Docker volume at:

   /var/lib/docker/volumes/gateway-lpData/_data/arbitrum-one-mainnet/keystore/
   

   Windows

   Windows

       # Create directory
       mkdir %USERPROFILE%\.lpData\keystore
   
       # Run Livepeer - it will create account and prompt for password
       livepeer.exe -gateway -network arbitrum-one-mainnet -ethUrl=<RPC_URL>
   

   See Keystore File Location & Format

   Keystore File Location

   Docker

   Docker

   #inside container
   /root/.lpData/
   
   #on host
   /var/lib/docker/volumes/gateway-lpData/_data/
   

   Linux / Mac

   Linux/Mac

   #~/.lpData/{network}/keystore/
   ~/.lpData/arbitrum-one-mainnet/keystore/
   

   Windows

   Windows

   #C:\Users\YOUR_USERNAME\.lpData\{network}\keystore\
   %USERPROFILE%\.lpData\arbitrum-one-mainnet\keystore\
   

   Keystore File Format

   Keystore File Format

   {
       "address": "089d8ab6752bac616a1f17246294eb068ee23d3e",
       "crypto": {
           "cipher": "aes-128-ctr",
           "ciphertext": "...",
           "cipherparams": {"iv": "..."},
           "kdf": "scrypt",
           "kdfparams": {...},
           "mac": "..."
           },
       "id": "unique-id",
       "version": 3
   }
   

   Create Now with Ethereum Tooling

   Otherwise you can use Ethereum tools to create the keystore - instructions below.

   If you are here, It is assumed you understand the security implications of exporting your private key and are able to vet & install any required software and convert linux bash commands to your own OS.

   Livepeer does not endorse or recommend any particular site or tools provided.

   See Ethereum Tooling Setup

   To create the keystore file, you can use one of the following methods:

   • Using Docker: Run the container interactively
   • Using geth (Ethereum’s development tool)
   • Using eth-cli (Ethereum’s command line tool)
   • Using node
   • Using web-based sites (not recommended)

   You will need to:

   1. Export your private key from your existing wallet
   2. Create a keystore file with your private key
   3. Create a password file with a strong password
   4. Place the keystore file and password file in the correct directory

   1. Export Private Key

      Export your private key from your existing wallet

   2. Create Keystore File

      Show Keystore File Format

      UTC--

      A prefix to indicate the timestamp that follows is in Coordinated Universal Time (UTC).

      timestamp

      Date and time, in ISO 8601 format (e.g., 2015-11-16T11-52-22.592017989Z), of when the account was created or the keystore file generated

      public_address

      The public Ethereum address associated with the private key inside the file, typically without the 0x prefix.

      Example_Keystore.json

      // Format: UTC--<TIMESTAMP>--<PUBLIC_ADDRESS>.json
      UTC--2015-11-16T11-52-22.592017989Z--089d8ab6752bac616a1f17246294eb068ee23d3e.json
      

      Create Keystore File

      Show Using geth

      Use Ethereum’s development tool -> geth

      Linux/Mac

      # Install geth first
      sudo apt-get install ethereum  # Ubuntu/Debian
      brew install ethereum          # macOS
      
      # Create keystore
      geth account import --datadir ~/.lpData/arbitrum-one-mainnet/
      # Enter private key when prompted
      # Set password when prompted
      

      Show Using eth-cli

      Using eth-cli

      # Install eth-cli
      go install github.com/ethereum/go-ethereum/cmd/ethkey@latest
      # Create directory
      mkdir -p ~/.lpData/arbitrum-one-mainnet/keystore/
      # Import private key (will prompt for private key and password)
      ethkey import --datadir ~/.lpData/arbitrum-one-mainnet/
      

      Show Using Node

      If you have Node.js installed - create a keystore file with the following command:

      npx ethereum-keystore create --private-key YOUR_PRIVATE_KEY --password YOUR_PASSWORD --output ~/.lpData/arbitrum-one-mainnet/keystore/
      

      Show Web-based Sites

      • Enter your private key
      • Set a password
      • Download the keystore JSON
      • Save it to the correct directory for your OS
      • Create the password text file
   3. Create Password File

      Create a password.txt file containing a (strong) password chosen by you. This password is used to decrypt the keystore file and access the private key.

      Linux/Mac

      # Create password file with the same password you just used
      echo "YOUR_PASSWORD" > ~/.lpData/eth-secret.txt
      
      # Secure it (Linux/Mac)
      chmod 600 ~/.lpData/eth-secret.txt
      

   4. Create Password File & Configure Directory

      After creating the keystore with geth or eth-cli, you must manually create the password file.

      # geth creates the keystore but does NOT save the password
      geth account import --datadir ~/.lpData/arbitrum-one-mainnet/
      # Enter private key: xxxxxx
      # Enter password: yourpassword
      # ✓ Keystore created
      
      # YOU must manually create the password file
      echo "yourpassword" > ~/.lpData/eth-secret.txt
      

      Place it in Livepeer’s keystore directory & configure Livepeer to use your account.

      # Linux/Mac
      mkdir -p ~/.lpData/arbitrum-one-mainnet/keystore/
      mv UTC--* ~/.lpData/arbitrum-one-mainnet/keystore/
      

6. Funding Your Gateway

   Funding Your Gateway

   Jump to the funding your gateway guide

Show REMOVE ME: Old Stuff

An Ethereum private key is a 256-bit random integer. For user presentation and interoperability across most software, this number is nearly always represented as a 64-character hexadecimal string

# Private Key Example
afdfd9c3d2095ef696594f6cedcae59e72dcd697e2a7521b1578140422a4f890

• Account Address: Created and stored in
  # Account Address
  ~/.lpData/arbitrum-one-mainnet/keystore/
  
• Keystore File: Located at
  # Keystore file
  ~/.lpData/arbitrum-one-mainnet/keystore/UTC--{timestamp}--{address}
  

• Password: Livepeer prompts you to enter and confirm a password

ETH Account

Docker

Show Create ETH Wallet & Keystore

Create Livepeer Gateway ETH account

In this step we need to start the Gateway in order to create an Ethereum account.

docker compose run -it gateway

When prompted for the ETH password, enter a strong password to secure your Ethereum account. This password is used to decrypt and access the ETH private key.

Keep this password handy, we will use it in the following steps.

After you see the message that the Ethereum account has been unlocked, CTRL+C to exit the Livepeer docker instance.

Using the previously created ETH password, create the eth-secret file

nano -p /var/lib/docker/volumes/gateway-lpData/_data/eth-secret.txt

Modify Docker compose file to include eth-secret.txt

nano docker-compose.yml

Add the following line below the -ethKeystorePath and save

-ethPassword=/root/.lpData/eth-secret.txt

Here is the full modified version of the docker-compose.yml file

version: '3.9'

services:
gateway:
    image: livepeer/go-livepeer:<RELEASE_VERSION>
    container_name: "gateway"
    hostname: "gateway"
    ports:
    - 1935:1935
    - 8935:8935
    volumes:
    - gateway-lpData:/root/.lpData
    command: '-ethUrl=<YOUR ARB APC>
            -ethKeystorePath=/root/.lpData
            -ethPassword=/root/.lpData/eth-secret.txt
            -network=arbitrum-one-mainnet
            -cliAddr=gateway:5935
            -broadcaster=true
            -monitor=true
            -v=99
            -blockPollingInterval=20
            -maxPricePerUnit=300
            -pixelsPerUnit=1
            -rtmpAddr=0.0.0.0:1935
            -httpAddr=0.0.0.0:8935
            '
volumes:
gateway-lpData:
    external: true

Start Livepeer in the background

docker compose up -d

Launch the livepeer_cli

docker exec -it gateway /bin/bash
livepeer_cli -host gateway -http 5935

Linux

Show Create ETH Wallet & Keystore

1. Configure Gateway

   Create a file containing your Gateway Ethereum password

   sudo mkdir /usr/local/bin/lptConfig
   sudo nano /usr/local/bin/lptConfig/node.txt
   

   Enter your password and save the file

2. Create System Service

   Create a system service

   sudo nano /etc/systemd/system/livepeer.service
   

   Paste and update the following startup script with your personal info:

   [Unit]
   Description=Livepeer
   
   [Service]
   Type=simple
   User=root
   Restart=always
   RestartSec=4
   ExecStart=/usr/local/bin/livepeer -network arbitrum-one-mainnet \
   -ethUrl=<YOUR ARB RPC URL> \
   -cliAddr=127.0.0.1:5935 \
   -ethPassword=/usr/local/bin/lptConfig/node.txt \
   -maxPricePerUnit=300 \
   -broadcaster=true \
   -serviceAddr=<INSERT YOUR IP ADDRESS>:8935 \
   -transcodingOptions=/usr/local/bin/lptConfig/transcodingOptions.json \
   -rtmpAddr=0.0.0.0:1935 \
   -httpAddr=0.0.0.0:8935 \
   -monitor=true \
   -v 6
   
   [Install]
   WantedBy=default.target
   

   Start the system service

   sudo systemctl daemon-reload
   sudo systemctl enable --now livepeer
   

   Open the Livepeer CLI

   livepeer_cli -host 127.0.0.1 -http 5935
   

Windows

Show Create ETH Wallet & Keystore

Run Gateway

When prompted enter and confirm a password.

This password is used to decrypt the keystore file and access the private key. Make sure to never share or lose access to either the password or the keystore file

After confirming your password close the terminal.

Configure Gateway

Create a file containing your Gateway Ethereum password

In C:\Users\YOUR_USER_NAME\.lpData create a txt file named ethsecret.txt with the password you created in the previous step.

Add the -ethPassword flag to your .bat file

Add -ethPassword=C:\Users\YOUR_USER_NAME\.lpData\ethsecret.txt to the previously created .bat file

Funding Your ETH Account

See Fund Your Gateway

• -ethUrl: Ethereum JSON-RPC URL (required for on-chain)
• -ethAcctAddr: Your Ethereum account address
• -ethPassword: Password for your ETH account or path to password file
• -ethKeystorePath: Path to your keystore directory or keyfile

Development Setup For testing, use the devtool to create keys :

func CreateKey(keystoreDir string) string {
    keyStore := keystore.NewKeyStore(keystoreDir, keystore.StandardScryptN, keystore.StandardScryptP)
    account, err := keyStore.NewAccount(passphrase)
    return account.Address.Hex()
}