Limits the fraction of the total reserve that may be withdrawn within the trailing
24-hour period
[default: 0.04]
```
Tweaking these parameters is a decision that requires careful thought. A future release will integrate these circuit breaker checks into the protocol itself.
# IBC Relayer
Running an IBC relayer for Nomic works mostly the same as with other Cosmos chains, but with a few caveats:
1. Currently, Nomic is only compatible with [Hermes](https://hermes.informal.systems) and does not support the ibc-go relayer.
2. Hermes must be configured with a custom proof spec. Please see the example configuration below.
## 1. Configure Hermes
Here's an example Hermes configuration relaying between a local Nomic and Osmosis node:
# ~/.hermes/config.toml
[[chains]]
id = 'nomic-stakenet-3'
rpc_addr = 'http://127.0.0.1:26657'
event_source = { mode = 'pull' }
grpc_addr = 'http://127.0.0.1:9001'
rpc_timeout = '10s'
account_prefix = 'nomic'
key_name = 'testkey'
store_prefix = 'ibc'
max_gas = 40000000
gas_price = { price = 0.001, denom = 'stake' }
clock_drift = '20s'
proof_specs = '''
[
{
"inner_spec": {
"child_order": [
0,
1,
2
],
"child_size": 32,
"empty_child": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"min_prefix_length": 1,
"max_prefix_length": 1,
"hash": 6
},
"leaf_spec": {
"hash": 6,
"prehash_key": 0,
"prehash_value": 0,
"length": 4,
"prefix": "AA"
},
"max_depth": 0,
"min_depth": 0
},
{
"inner_spec": {
"child_order": [
0
],
"child_size": 32,
"empty_child": "",
"min_prefix_length": 0,
"max_prefix_length": 0,
"hash": 6
},
"leaf_spec": {
"hash": 6,
"prehash_key": 0,
"prehash_value": 0,
"length": 0,
"prefix": ""
},
"max_depth": 0,
"min_depth": 0
}
]
'''
[[chains]]
id = 'osmosis-1'
rpc_addr = 'http://127.0.0.1:26757'
grpc_addr = 'http://127.0.0.1:9090'
websocket_addr = 'ws://127.0.0.1:26757/websocket'
rpc_timeout = '10s'
account_prefix = 'osmo'
key_name = 'osmosis'
address_type = { derivation = 'cosmos' }
store_prefix = 'ibc'
default_gas = 5000000
max_gas = 15000000
gas_price = { price = 0.0026, denom = 'uosmo' }
gas_multiplier = 1.1
max_msg_num = 20
max_tx_size = 209715
clock_drift = '20s'
max_block_time = '10s'
trusting_period = '10days'
trust_threshold = { numerator = '1', denominator = '3' }
[chains.packet_filter]
policy = 'allow'
list = [
['transfer', 'channel-5555'], # nomic-stakenet-3
]
The `proof_specs` and `event_source` fields for Nomic are the main differences to note for those otherwise familiar with IBC relaying with Hermes.
Please refer to the [Hermes docs](https://hermes.informal.systems) for more information.
## 2. Run gRPC server
Nomic features a gRPC server to support IBC relaying, which implements only the minimum set of gRPC methods required by Hermes. The server does not run by default, and must be run in a separate process with:
```bash
# default port 9001
nomic grpc
```
or:
```bash
nomic grpc
```
## 3. Fund relayer with nBTC
Fees for IBC transactions are paid with nBTC (1 sat per tx). After you've configured your relayer, you'll need to fund its Nomic account (`hermes keys list --chain nomic-stakenet-3` to see the address) with nBTC.
## 4. (Optional) Relay operator keys
To ensure that nBTC is recoverable by the remote chain's validator set in the event of an Emergency Disbursal, run:
```bash
nomic relay-op-keys
```
This command may be re-run anytime to refresh the operator keys of the remote chain's validator set. If an Emergency Disbursal occurs on Nomic, a portion of the Bitcoin reserves equal to the nBTC held in channels backed by the specified client will become spendable by 2/3+ of the voting power of that network's top 30 validators.
## Other notes
Below are a couple other notes to keep in mind, given Nomic's custom IBC implementation.
### Channel ports
For channels supporting token transfers, the Nomic channel port **must** be `transfer`. ICS 20 is the only application-layer standard currently supported by Nomic:
```bash
hermes create channel --a-chain osmosis-1 --b-chain nomic-stakenet-3 --a-port transfer --b-port transfer --new-client-connection
```
### Manual clearing
Typically, the main Hermes process (`hermes start`) will properly relay packets between Nomic and its counterparty. However, if it seems like an event has been missed by Hermes, packets can be manually cleared (bidirectionally) with:
```bash
hermes clear packets --chain nomic-stakenet-3 --port transfer --channel channel-1
```
# Bitcoin Relayer
Relayer nodes carry data between the Bitcoin blockchain and the Nomic blockchain. You can help support the health of the network by running a Bitcoin node alongside your Nomic node and running the relayer process.
### 1. Sync a Bitcoin node
Download Bitcoin Core:
Run it with:
```bash
# mainnet
bitcoind -server -rpcuser=satoshi -rpcpassword=nakamoto
# testnet
bitcoind -server -testnet -rpcuser=satoshi -rpcpassword=nakamoto
```
{% hint style="info" %}
**NOTE:** To save on disk space, you may want to configure your Bitcoin node to prune block storage. For instance, add `-prune=5000` to only keep a maximum of 5000 MB of blocks. You may also want to use the `-daemon` option to keep the node running in the background.
{% endhint %}
### 2. Run the relayer process
```bash
# mainnet
nomic relayer --rpc-port=8332 --rpc-user=satoshi --rpc-pass=nakamoto
# testnet
nomic relayer --rpc-port=18332 --rpc-user=satoshi --rpc-pass=nakamoto
```
Leave this running - the relayer will constantly scan the Bitcoin and Nomic chains and broadcast relevant data.
The relayer will also create a server which listens on port 9000 for clients to announce their deposit addresses. To help make the network more reliable, if you run a relayer please open this port and add your node's address in a Github issue so clients can make use of your node. If you're going to make this service public, putting the server behind an HTTP reverse proxy is recommended for extra safety.
# Key Management
When running a node, care must be put into handling the various keys to ensure they are not lost or leaked.
If your node is in the validator set or signatory set, you have an important responsibility to keep signing so that the network can remain live. Also, if these keys are stolen the security of the bridge is at risk.
## List of Keys
* **Consensus key (validators)**
* `~/.nomic-stakenet-3/tendermint/config/prev_validator_key.json`
* Used to sign blocks on the Nomic blockchain.
* **Signatory key (signatories)**
* `~/.nomic-stakenet-3/signer/xpriv`
* Used to sign Bitcoin transactions for the bridge.
* **Wallet key (all nodes)**
* `~/.orga-wallet/privkey`
* Used to sign transactions created through the Nomic CLI (declaring a validator, transferring tokens, etc.)
*On testnet, the path will instead start with `~/.nomic-testnet-4d`*
## Backing Up
It is important to make backups of these keys, since losing them can be hard to recover from.
When backing up, ensure your keys are copied somewhere other than where you run your nodes - preferably on an offline machine, encrypted with a passphrase, or stored on other medium not vulnerable to malware such as paper.
## Migrating Validator Nodes
Sometimes it is necessary to move your keys to a different machine to start operating your node there. When you do this, make sure to transfer all the keys as listed above into their respective paths.
Additionally, make sure to transfer `~/.nomic-stakenet-3/tendermint/data/priv_validator_state.json`. This file ensures your node will not accidentally cause a double-sign, which is a slashable offense that will jail your validator.
# Listing in Codebase
If running a reliable node or relayer, you can help the network by listing them in the network config files so that others can automatically connect.
* Add public RPC URL(s) with port (preferably an HTTPS URL, which may require using a reverse proxy) to `state_sync_rpc`
* Add your Tendermint peer id (found in the `/status` RPC endpoint) and IP with port to `--p2p.seeds` in `tendermint_flags`
* If running a Bitcoin relayer, add the URL (preferably an HTTPS URL, which may require using a reverse proxy) to `btc_relayer`
## Stakenet
For Stakenet please make a GitHub issue or PR to the below file:
{% @github-files/github-code-block url="" %}
## Testnet
For Stakenet please make a GitHub issue or PR to the below file:
{% @github-files/github-code-block url="" %}
# Integrating nBTC via IBC
IBC is a blockchain interoperability protocol used by 110+ chains. This page gives a high-level overview of how to integrate nBTC into any IBC-compatible chain.
## Prerequisites
As a prerequisite, follow the instructions to configure an [IBC relayer](/network/ibc-relayer) to work with Nomic. IBC transactions require the relayer account to be funded with a small amount of nBTC, as IBC-related transactions are charged a fee of 1 Satoshi each.
## Creating a channel
Once `hermes` is [configured for Nomic](/network/ibc-relayer), the next step is to create an IBC channel with Nomic.
```bash
hermes create channel --a-chain --b-chain nomic-stakenet-3 --a-port
transfer --b-port transfer --new-client-connection
```
Nomic currently requires both ends of the channel to use the "transfer" port.
## Relaying operator keys
To ensure that nBTC is recoverable by the remote chain's validator set in the event of an Emergency Disbursal, run:
```bash
nomic relay-op-keys
```
This command may be re-run anytime to refresh the operator keys of the remote chain's validator set. If an Emergency Disbursal occurs on Nomic, a portion of the Bitcoin reserves equal to the nBTC held in channels backed by the specified client will become spendable by 2/3+ of the voting power of that network's top 30 validators.
## Interchain Deposits
Interchain Deposits allow the generation of Bitcoin addresses which commit to an ICS-20 token transfer packet, automatically forwarding any received funds to an address on the counterparty chain.
Interchain Deposits require communication with a [Bitcoin relayer](/network/bitcoin-relayer). The set of relayers used by your front-end should be selected with care.
After a channel has been opened between your chain and Nomic, see [`nomic-bitcoin-js`](https://www.npmjs.com/package/nomic-bitcoin) for information on generating and displaying deposit addresses.
### Withdrawals to Bitcoin
nBTC may be withdrawn as Bitcoin directly from the counterparty chain. ICS-20 transfer packets support a `memo` field. Providing a memo of the form "withdraw:\" for an incoming nBTC transfer packet to Nomic will trigger a withdrawal of the Bitcoin to `` at the next checkpoint. `` may be either:
1. A Bech32 Bitcoin address.
2. A hex-encoded Bitcoin script.
# Integrating nBTC on EVM
Nomic supports bridging Bitcoin to EVM-based chains.
## Contract Addresses
Nomic's decentralized custody bridging contract can be found at the following contract addresses:
nBTC on EVM-based chains is issued as an ERC-20 token at the following contract addresses:
Additional network contract addresses will be listed on here in the future, as well as documentation for creating your own customizable deployments in any EVM environment.
## Interchain Deposits
Interchain Deposits allow the generation of Bitcoin addresses which commit to a destination on an EVM-based chain, automatically forwarding any received funds as nBTC to a contract on that chain.
The EVM destination may be either:
* an Ethereum address to receive the nBTC;
* a contract call to be executed with the received nBTC.
Interchain Deposits require communication with [Bitcoin relayers](/network/bitcoin-relayer). The set of relayers used by your front-end should be selected with care.
See [`nomic-bitcoin-js`](https://www.npmjs.com/package/nomic-bitcoin) for more information on generating and displaying Bitcoin deposit addresses.
### Withdrawing to Bitcoin
Bitcoin may be withdrawn to a Bitcoin address directly via contract calls on EVM-based chains.
First, `approve` must be called on the token contract (see above table):
```typescript
web3.eth.abi.encodeFunctionCall({
name: 'approve',
type: 'function',
inputs: [
{
type: 'address',
name: 'spender'
},
{
type: 'uint256',
name: 'amount'
}
]
}, [tokenContractAddress, usatAmount]);
```
Next, initiate the withdrawal to a Bitcoin address with a call to the bridge contract:
import { buildDestination } from 'nomic-bitcoin'
let destination = buildDestination({
bitcoinAddress: 'tb1...'
})
web3.eth.abi.encodeFunctionCall({
name: 'sendToNomic',
type: 'function',
inputs: [
{
type: 'address',
name: '_tokenContract'
},
{
type: 'string',
name: '_destination'
},
{
type: 'uint256',
name: '_amount'
}
]
}, [tokenContractAddress, destination, usatAmount]);
# Emergency Disbursal
## Introduction
In the event of an extended liveness failure, for example, downtime caused by a bug or an attack, funds in typical custody systems and bridges remain inaccessible for an indefinite amount of time. The funds are stuck until the issue is resolved and signatories manually intervene, leaving depositors with no recourse.
Nomic protects against this by including an Emergency Disbursal mechanism, making user funds accessible even during a liveness failure.
## Mechanism
The Emergency Disbursal is conceptually simple: the network produces and signs timelocked Bitcoin transactions each time a new checkpoint transaction is made. If the next checkpoint confirms on the Bitcoin network, the UTXOs spent by the previous checkpoint transactions are now spent by the checkpoint. This invalidates the old Emergency Disbursal which is now atomically replaced by the new one.
### Transaction Structure
Nomic periodically moves funds in “[checkpoint transaction](broken://spaces/wouPLII4HXZ3uzgba1H6/pages/7MddoYvV6rxwIZWq4dGe#how-it-works)s”, which result in a “reserve output” that contains a pool of funds held in decentralized custody. The Emergency Disbursal makes up a tree of transactions: a set of “final transactions”, each including a large set of outputs to the recipients of the Emergency Disbursal and a single input, and a single “intermediate transaction” with outputs corresponding to the inputs of final transactions and a single input spending from the reserve output.
Outputs are split across multiple final transactions because of size constraints - Bitcoin’s default policies limit transactions to 100,000 virtual bytes. Assuming there are 100,000 accounts on the network, and each of these accounts receive a pay-to-pubkey-hash UTXO (34 bytes each), this would require over 3.4M vbytes of transaction data (a small amount of additional space is required for the base transaction fields and the inputs). This structure could then be made up of about 36 transactions, 1 intermediate transaction which directly spends the reserve output and has 35 outputs, and 35 transactions which spend outputs from the intermediate transaction and pay out to many P2PKH outputs (one for each account).
All final transactions and the intermediate transaction include a timelock at a timestamp in the future based on some parameter - e.g., two weeks. Since Bitcoin signatures commit to the inputs they spend, signed emergency disbursals will automatically be invalidated as soon as a newer checkpoint happens since it will spend the same reserve UTXO and become confirmed before the emergency disbursal unlocks.
For atomicity in moving the funds to a new checkpoint, the network first coordinates signing of the next checkpoint’s Emergency Disbursal transactions before advancing to the signatures for the checkpoint transaction. This ensures that if a liveness failure happens during the signing process, it is guaranteed that the most recently confirmed checkpoint has valid and signed Emergency Disbursal transactions spending from it.
### Fees
In order to pay for the high cost of Bitcoin network fees for the Emergency Disbursal transactions to be included in blocks, the proper fee amounts based on the network’s last known fee levels and the transaction and witness sizes are deducted from final transaction outputs. This cost is shared across all outputs, and results in any accounts which have too small of a balance to pay their share of the fee being pruned and becoming wholly paid into the shared fee.
In the event the Emergency Disbursal transactions pay too low of a fee and are not being confirmed in blocks, the transactions can be fee-bumped collectively by any recipients of final transactions if they simply spend their (unconfirmed) outputs with a high fee rate. Bitcoin mempools use the child-pays-for-parent fee rules meaning any recipient can help contribute additional fees to the network’s Emergency Disbursal transactions.
### Outputs
To convert onchain accounts into recipients of the Emergency Disbursal, we have to derive a Bitcoin script for each to include in a transaction output. Depending on the type of account, there are different ways to build Bitcoin scripts which can be spent by the intended user.
#### nBTC on Nomic
Native accounts on the Nomic chain each have an optional “recovery script” which can be set by the user at any point, to define the output script for their emergency disbursal payouts. The user simply has to pick a destination address and input it in their Nomic protocol client (e.g. [app.nomic.io](https://app.nomic.io/bitcoin)). Each new Emergency Disbursal will include an output with their latest recovery script and balance.
In the future, the protocol could potentially derive an output for all accounts, even those that do not set a recovery script. This is possible because Nomic account address hashes and keys are compatible with Bitcoin script (`ripemd160`, `sha256`, and `secp256k1`).
#### nBTC on Remote IBC Chains
If funds have been moved over a channel to a remote IBC chain based on Tendermint or CometBFT consensus, the Nomic network needs a different way to reason about paying out via the Emergency Disbursal. Instead of paying to individual users, since their balances may change and are not known on the Nomic chain, a multisig wallet is constructed instead, made from the keys of the top 40 validators.
To power IBC, the Nomic network already accepts relayed proofs of the current validator set of the remote chain. The validator set gets retained in the state, and additional proofs about the remote chain’s state are accepted in order to relay and verify the validator’s `secp256k1` operator keys. This process can happen automatically by third-party relayer nodes which carry data between both networks.
In the future, it could be possible to create an IBC standard to allow remote protocols, contracts, and users to set their own recovery scripts and have their balances tracked by the Nomic protocol to include individuals as recipients outside of the chain-wide multisig. However, care must be taken since this could mean there would be a short time where a user can hold a balance which is not currently reflected in the most recently created Emergency Disbursal transactions.
#### nBTC on Ethereum/EVM
On Ethereum, nBTC is deployed as an ERC-20 token representing BTC. For its Emergency Disbursal scheme, accounts can opt to set a recovery script, similar to native Nomic accounts. Once opted-in, transfers to and from the user will result in a call to the Nomic decentralized custody contract's `setEmergencyDisbursalBalance` function, queueing up a message to be relayed to the Nomic protocol which updates the user’s output in the next Emergency Disbursal.
Note that unlike native Nomic accounts, this system does not reflect users’ balance changes into their Emergency Disbursal output until the next checkpoint update. However, this is only a temporary condition (at most, a period of hours but often a period of minutes) - nBTC transfers can be considered to have “soft finality” when the ERC-20 token transfer confirms on Ethereum, and “hard finality” once signed into a Nomic checkpoint.
#### Decentralized Custody Contracts on EVM
On EVM-based networks, usage of the Nomic network happens via bridge contracts deployed by different projects that opt to use Nomic’s decentralized BTC custody. These consumers of the bridge contract can arbitrarily assign the BTC they hold into Emergency Disbursal outputs at any time via the `setEmergencyDisbursalBalance(bytes script, u64 amount)` contract call.
This means that consumers of Nomic’s decentralized custody can choose their own paradigm for updating the Emergency Disbursal payouts for their users - a necessary flexibility since contracts could represent relationships more complex than simple user accounts (for instance, the BTC may be collateral in a loan, or be in a DAO-owned treasury).