Skip to content

Commit e101efd

Browse files
tanut32039Tanut Lertwarachai
tanut32039
and
Tanut Lertwarachai
authored
Add document (#16)
* add doc * update installation * update * fix by comment * fix by comment * fix doc * refac doc * fix quote * fix space * del private_key --------- Co-authored-by: Tanut Lertwarachai <tanutlertwarachai@Tanuts-MacBook-Pro.local>
1 parent cc9e9af commit e101efd

File tree

2 files changed

+312
-1
lines changed

2 files changed

+312
-1
lines changed

‎README.md

+291-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,293 @@
11
# Falcon
22

3-
TBD
3+
<div align="center">
4+
5+
![logo](logo.svg)
6+
7+
</div>
8+
9+
**Disclaimer:** This project is still in its early stages of development and is considered a prototype. Please refrain from using it in production.
10+
11+
`Falcon` is a CLI program designed for smart contract developers to relay data from the [Tunnel](https://github.com/bandprotocol/chain/tree/master/x/tunnel) on BandChain to their target blockchain seamlessly.
12+
13+
# Table Of Contents
14+
- [Components](#components)
15+
- [Flow](#flow)
16+
- [Getting Started](#getting-started)
17+
18+
---
19+
## Components
20+
### 1. BandChain Client
21+
- Queries tunnel information.
22+
- Queries packet data and EVM signatures for verification in the TSS verifier.
23+
24+
### 2. Chain Provider
25+
Intermediary between the relayer application and the target blockchain. It encapsulates all logic required to interact with a specific type of blockchain, such as Ethereum Virtual Machine (EVM)-based chains, and abstracts the details of blockchain operations like transaction creation, execution, querying, and validation.
26+
(At this moment, only EVM chains are supported.)
27+
- Keys Manipulation
28+
- Manages key operations such as adding, deleting, listing, and securely storing them.
29+
- Transaction Creation
30+
- Constructs calldata for packet relaying.
31+
- Dynamically calculates gas fees for both EIP-1559 and Legacy transactions.
32+
- Transaction Execution
33+
- Signs transactions using keys from the senders pool.
34+
- Broadcasts transactions to the blockchain.
35+
- Verifies transaction success with a receipt check.
36+
37+
### 3. Scheduler
38+
- Executes tasks for each `TunnelRelayer` periodically.
39+
- Penalizes failing tasks with an exponential backoff.
40+
- Synchronizes with BandChain periodically to ensure that Falcon keeps all tunnels aligned and up-to-date with BandChain.
41+
42+
### 4. Tunnel Relayer
43+
- Fetches tunnel information and packet by `BandChain Client` and `Chain Provider`
44+
- Handles the packet relaying process
45+
- Validates tunnel state (e.g., active status, latest sequence).
46+
- Fetches unrelayed packets from BandChain.
47+
- Submit packet to `Chain Provider` to continue on transaction process.
48+
49+
50+
---
51+
## Flow
52+
### 1. Initialization
53+
- Initializes Tunnel Relayers
54+
- Fetches tunnel information from BandChain and target chains.
55+
- Validates the provider and loads keys into the sender channel.
56+
- Validates Passphrase
57+
- Checks if the user-provided passphrase matches the stored hash to ensure security.
58+
- Starts Scheduler
59+
- Scheduler manages periodic relaying tasks for all initialized `TunnelRelayer` instances.
60+
61+
### 2. Starting Scheduler
62+
The Scheduler starts execution ticker and tunnel synchronization ticker based on the given configuration, and handles penalized tasks resulting from consecutive relay packet failures.
63+
- Periodic Execution
64+
- Asynchronously triggers each `TunnelRelayer` instances to check [(3.)](#3-checking-packets) and relay [(4.)](#4-relaying-packets) the packet and confirm transaction [(5.)](#5-confirming-transaction).
65+
- Tunnels synchronization
66+
- Updates tunnel information from BandChain to ensure that Falcon keeps all tunnels aligned and up-to-date with BandChain.
67+
- Handling penalty task
68+
- Retries failed tasks after waiting for a penalty duration, which is calculated using exponential backoff.
69+
70+
### 3. Checking Packets
71+
- Checks Tunnel State
72+
- Queries tunnel information from BandChain and the target chain.
73+
- Validates if the target chain's tunnel is active and ensures sequence consistency.
74+
- Determine Next Packet
75+
- Compares the LatestSequence on the BandChain and the target chain.
76+
- Identifies packets that have not yet been relayed.
77+
78+
### 4. Relaying Packets
79+
- Validate Connection
80+
- Ensures the chain client is connected.
81+
- Retry Logic
82+
- Attempts to relay the packet up to `max_retry` times.
83+
If all attempts fail, logs the error and move this task to penalty task.
84+
- #### 4.1 Create Transaction
85+
- Fetch the sender's nonce to ensure transaction order.
86+
- Calculate Gas Limit by using a pre-configured limit or dynamically estimate it based on transaction parameters.
87+
- Set Fees by GasPrice for legacy transactions or BaseFee + PriorityFee for EIP-1559 transactions.
88+
- #### 4.2 Sign Transaction
89+
- Sign the transactionby the sender's private key to sign the transaction with the chosen signer
90+
- EIP155Signer for legacy transactions.
91+
- LondonSigner for EIP-1559 transactions.
92+
- #### 4.3 Broadcast Transaction
93+
- Send the transaction to the target chain.
94+
### 5. Confirming Transaction
95+
- Fetch the transaction receipt and check its status and block confirmations to ensure success.
96+
- Continuously check the transaction status within a specified duration. If the transaction remains unconfirmed for too long, mark it as unmined and handle it accordingly.
97+
- If the transaction fails, adjust the gas by using `GasMultiplier` and retry to relay packet again
98+
99+
---
100+
## Getting Started
101+
**Note:** This guide assumes that the program runs on a Linux environment.
102+
### 1. Node Installation
103+
104+
#### 1.1 Node Configuration
105+
- make, gcc, g++ (can be obtained from the build-essential package on linux)
106+
- wget, curl for downloading files
107+
108+
``` shell
109+
# install required tools
110+
sudo apt-get update && \
111+
sudo apt-get upgrade -y && \
112+
sudo apt-get install -y build-essential curl wget jq
113+
```
114+
- Install Go 1.22.3
115+
```shell
116+
# Install Go 1.22.3
117+
wget https://go.dev/dl/go1.22.3.linux-amd64.tar.gz
118+
tar xf go1.22.3.linux-amd64.tar.gz
119+
sudo mv go /usr/local/go
120+
121+
# Set Go path to $PATH variable
122+
echo "export PATH=$PATH:/usr/local/go/bin:~/go/bin" >> $HOME/.profile
123+
source ~/.profile
124+
```
125+
Go binary should be at /usr/local/go/bin and any executable compiled by go install command should be at ~/go/bin
126+
127+
#### 1.2: Clone & Install Falcon
128+
``` shell
129+
cd ~
130+
# Clone Falcon
131+
git clone https://github.com/bandprotocol/falcon
132+
cd falcon
133+
134+
# Install binaries to $GOPATH/bin
135+
make install
136+
```
137+
138+
### 2. Set passphrase
139+
In Falcon, the passphrase serves as an **encryption key** for securing sensitive data.
140+
- The passphrase can be set in one of the following ways:
141+
- As an environment variable via a `.env` file.
142+
``` shell
143+
PASSPHRASE=secret
144+
```
145+
- Passed inline with commands that require it.
146+
``` shell
147+
PASSPHRASE=secret falcon ...
148+
```
149+
- Some commands require the passphrase to:
150+
- Validate its correctness when performing operations like managing keys.
151+
- Initialize and encrypt configuration files for the program.
152+
- If no passphrase is provided, it defaults to an empty string `""`.
153+
154+
### 3. Initialize the configuration directory/file
155+
``` shell
156+
falcon config init
157+
```
158+
- The passphrase will be init after this command, it will become your program's permanent passphrase and cannot be changed. Please check that you set the correct passphrase during this step.
159+
160+
- Default config directory: `~/.falcon/config`
161+
162+
- By default, config will be initialized in format like this
163+
```toml
164+
[global]
165+
log_level = 'info'
166+
checking_packet_interval = 60000000000
167+
max_checking_packet_penalty_duration = 3600000000000
168+
penalty_exponential_factor = 1.0
169+
170+
[bandchain]
171+
rpc_endpoints = ['http://localhost:26657']
172+
timeout = 3000000000
173+
174+
[target_chains]
175+
176+
```
177+
178+
179+
To customize the config for relaying, you can use custom config file and use the `--file` flag when initializing the configuration.
180+
```
181+
falcon config init --file custom_config.toml
182+
```
183+
184+
### 4. Configure target chains you want to relay
185+
You need to create a chain configuration file to add it to the configuration. Currently, only EVM chains are supported.
186+
<br/> Example:
187+
``` toml
188+
endpoints = ['http://localhost:8545']
189+
chain_type = 'evm'
190+
max_retry = 3
191+
query_timeout = 3000000000
192+
chain_id = 31337
193+
tunnel_router_address = '0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9'
194+
block_confirmation = 5
195+
waiting_tx_duration = 3000000000
196+
checking_tx_interval = 1000000000
197+
gas_type = 'eip1559'
198+
gas_multiplier = 1.1
199+
execute_timeout = 3000000000
200+
liveliness_checking_interval = 900000000000
201+
```
202+
203+
The supported `gas_type` values are `legacy` and `eip1559`. Each type requires specific configuration fields.
204+
- `legacy`
205+
- `max_gas_price` defines the maximum gas price.
206+
- If `max_gas_price` is not specified, it will be retrieved from the tunnel router.
207+
- `eip1559`
208+
- `max_base_fee` defines the maximum base fee.
209+
- `max_priority_fee` defines the maximum priority fee.
210+
- If `max_priority_fee` is not defined, it will also be retrieved from the tunnel router
211+
212+
``` shell
213+
falcon chains add testnet chain_config.toml
214+
```
215+
216+
### 5. Check target chain's activeness
217+
To relay packets to the target chain, you need to ensure that the tunnel on the target chain is active. This can be checked using
218+
``` shell
219+
falcon query tunnel <TUNNEL_ID>
220+
```
221+
222+
223+
### 6. Import OR create new keys to use when signing and relaying transactions.
224+
>Please ensure that you are using the correct passphrase that was set during initialization for the `add`, `delete`, and `export` commands.
225+
</br>
226+
227+
If you need to generate a new key, use the `add` subcommand.
228+
``` shell
229+
falcon keys add testnet testkey
230+
```
231+
232+
There are 3 options for user to add key
233+
```
234+
Choose how to add a key
235+
> Private key (provide an existing private key)
236+
Mnemonic (recover from an existing mnemonic phrase)
237+
Generate new address (no private key or mnemonic needed)
238+
```
239+
240+
If you already have a private key and want to retrive key from it, you can choose `Private key` option.
241+
```
242+
Enter your private key
243+
>
244+
```
245+
246+
If you already have a mnemonic and want to retrive key from it, you can choose `Mnemonic` option.
247+
```
248+
Enter your mnemonic
249+
>
250+
251+
Enter a coin type
252+
Coin type number for HD derivation (default: 60; leave empty to use default)
253+
>
254+
255+
Enter an account
256+
Account number in the HD derivation path (default: 0; leave empty to use default)
257+
>
258+
259+
Enter an index
260+
Index number for the specific address within an account in the HD derivation path (default: 0; leave empty to use default)
261+
>
262+
```
263+
264+
If you want to generate a new address, choose the `Generate new address` option.
265+
```
266+
Enter a coin type
267+
Coin type number for HD derivation (default: 60; leave empty to use default)
268+
>
269+
270+
Enter an account
271+
Account number in the HD derivation path (default: 0; leave empty to use default)
272+
>
273+
274+
Enter an index
275+
Index number for the specific address within an account in the HD derivation path (default: 0; leave empty to use default)
276+
>
277+
```
278+
279+
### 7. Check that the keys for the configured chains are funded
280+
281+
You can query the balance of each configured key by running:
282+
``` shell
283+
falcon q balance testkey
284+
```
285+
### 8. Start to relay packet
286+
Starts all tunnels that `falcon query tunnels` can query
287+
``` shell
288+
falcon start
289+
```
290+
> NOTE: You can choose which tunnels do you want to relay.
291+
``` shell
292+
falcon start 1 2 3
293+
```

0 commit comments

Comments
 (0)