{"id":42254616,"url":"https://github.com/bandprotocol/falcon","last_synced_at":"2026-01-27T05:18:36.485Z","repository":{"id":267742863,"uuid":"871122712","full_name":"bandprotocol/falcon","owner":"bandprotocol","description":"An open-source project for relaying tunnel messages with cryptographic signatures powered by Bandtss module.","archived":false,"fork":false,"pushed_at":"2026-01-14T07:11:11.000Z","size":1194,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-14T10:55:43.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bandprotocol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-11T10:10:53.000Z","updated_at":"2026-01-06T06:30:00.000Z","dependencies_parsed_at":"2026-01-14T09:02:12.829Z","dependency_job_id":null,"html_url":"https://github.com/bandprotocol/falcon","commit_stats":null,"previous_names":["bandprotocol/falcon"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bandprotocol/falcon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Ffalcon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Ffalcon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Ffalcon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Ffalcon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bandprotocol","download_url":"https://codeload.github.com/bandprotocol/falcon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Ffalcon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28803650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T03:44:14.111Z","status":"ssl_error","status_checked_at":"2026-01-27T03:43:33.507Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-27T05:18:35.964Z","updated_at":"2026-01-27T05:18:36.478Z","avatar_url":"https://github.com/bandprotocol.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Falcon\n\n\u003cdiv align=\"center\"\u003e\n\n![logo](logo.svg)\n\n\u003c/div\u003e\n\n**Disclaimer:** This project is still in its early stages of development and is considered a prototype. Please refrain from using it in production.\n\n`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.\n\n# Table Of Contents\n- [Components](#components)\n- [Flow](#flow)\n- [Getting Started](#getting-started)\n\n---\n## Components \n### 1. BandChain Client\n- Queries tunnel information.\n- Queries packet data and EVM signatures for verification in the TSS verifier.\n\n### 2. Chain Provider\nIntermediary 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.\n(At this moment, only EVM chains are supported.)\n- Keys Manipulation\n  - Manages key operations such as adding, deleting, listing, and securely storing them.\n- Transaction Creation \n  - Constructs calldata for packet relaying.\n  - Dynamically calculates gas fees for both EIP-1559 and Legacy transactions.\n- Transaction Execution\n  - Signs transactions using keys from the senders pool.\n  - Broadcasts transactions to the blockchain. \n  - Verifies transaction success with a receipt check.\n\n### 3. Scheduler\n- Executes tasks for each `TunnelRelayer` periodically.\n- Penalizes failing tasks with an exponential backoff.\n- Synchronizes with BandChain periodically to ensure that Falcon keeps all tunnels aligned and up-to-date with BandChain.\n\n### 4. Tunnel Relayer\n- Fetches tunnel information and packet by `BandChain Client` and `Chain Provider`\n- Handles the packet relaying process\n  - Validates tunnel state (e.g., active status, latest sequence).\n  - Fetches unrelayed packets from BandChain.\n  - Submit packet to `Chain Provider` to continue on transaction process.\n\n\n---\n## Flow\n### 1. Initialization\n- Initializes Tunnel Relayers\n  - Fetches tunnel information from BandChain and target chains.\n  - Validates the provider and loads keys into the sender channel.\n- Validates Passphrase \n  - Checks if the user-provided passphrase matches the stored hash to ensure security. \n- Starts Scheduler\n  - Scheduler manages periodic relaying tasks for all initialized `TunnelRelayer` instances.\n\n### 2. Starting Scheduler\nThe Scheduler starts execution ticker and tunnel synchronization ticker based on the given configuration, and handles penalized tasks resulting from consecutive relay packet failures.\n- Periodic Execution\n  - 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).\n- Tunnels synchronization\n  - Updates tunnel information from BandChain to ensure that Falcon keeps all tunnels aligned and up-to-date with BandChain.\n- Handling penalty task\n  - Retries failed tasks after waiting for a penalty duration, which is calculated using exponential backoff.\n\n### 3. Checking Packets\n- Checks Tunnel State\n  - Queries tunnel information from BandChain and the target chain.\n  - Validates if the target chain's tunnel is active and ensures sequence consistency.\n- Determine Next Packet\n  - Compares the LatestSequence on the BandChain and the target chain.\n  - Identifies packets that have not yet been relayed.\n\n### 4. Relaying Packets \n- Validate Connection \n  - Ensures the chain client is connected.\n- Retry Logic \n  - Attempts to relay the packet up to `max_retry` times.\n    If all attempts fail, logs the error and move this task to penalty task.\n- #### 4.1 Create Transaction\n  - Fetch the sender's nonce to ensure transaction order.\n  - Calculate Gas Limit by using a pre-configured limit or dynamically estimate it based on transaction parameters.\n  - Set Fees by GasPrice for legacy transactions or BaseFee + PriorityFee for EIP-1559 transactions.\n- #### 4.2 Sign Transaction\n  - Sign the transactionby the sender's private key to sign the transaction with the chosen signer \n    - EIP155Signer for legacy transactions.\n    - LondonSigner for EIP-1559 transactions.\n- #### 4.3 Broadcast Transaction \n  - Send the transaction to the target chain.\n### 5. Confirming Transaction\n- Fetch the transaction receipt and check its status and block confirmations to ensure success.\n- 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.\n- If the transaction fails, adjust the gas by using `GasMultiplier` and retry to relay packet again\n\n---\n## Getting Started\n**Note:** This guide assumes that the program runs on a Linux environment.\n### 1. Node Installation\n\n#### 1.1 Node Configuration\n- make, gcc, g++ (can be obtained from the build-essential package on linux)\n- wget, curl for downloading files\n\n``` shell\n# install required tools\nsudo apt-get update \u0026\u0026 \\\nsudo apt-get upgrade -y \u0026\u0026 \\\nsudo apt-get install -y build-essential curl wget jq\n```\n- Install Go 1.24.2\n```shell\n# Install Go 1.24.2\nwget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz\ntar xf go1.24.2.linux-amd64.tar.gz\nsudo mv go /usr/local/go\n\n# Set Go path to $PATH variable\necho \"export PATH=$PATH:/usr/local/go/bin:~/go/bin\" \u003e\u003e $HOME/.profile\nsource ~/.profile\n```\nGo binary should be at /usr/local/go/bin and any executable compiled by go install command should be at ~/go/bin\n\n#### 1.2: Clone \u0026 Install Falcon\n``` shell\ncd ~\n# Clone Falcon\ngit clone https://github.com/bandprotocol/falcon\ncd falcon\n\n# Install binaries to $GOPATH/bin\nmake install\n```\n\n### 2. Set passphrase \nIn Falcon, the passphrase serves as an **encryption key** for securing sensitive data.\n- The passphrase can be set in one of the following ways:\n  - As an environment variable via a `.env` file.\n    ``` shell\n    PASSPHRASE=secret\n    ```\n  - Passed inline with commands that require it.\n    ``` shell\n    PASSPHRASE=secret falcon ...\n    ```\n- Some commands require the passphrase to:\n  - Validate its correctness when performing operations like managing keys.\n  - Initialize and encrypt configuration files for the program.\n- If no passphrase is provided, it defaults to an empty string `\"\"`.\n\n### 3. Initialize the configuration directory/file\n``` shell\nfalcon config init\n```\n- 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.\n\n- Default config directory: `~/.falcon/config`\n\n- By default, config will be initialized in format like this \n```toml\n[global]\nlog_level = 'info'\nchecking_packet_interval = 60000000000\nsync_tunnels_interval = 300000000000\npenalty_skip_rounds = 3\nmetrics_listen_addr = ''\n\n[bandchain]\nrpc_endpoints = ['http://localhost:26657']\ntimeout = 3000000000\n\n[target_chains]\n\n```\n\n\nTo customize the config for relaying, you can use custom config file and use the `--file` flag when initializing the configuration.\n```\nfalcon config init --file custom_config.toml\n```\n\n### 4. Configure target chains you want to relay\nYou need to create a chain configuration file to add it to the configuration. Currently, only EVM chains are supported.\n\u003cbr/\u003e Example:\n``` toml\nendpoints = ['http://localhost:8545']\nchain_type = 'evm'\nmax_retry = 3\nquery_timeout = 3000000000\nchain_id = 31337\ntunnel_router_address = '0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9'\nblock_confirmation = 5\nwaiting_tx_duration = 3000000000\nchecking_tx_interval = 1000000000\ngas_type = 'eip1559'\ngas_multiplier = 1.1\nexecute_timeout = 3000000000\nliveliness_checking_interval = 900000000000\n```\n\nThe supported `gas_type` values are `legacy` and `eip1559`. Each type requires specific configuration fields.\n- `legacy`\n  - `max_gas_price` defines the maximum gas price.\n  - If `max_gas_price` is not specified, it will be retrieved from the tunnel router.\n- `eip1559`\n  - `max_base_fee` defines the maximum base fee.\n  - `max_priority_fee` defines the maximum priority fee.\n   - If `max_priority_fee` is not defined, it will also be retrieved from the tunnel router\n\n``` shell\nfalcon chains add testnet chain_config.toml\n```\n\n### 5. Check target chain's activeness\nTo relay packets to the target chain, you need to ensure that the tunnel on the target chain is active. This can be checked using\n``` shell\nfalcon query tunnel \u003cTUNNEL_ID\u003e\n```\n\n\n### 6. Import OR create new keys to use when signing and relaying transactions.\n\u003ePlease ensure that you are using the correct passphrase that was set during initialization for the `add`, `delete`, and `export` commands.\n\u003c/br\u003e\n\nIf you need to generate a new key, use the `add` subcommand.\n``` shell\nfalcon keys add testnet testkey\n```\n\nThere are 3 options for user to add key \n```\nChoose how to add a key\n\u003e Private key (provide an existing private key)\n  Mnemonic (recover from an existing mnemonic phrase)\n  Generate new address (no private key or mnemonic needed)\n```\n\nIf you already have a private key and want to retrieve key from it, you can choose `Private key` option. \n```\nEnter your private key\n\u003e\n```\n\nIf you already have a mnemonic and want to retrieve key from it, you can choose `Mnemonic` option. \n```\nEnter your mnemonic\n\u003e\n\nEnter a coin type \nCoin type number for HD derivation (default: 60; leave empty to use default)\n\u003e\n\nEnter an account \nAccount number in the HD derivation path (default: 0; leave empty to use default)\n\u003e\n\nEnter an index\nIndex number for the specific address within an account in the HD derivation path (default: 0; leave empty to use default)\n\u003e \n```\n\nIf you want to generate a new address, choose the `Generate new address` option.\n```\nEnter a coin type \nCoin type number for HD derivation (default: 60; leave empty to use default)\n\u003e\n\nEnter an account \nAccount number in the HD derivation path (default: 0; leave empty to use default)\n\u003e\n\nEnter an index\nIndex number for the specific address within an account in the HD derivation path (default: 0; leave empty to use default)\n\u003e \n```\n\n### 7. Check that the keys for the configured chains are funded\n\nYou can query the balance of each configured key by running:\n``` shell\nfalcon q balance testkey\n```\n### 8. Start to relay packet\nStarts all tunnels that `falcon query tunnels` can query\n``` shell\nfalcon start\n```\n\u003e NOTE: You can choose which tunnels do you want to relay.\n``` shell\nfalcon start 1 2 3\n```\n\n## Generate Go Protobuf Code\nFalcon uses gRPC and Protocol Buffers for its internal APIs.\nIf you modify any `.proto` files under the `proto/` directory, regenerate the Go code by running:\n\n```sh\nmake proto\n```\n\n## Database\n### Setup SQL database \n  - As an environment variable via a `.env` file.\n    ``` shell\n    DB_PATH=postgresql://user:password@localhost:5432/mydatabase\n    ```\n  - Passed inline with commands that require it.\n    ``` shell\n    export DB_PATH=postgresql://user:password@localhost:5432/mydatabase\n    ```\n\n### Migrating SQL database \n#### Install\n```sh\ngo install github.com/pressly/goose/v3/cmd/goose@latest\n# Ensure GOBIN (or $(go env GOPATH)/bin) is on your PATH\n```\n\n#### Run \n\u003e Use `-dir` before the driver/DSN.\n\u003e Supported drivers: `postgres`, `sqlite`.\n\n##### Up (apply all pending)\n```sh \n# Postgres\ngoose -dir relayer/db/migrations/postgres postgres \"postgres://user:password@localhost:5432/falcon?sslmode=disable\" up\n\n# SQLite\ngoose -dir relayer/db/migrations/sqlite sqlite \"gorm.db\" up\n```\n\n##### Down (revert one step)\n```sh \n# Postgres\ngoose -dir relayer/db/migrations/postgres postgres \"postgres://user:password@localhost:5432/falcon?sslmode=disable\" down\n\n# SQLite\ngoose -dir relayer/db/migrations/sqlite sqlite \"gorm.db\" down\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandprotocol%2Ffalcon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbandprotocol%2Ffalcon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandprotocol%2Ffalcon/lists"}