Using the Alpen CLI
The Alpen CLI is a Rust command line interface that allows you to interact with Alpen, the bitcoin bridge, and an associated signet bitcoin network.
Installation
Ensure you have Cargo installed. If you don't have it, we recommend you install it using Rustup. Then run:
cargo install --git https://github.com/alpenlabs/alpen --branch releases/0.2.0 [email protected] --locked --forceThis will compile and install the binary into your system path. It may take a few minutes depending on how powerful your hardware is.
Configure the CLI
Before using the CLI, run alpen config to find the location of your config.toml file. The output will look like:
~/.config/alpen/config.toml # Linux
~/Library/Application Support/io.alpenlabs.alpen/config.toml # MacOS
C:\Users\<USER>\AppData\Roaming\alpen\config.toml # WindowsIf the directory containing config.toml file does not exist, create the directory. Open the file (or create if it does not exist) and save the following configuration:
# Use esplora for the bitcoin signet backend
esplora = "https://esplora.testnet.alpenlabs.io"
# EVM-compatible endpoint for Alpen transactions
alpen_endpoint = "https://rpc.testnet.alpenlabs.io"
# Alpen's hosted faucet API
faucet_endpoint = "https://faucet-api.testnet.alpenlabs.io"
# mempool.space instance to explore the bitcoin signet
mempool_endpoint = "https://bitcoin.testnet.alpenlabs.io"
# Blockscout instance to explore Alpen's chain
blockscout_endpoint = "https://explorer.testnet.alpenlabs.io"
# Bridge multisig public key
bridge_pubkey = "705f1c4a00a46ca0f99627f33e8daf4e227967d6e9f0210a950d9d6103f9db1d"
# Prefix added to OP_RETURN metadata to identify deposit requests
magic_bytes = "alpn"Then save and close the file. Now the CLI is ready to use.
How to use
The CLI is your entrypoint for interacting with Alpen.
Run alpen --help to display the help message. If you're using a newer version, the output might be slightly different.
Usage: alpen <command> [<args>]
A CLI for interacting with Alpen and the underlying bitcoin (signet) network
Options:
--help display usage information
Commands:
recover Attempts a recovery of old deposit transactions
drain Drains the internal wallet to the provided signet or Alpen
address
balance Prints the wallet's current balance(s)
backup Prints a BIP39 mnemonic encoding the internal wallet's seed
bytes
deposit Deposits 10 BTC from signet into Alpen
withdraw Withdraws 10 BTC from Alpen to signet
faucet Requests BTC from the faucet
send Sends BTC from the internal wallet
receive Prints a new address for the internal wallet
change-password Changes the seed's encryption password
reset DANGER: resets the CLI completely, destroying all keys and
databases. Keeps config.
scan Performs a full scan of the signet wallet
config Prints the location of the CLI's TOML config fileThe CLI is composed of multiple commands. You can append --help to any command to get more details about what the command does and what arguments it supports.
Available via commands are a bitcoin signet wallet and an EVM-compatible Alpen wallet, allowing you to use Alpen without any other tools. For example, the CLI can help you deposit into and withdraw BTC from Alpen via the deposit and withdraw commands, respectively.
The first time you make a command in the CLI, you will be asked to create a new password to encrypt the wallet's secret. If you're using Windows or macOS, alpen will store the encrypted secret in the operating system's keychain. On Linux, it is stored in a file in the user's home directory.
Backup your wallet
Before you start, you should make sure to backup your wallet.
Usage: alpen backup [--language <language>]
Prints a BIP39 mnemonic encoding the internal wallet's seed bytes
Options:
--language select a language for the BIP39 mnemonic. defaults to
English. options: en, cn, cn-trad, cz, fr, it, jp, kr or es
--help display usage informationKeep this backup safe; your funds will be lost if you lose it. Don't reset a wallet when you have deposit transactions that haven't either been received on Alpen yet or recovered, as the database that stores recovery information is separate to your seed, and it will be very difficult to recover those funds.
When you restore your wallet, make sure to run alpen scan so the CLI can find all your previous funds. This process can take some time, depending on how many UTXOs you have.
Request BTC
Alpen uses a custom signet where Alpen Labs is the only miner. We have a faucet that you can request BTC from via the CLI.
Usage: alpen faucet [<address>]
Requests BTC from the faucet
Positional Arguments:
address address that funds will be sent to. defaults to internal
wallet address
Options:
--help display usage informationTo receive ~10 BTC to test, run this command. If you haven't created a wallet yet, this will prompt you for a password to encrypt a new one.
alpen faucetOur signet has block time of 10 minutes, similar to the average block time on bitcoin mainnet. After requesting funds from the faucet, you can check if they have arrived by viewing the recent transactions in the signet explorer.
Check your balance
Usage: alpen balance <network_type>
Prints the wallet's current balance(s)
Positional Arguments:
network_type either "signet" or "alpen"
Options:
--help display usage informationDeposit BTC into Alpen
After you have more than 10 BTC, you can make a deposit into Alpen.
Usage: alpen deposit [<alpen_address>] [--fee-rate <fee-rate>]
Deposits 10 BTC from signet into Alpen
Positional Arguments:
alpen_address the Alpen address to deposit the funds into. defaults to the
wallet's internal address
Options:
--fee-rate override signet fee rate in sat/vbyte. must be >=1
--help display usage informationTo deposit 10 BTC from the internal signet wallet into the internal Alpen wallet, run this command.
alpen depositIf the funds are not available in your Alpen wallet (check using alpen balance alpen) after 1,008 signet blocks, you can run the recover command to perform an autorecovery.
Withdraw BTC back to signet
To withdraw BTC from your Alpen wallet to a signet address, use the following command. If an address is provided, it must be a P2TR address. If an address isn't provided, the CLI will send to an unused signet address from its own wallet. As with the deposit, the withdrawal amount must be exactly 10 BTC.
Usage: alpen withdraw [<p2tr_address>]
Withdraws 10 BTC from Alpen to signet
Positional Arguments:
p2tr_address the signet address to send funds to. defaults to a new
internal wallet address
Options:
--help display usage informationSend BTC
You can send BTC from the internal signet or Alpen wallet via the alpen send command. Use the fee-rate option to override the automatically determined fee rate. If you want to drain your wallet, see the drain command.
Usage: alpen send <network_type> <amount> <address> [--fee-rate <fee-rate>]
Sends BTC from the internal wallet.
Positional Arguments:
network_type either "signet" or "alpen"
amount amount to send in sats
address address to send to
Options:
--fee-rate override signet fee rate in sat/vbyte. must be >=1
--help display usage informationReceive BTC
You can generate an address for receiving BTC using the receive command. For the Alpen wallet, this will always return the same address. The Alpen wallet creates an EVM-compatible externally owned account (EOA) with the following BIP44 derivation path: m/44'/60'/0'/0/0.
The signet wallet will print a different address every time, which is a BIP-86 P2TR address.
Usage: alpen receive <network_type>
Prints a new address for the internal wallet
Positional Arguments:
network_type either "signet" or "alpen"
Options:
--help display usage informationChange wallet password
The change-password command will load your existing seed, decrypt it, and then prompt you for a new password, encrypt the seed with the new password, and overwrite the old encrypted seed.
Usage: alpen change-password
Changes the seed's encryption password
Options:
--help display usage informationDrain the wallet
If you want to send all of your funds to a single address. To do this, run the alpen drain command.
Signet funds can only be drained to another signet address, and Alpen funds can only be drained to another Alpen address. This command will not implicitly deposit/withdraw funds between the two wallets.
Usage: alpen drain [-s <signet-address>] [-r <alpen-address>] [--fee-rate <fee-rate>]
Drains the internal wallet to the provided signet and Alpen addresses
Options:
-s, --signet-address
a signet address for signet funds to be drained to
-r, --alpen-address
a Alpen address for Alpen funds to be drained to
--fee-rate override signet fee rate in sat/vbyte. must be >=1
--help display usage informationRecover
To recover any failed/expired deposit transactions, use the recover command.
Recovery of failed deposit transactions can be made 1,008 signet blocks after the deposit transaction was confirmed. With a 10 minute block time, that's about 1 week.
Usage: alpen recover
Attempts a recovery of old deposit transactions
Options:
--help display usage informationScan your wallet
The scan command scans the signet for coins belonging to the internal wallet. This should be used after restoring from a BIP-39 mnemonic.
Usage: alpen scan
Performs a full scan of the signet wallet
Options:
--help display usage informationConfiguration
The CLI uses a TOML file for configuration. This is for advanced users only.
To find your config file location, run alpen config. You can then open this file in an editor. You may only change the keys listed in the file if you want to use alternatives to the defaults provided.
Last updated