From 0130ed7a2d8811642da45dea6a915743b36840d2 Mon Sep 17 00:00:00 2001 From: nkitlabs Date: Sat, 26 Apr 2025 01:25:02 +0700 Subject: [PATCH 1/5] draft falcon doc --- .../04-falcon/01-what-is-falcon.md | 22 +++++ .../04-falcon/02-falcon-architecture.md | 42 ++++++++ .../04-falcon/03-getting-start.md | 98 +++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md create mode 100644 docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md create mode 100644 docs/develop/03-developer-tools/04-falcon/03-getting-start.md diff --git a/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md b/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md new file mode 100644 index 0000000..c564b43 --- /dev/null +++ b/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md @@ -0,0 +1,22 @@ +# What is Falcon? + +:::warning + +We are excited to announce that Band V3 is currently under development! + +During this period, you may encounter intermittent updates, changes, and limited availability as we work to enhance its features and performance. + +We appreciate your patience and understanding as we aim to deliver a robust and improved testing experience. Stay tuned for more updates and release information! + +::: + +**Falcon** is a lightweight, reliable relay program designed to bridge data between a [tss-tunnel system](../../../data-tunnel/route-types/01-tss.md) and a designated target smart contract. It acts as a data relayer, ensuring timely and secure delivery of critical information generated by a decentralized threshold signature scheme (TSS) network to its corresponding consumer on-chain. + +--- + +## 🚀 Purpose + +Falcon’s core responsibility is to: + +1. **Periodically Retrieve** data output from the `tss-tunnel` (typically price feeds, tss signatures, or other consensus outputs) and the current states of the target contract predefined on the tss tunnel. +2. **Relay** the data to a target smart contract on a blockchain network and charge a relay fee from the contract's account. diff --git a/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md b/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md new file mode 100644 index 0000000..c0edc9d --- /dev/null +++ b/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md @@ -0,0 +1,42 @@ +# Falcon Architecture + +There are 5 main components + +1. BandChain Client + - Provide query client for retrieving tunnel information and packet information. + +2. Chain Provider + - Abstract level of keys management + - Manages key operations such as adding, deleting, listing related keys. + - Transaction Creation + - Constructs calldata for packet relaying. + - Dynamically calculates gas fees for both EIP-1559 and Legacy transactions. + - Transaction Execution + - Broadcasts transactions to the blockchain. + - Verifies transaction success with a receipt check. + +3. Scheduler + - Execute tasks for each tunnel relayer periodically. + - Synchronize with BandChain periodically to fetch new tunnel (if it is in all-tss-tunnel mode). + +4. Tunnel Relayer + - Fetche tunnel information and packet by BandChain Client and chain provider + - Handle the packet relaying process + - Validate tunnel state (e.g., active status, latest sequence). + - Fetche unrelayed packets from BandChain client. + - Submit packet to chain provider to continue on transaction process. + +5. Wallet + - Manage keys store. + - Signs transactions using keys from the senders pool. + + +## ⚙️ How It Works + +1. **Connect to BandChain**: Falcon connects to the BandChain to poll a new data from tss tunnel. +2. **Connect to Destination Chain**: Falcon connects to the destination chain to retrieve current state and packet sequence of the target contract associated with the TSS tunnel. +3. **Retrieve Data**: Falcon fetches the next-sequence packet required by the target contract from BandChain. +4. **Contract Interaction**: Using a pre-configured RPC endpoint and wallet key, Falcon submits a transaction containing the relevant data to the target smart contract. +5. **Retry & Logging**: Falcon supports automatic retries on failure and logs all relayed events for traceability. + + diff --git a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md new file mode 100644 index 0000000..4810942 --- /dev/null +++ b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md @@ -0,0 +1,98 @@ +# Getting Starts with Falcon + +If this is the first time you start the falcon service, run the following + +1. Initialize the Falcon configuration file. + ```shell + $ PASSPHRASE=$YOUR_PASSPHRASE falcon config init + ``` + + Passphrase will be used when it interacts with keys manangement. + + Default config will be at: `~/.falcon/config/config.toml`. By default, config will be initialized in format like this + ```toml + [global] + log_level = 'info' + checking_packet_interval = 60000000000 + max_checking_packet_penalty_duration = 3600000000000 + penalty_exponential_factor = 1.0 + + [bandchain] + rpc_endpoints = ['http://localhost:26657'] + timeout = 3000000000 + + [target_chains] + + ``` + + + To customize the config for relaying, you can use custom config file and use the `--file` flag when initializing the configuration. + ```shell + falcon config init --file custom_config.toml + ``` + +2. Configure target chains + You need to create a chain configuration file with the format below in order to add it to the Falcon's configuration. Currently, Falcon only supports EVM chain. + + Example: + ``` toml + endpoints = ['http://localhost:8545'] + chain_type = 'evm' + max_retry = 3 + query_timeout = 3000000000 + chain_id = 31337 + tunnel_router_address = '0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9' + block_confirmation = 5 + waiting_tx_duration = 3000000000 + checking_tx_interval = 1000000000 + gas_type = 'eip1559' + gas_multiplier = 1.1 + execute_timeout = 3000000000 + liveliness_checking_interval = 900000000000 + ``` + + The supported `gas_type` values are **legacy** and **eip1559**. Each type requires specific configuration fields. + - **legacy** + - `max_gas_price` defines the maximum gas price. If `max_gas_price` is not specified, it will be retrieved from the tunnel router. + - **eip1559** + - `max_base_fee` defines the maximum base fee. + - `max_priority_fee` defines the maximum priority fee. If `max_priority_fee` is not defined, it will also be retrieved from the tunnel router + + After creating a chain configuraiton file, run with the following commands + ``` shell + falcon chains add $CHAIN_NAME $CHAIN_CONFIG_FILE + ``` + + `$CHAIN_NAME` should be matched with the one predefined in the tss-tunnel. + + You can check if falcon can connect to both BandChain and destination via query tunnel information using following command + ``` shell + falcon query tunnel + ``` + +3. Import or Create keys + + If you need to create a new key into the system, run the following command. + ``` shell + PASSPHRASE=$YOUR_PASSPHRASE falcon keys add $CHAIN_NAME $KEY_NAME + ``` + + The command is interactive, user can either adding keys via importing private key or mnemonic, or user can generate a new private key specifically for relaying a transaction. + + To avoid command interaction, user can manually run the command with specific flag for key creation. + + You can query the balance of each configured key by running: + ``` shell + PASSPHRASE=$YOUR_PASSPHRASE falcon q balance $CHAIN_NAME $KEY_NAME + ``` + +4. Start Falcon + Starts the Falcon to relay every tss-tunnel by running the following command + ``` shell + falcon start + ``` + + Falcon can relay the data from only specific tss tunnels, the following is an example of how to run Falcon to relay only tunnel ID 1, 2, and 3 + ``` shell + falcon start 1 2 3 + ``` From 94271336ce0b4d55109c73a09975d0de3f6d990c Mon Sep 17 00:00:00 2001 From: nkitlabs Date: Sat, 26 Apr 2025 01:28:29 +0700 Subject: [PATCH 2/5] add _category_.json and fix wording --- docs/develop/03-developer-tools/04-falcon/03-getting-start.md | 4 +++- docs/develop/03-developer-tools/04-falcon/_category_.json | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 docs/develop/03-developer-tools/04-falcon/_category_.json diff --git a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md index 4810942..61f1101 100644 --- a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md +++ b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md @@ -1,5 +1,7 @@ # Getting Starts with Falcon +## Prerequisite + If this is the first time you start the falcon service, run the following 1. Initialize the Falcon configuration file. @@ -86,7 +88,7 @@ If this is the first time you start the falcon service, run the following PASSPHRASE=$YOUR_PASSPHRASE falcon q balance $CHAIN_NAME $KEY_NAME ``` -4. Start Falcon +## Start Falcon Starts the Falcon to relay every tss-tunnel by running the following command ``` shell falcon start diff --git a/docs/develop/03-developer-tools/04-falcon/_category_.json b/docs/develop/03-developer-tools/04-falcon/_category_.json new file mode 100644 index 0000000..8f1da2b --- /dev/null +++ b/docs/develop/03-developer-tools/04-falcon/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Falcon", + "position": 4 +} From 9e902815b78480b7d95c7c891e46dda24fd23d5f Mon Sep 17 00:00:00 2001 From: Natthakun Date: Tue, 1 Jul 2025 12:48:55 +0700 Subject: [PATCH 3/5] fix typos --- docs/develop/03-developer-tools/04-falcon/03-getting-start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md index 61f1101..0cdd067 100644 --- a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md +++ b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md @@ -9,7 +9,7 @@ If this is the first time you start the falcon service, run the following $ PASSPHRASE=$YOUR_PASSPHRASE falcon config init ``` - Passphrase will be used when it interacts with keys manangement. + Passphrase will be used when it interacts with keys management. Default config will be at: `~/.falcon/config/config.toml`. By default, config will be initialized in format like this ```toml @@ -60,7 +60,7 @@ If this is the first time you start the falcon service, run the following - `max_base_fee` defines the maximum base fee. - `max_priority_fee` defines the maximum priority fee. If `max_priority_fee` is not defined, it will also be retrieved from the tunnel router - After creating a chain configuraiton file, run with the following commands + After creating a chain configuration file, run with the following commands ``` shell falcon chains add $CHAIN_NAME $CHAIN_CONFIG_FILE ``` From 2b2dd2eaf8c55af6f87cbf07900cd6952508a583 Mon Sep 17 00:00:00 2001 From: Natthakun Date: Thu, 3 Jul 2025 13:12:50 +0700 Subject: [PATCH 4/5] fix from comments --- .../04-falcon/02-falcon-architecture.md | 4 ++-- .../04-falcon/03-getting-start.md | 17 +++++++++-------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md b/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md index c0edc9d..02730e8 100644 --- a/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md +++ b/docs/develop/03-developer-tools/04-falcon/02-falcon-architecture.md @@ -20,10 +20,10 @@ There are 5 main components - Synchronize with BandChain periodically to fetch new tunnel (if it is in all-tss-tunnel mode). 4. Tunnel Relayer - - Fetche tunnel information and packet by BandChain Client and chain provider + - Fetch tunnel information and packet by BandChain Client and chain provider - Handle the packet relaying process - Validate tunnel state (e.g., active status, latest sequence). - - Fetche unrelayed packets from BandChain client. + - Fetch unrelayed packets from BandChain client. - Submit packet to chain provider to continue on transaction process. 5. Wallet diff --git a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md index 0cdd067..a13ad4c 100644 --- a/docs/develop/03-developer-tools/04-falcon/03-getting-start.md +++ b/docs/develop/03-developer-tools/04-falcon/03-getting-start.md @@ -2,11 +2,11 @@ ## Prerequisite -If this is the first time you start the falcon service, run the following +If this is the first time you start Falcon service, run the following -1. Initialize the Falcon configuration file. +1. Initialize the Falcon configuration file (if you leave the passphrase unset, it defaults to ""). ```shell - $ PASSPHRASE=$YOUR_PASSPHRASE falcon config init + $PASSPHRASE=$YOUR_PASSPHRASE Falcon config init ``` Passphrase will be used when it interacts with keys management. @@ -16,12 +16,13 @@ If this is the first time you start the falcon service, run the following [global] log_level = 'info' checking_packet_interval = 60000000000 - max_checking_packet_penalty_duration = 3600000000000 - penalty_exponential_factor = 1.0 + sync_tunnel_interval = 300000000000 + penalty_skip_rounds = 3 [bandchain] rpc_endpoints = ['http://localhost:26657'] timeout = 3000000000 + liveliness_checking_interval=60000000000 [target_chains] @@ -42,15 +43,15 @@ If this is the first time you start the falcon service, run the following chain_type = 'evm' max_retry = 3 query_timeout = 3000000000 + execute_timeout = 3000000000 chain_id = 31337 tunnel_router_address = '0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9' block_confirmation = 5 waiting_tx_duration = 3000000000 + liveliness_checking_interval = 900000000000 checking_tx_interval = 1000000000 gas_type = 'eip1559' gas_multiplier = 1.1 - execute_timeout = 3000000000 - liveliness_checking_interval = 900000000000 ``` The supported `gas_type` values are **legacy** and **eip1559**. Each type requires specific configuration fields. @@ -67,7 +68,7 @@ If this is the first time you start the falcon service, run the following `$CHAIN_NAME` should be matched with the one predefined in the tss-tunnel. - You can check if falcon can connect to both BandChain and destination via query tunnel information using following command + You can check if Falcon can connect to both BandChain and destination via query tunnel information using following command ``` shell falcon query tunnel ``` From d8cfeeb2466ab572274399cbfc80435cf54b41cc Mon Sep 17 00:00:00 2001 From: Natthakun Date: Thu, 17 Jul 2025 14:57:02 +0700 Subject: [PATCH 5/5] remove warning --- .../03-developer-tools/04-falcon/01-what-is-falcon.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md b/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md index c564b43..13edd61 100644 --- a/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md +++ b/docs/develop/03-developer-tools/04-falcon/01-what-is-falcon.md @@ -1,15 +1,5 @@ # What is Falcon? -:::warning - -We are excited to announce that Band V3 is currently under development! - -During this period, you may encounter intermittent updates, changes, and limited availability as we work to enhance its features and performance. - -We appreciate your patience and understanding as we aim to deliver a robust and improved testing experience. Stay tuned for more updates and release information! - -::: - **Falcon** is a lightweight, reliable relay program designed to bridge data between a [tss-tunnel system](../../../data-tunnel/route-types/01-tss.md) and a designated target smart contract. It acts as a data relayer, ensuring timely and secure delivery of critical information generated by a decentralized threshold signature scheme (TSS) network to its corresponding consumer on-chain. ---