{"id":20186477,"url":"https://github.com/palomachain/pigeon","last_synced_at":"2025-04-06T21:15:13.436Z","repository":{"id":37482401,"uuid":"478535094","full_name":"palomachain/pigeon","owner":"palomachain","description":"Pigeon software is run by Paloma validators to send messages to any public blockchain","archived":false,"fork":false,"pushed_at":"2024-10-24T19:18:01.000Z","size":1880,"stargazers_count":44,"open_issues_count":5,"forks_count":40,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-25T08:28:53.220Z","etag":null,"topics":["blockchain","crosschain","messaging","multichain"],"latest_commit_sha":null,"homepage":"https://palomachain.com","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/palomachain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-06T11:45:29.000Z","updated_at":"2024-10-24T19:18:05.000Z","dependencies_parsed_at":"2022-07-09T14:46:20.561Z","dependency_job_id":"558c6cd0-7ff8-4221-b44f-d6b0958c44f5","html_url":"https://github.com/palomachain/pigeon","commit_stats":{"total_commits":362,"total_committers":17,"mean_commits":"21.294117647058822","dds":0.7016574585635359,"last_synced_commit":"4c30bd48cc723ad52acb9698bf28f3c856104607"},"previous_names":["palomachain/sparrow"],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palomachain%2Fpigeon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palomachain%2Fpigeon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palomachain%2Fpigeon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palomachain%2Fpigeon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/palomachain","download_url":"https://codeload.github.com/palomachain/pigeon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247550690,"owners_count":20956987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["blockchain","crosschain","messaging","multichain"],"created_at":"2024-11-14T03:17:24.205Z","updated_at":"2025-04-06T21:15:13.410Z","avatar_url":"https://github.com/palomachain.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e Pigeon \u003c/h1\u003e\n    \u003cimg alt=\"Paloma\" src=\"https://github.com/palomachain/pigeon/blob/master/assets/paloma.png\" /\u003e\n\u003c/div\u003e\n\n\u003e A Golang cross-chain message relayer system\n\u003e for Paloma validators to deliver messages to any blockchain.\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/palomachain/pigeon/blob/master/LICENSE\"\u003e\n    \u003cimg alt=\"License: Apache-2.0\" src=\"https://img.shields.io/github/license/palomachain/pigeon.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/palomachain/pigeon\"\u003e\n    \u003cimg src=\"https://pkg.go.dev/badge/github.com/palomachain/pigeon.svg\" alt=\"Go Reference\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/palomachain/pigeon\"\u003e\n    \u003cimg alt=\"Go report card\" src=\"https://goreportcard.com/badge/github.com/palomachain/pigeon\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/palomachain/pigeon/blob/master/.github/workflows/ci-test.yml\"\u003e\n    \u003cimg alt=\"Code Coverage\" src=\"https://github.com/palomachain/pigeon/actions/workflows/ci-test.yml/badge.svg?branch=master\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/palomachain/pigeon/blob/master/.github/workflows/release.yml\"\u003e\n    \u003cimg alt=\"Code Coverage\" src=\"https://github.com/palomachain/pigeon/actions/workflows/release.yml/badge.svg?branch=master\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\nFor Crosschain software engineers that want simultaneous control of multiple smart contracts, on any blockchain, Paloma is decentralized and consensus-driven message delivery, fast state awareness, low cost state computation, and powerful attestation system that enables scalable, crosschain, smart contract execution with any data source.\n\n## Table of Contents\n\n- [Talk To Us](#talk-to-us)\n- [Releases](#releases)\n- [Active Networks](#active-networks)\n- [Issues](#issues)\n- [Install](#install)\n\n## Talk to us\n\nWe have active, helpful communities on Twitter and Telegram.\n\n- [Twitter](https://twitter.com/paloma_chain)\n- [Telegram](https://t.me/palomachain)\n- [Discord](https://discord.gg/HtUvgxvh5N)\n- [Forum](https://forum.palomachain.com/)\n\n## Releases\n\nSee [Release procedure](CONTRIBUTING.md#release-procedure) for more information about the release model.\n\n## Active Networks\n\n- Paloma Testnest `paloma-testnet-16` (May 23, 2024)\n- Paloma Mainnet `tumbler` (April 22, 2024)\n- Arbitrum Mainnet (relay)\n- Base Mainnet (relay)\n- Blast Mainnet (relay)\n- Binance Smart Chain Mainnet (relay)\n- Ethereum Mainnet (relay)\n- Gnosis Mainnet (relay)\n- Optimism Mainnet (relay)\n- Polygon Mainnet (relay)\n\n## ISSUES\n\nThis repo does not accept issues. Please use \u003chttps://github.com/palomachain/paloma/issues\u003e to submit issues and add pigeon label!\n\n## Install\n\n**If you are upgrading from a prior tesntet confirm that you added the `health-check-port: 5757` to your pigeon yaml configuration file and upgrade the paloma chain-id field to `paloma-testnet-16` for Testnet or `tumbler` for Mainnet (see example below).**\n\n\u003e #### Note\n\u003e\n\u003e If you're joining while testnet didn't boot up yet you may see a log line saying `not staking. waiting`. That's OK.\n\u003e If you see this after the chains starts producing blocks, then it means that your validator has been jailed.\n\n\u003e #### Note\n\u003e\n\u003e Some have seen errors with GLIBC version differences with the downloaded binaries.  This is caused by a difference in the libraries of the host that built the binary and the host running the binary.\n\u003e\n\u003e If you experience these errors, please pull down the code and build it, rather than downloading the prebuilt binary\n\n### To get the latest prebuilt `pigeon` binary\n\n```shell\nwget -O - https://github.com/palomachain/pigeon/releases/download/v2.3.4/pigeon_Linux_x86_64.tar.gz  | \\\n  sudo tar -C /usr/local/bin -xvzf - pigeon\nsudo chmod +x /usr/local/bin/pigeon\n\nmkdir ~/.pigeon\n```\n\n### To build pigeon using latest\n\n\u003e [!IMPORTANT]  \n\u003e Always make sure you're building against the latest released version of Go.\n\n```shell\ngit clone https://github.com/palomachain/pigeon.git\ncd pigeon\ngit checkout v2.3.4\nmake build\nsudo mv ./build/pigeon /usr/local/bin/pigeon\n\nmkdir ~/.pigeon\n```\n\nIf you're upgrading to the most recent version, you will need to stop `pigeond` before removing the old binary and copying the new binary into place.\n\n## Set up your EVM Keys. Don't forget your passwords\n\n### Create a new key\n\nEthereum Mainnet (eth-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/eth-main\n```\n\nBinance Smart Chain Mainnet (bnb-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/bnb-main\n```\n\nPolygon Mainnet (matic-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/matic-main\n```\n\nOptimism Mainnet (op-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/op-main\n```\n\nBase Mainnet (base-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/base-main\n```\n\nArbitrum Mainnet (arbitrum-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/arbitrum-main\n```\n\nGnosis Mainnet (gnosis-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/gnosis-main\n```\n\nBlast Mainnet (blast-main)\n\n```\npigeon evm keys generate-new ~/.pigeon/keys/evm/blast-main\n```\n\n### or import existing you existing Ethereum evm private keys\n\nEthereum Mainnet (eth-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/eth-main\n```\n\nBinance Smart Chain Mainnet (bnb-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/bnb-main\n```\n\nPolygon Mainnet (matic-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/matic-main\n```\n\nOptimism Mainnet (op-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/op-main\n```\n\nBase Mainnet (base-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/base-main\n```\n\nArbitrum Mainnet (arbitrum-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/arbitrum-main\n```\n\nGnosis Mainnet (gnosis-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/gnosis-main\n```\n\nBlast Mainnet (blast-main)\n\n```\npigeon evm keys import ~/.pigeon/keys/evm/blast-main\n```\n\n### Config setup\n\n**IMPORTANT VALIDATOR NOTE:** `gas-adjustment` is important in your pigeon settings. The gas adjustment values in the example below are set to ensure that your relay is able to increase gas required during periods of high congestion on the target chain. We propose that for `tx-type: 2`, `gas-adjustment` is set to `2` except for `bnb-main` chain. However, given that Paloma assigns messages based on pigeon performance, make sure your gas adjustment for each target chain maximizes your message delivery, while minimizing your relay costs.\n\n#### Paloma supported chains on `tumbler` mainnet as of January 5, 2024\n\nValidators joining the Paloma network for the first time will need to fund the minimum onchain gas-fee balances to be included in the validator set. All validators must support all chains for relaying. All validators must maintain the minimum balance required for each target chain. Below are the list of supported chains and their minimums.\n\n| Chain Name    | Paloma Chain-ID | Native Token | Minimum Balance Required | Governance Proposal|\n| ------------- | --------------- |------------- |-------------- |---------------- |\n| BNB Chain / Binance Smart Chain |bnb-main | BNB  | 0.005 BNB  | [PIP 27 - Paloma Mainnet Support for BNB Chain](https://paloma.explorers.guru/proposal/9) |\n| Ethereum  | eth-main  | ETH  | 0.005 ETH  | [PIP 28 - Paloma Compass-EVM and Mainnet Support for Ethereum Mainnet](https://paloma.explorers.guru/proposal/10)|\n| Polygon MATIC  | matic-main  | MATIC  | 0.005 MATIC  | [PIP 34 - Paloma Messenger Mainnet Validator Support for Polygon Mainnet](https://paloma.explorers.guru/proposal/15)|\n| Optimism  | op-main  | ETH  | 0.005 ETH  | [PIP 36 - Paloma Mainnet Support for Optimistic EVM blockchain, Optimism](https://paloma.explorers.guru/proposal/22)|\n| Base  | base-main  | ETH  | 0.001 ETH  | [PIP 37 - Paloma Mainnet Support for Base EVM blockchain](https://paloma.explorers.guru/proposal/23)|\n| Gnosis  | base-main  | xDAI  | 10 xDAI  | [PIP 46 - Paloma Mainnet Support for Gnosis EVM blockchain](https://paloma.explorers.guru/proposal/36)|\n| Arbitrum  | arbitrum-main  | ETH  | 0.005 ETH  | [PIP 52 - Paloma Mainnet Support for Arbitrum EVM blockchain](https://paloma.explorers.guru/proposal/43)|\n| BLAST  | blast-main  | ETH  | 0.005 ETH  | [PIP-55 - Paloma Messenger Support for BLAST!](https://paloma.explorers.guru/proposal/46)|\n\n#### Configuration updates\n\nPlease make sure you restart Pigeon after making changes to your configuration files for the updates to come into effect.\n\nMake sure your Paloma Cosmos-SDK keys are stored and available on your environment.\n\n`palomad keys add \"$VALIDATOR\" --recover`\n\nSet the VALIDATOR env variable\n\n`export VALIDATOR=\"$(palomad keys list --list-names | head -n1)\"`\n\nCreate configuration file here `~/.pigeon/config.yaml`\n\n```yaml\nloop-timeout: 5s\nhealth-check-port: 5757\n\npaloma:\n  chain-id: tumbler\n  call-timeout: 20s\n  keyring-dir: ~/.paloma\n  keyring-pass-env-name: PALOMA_KEYRING_PASS\n  keyring-type: os\n  validator-key: ${VALIDATOR}\n  base-rpc-url: http://localhost:26657\n  gas-adjustment: 10.0\n  gas-prices: 0.001ugrain\n  account-prefix: paloma\n\nevm:\n  eth-main:\n    chain-id: 1\n    base-rpc-url: ${ETH_RPC_URL}\n    keyring-pass-env-name: ETH_PASSWORD\n    signing-key: ${ETH_SIGNING_KEY}\n    keyring-dir: ~/.pigeon/keys/evm/eth-main\n    gas-adjustment: 2\n    tx-type: 2\n\n  bnb-main:\n    chain-id: 56\n    base-rpc-url: ${BNB_RPC_URL}\n    keyring-pass-env-name: BNB_PASSWORD\n    signing-key: ${BNB_SIGNING_KEY}\n    keyring-dir: ~/.pigeon/keys/evm/bnb-main\n    gas-adjustment: 1\n    tx-type: 0\n\n  matic-main:\n    chain-id: 137\n    base-rpc-url: ${MATIC_RPC_URL}\n    keyring-pass-env-name: MATIC_PASSWORD\n    signing-key: ${MATIC_SIGNING_KEY}\n    keyring-dir: ~/.pigeon/keys/evm/matic-main\n    gas-adjustment: 2\n    tx-type: 2\n  \n  op-main:\n    chain-id: 10\n    base-rpc-url: ${OP_RPC_URL}\n    keyring-pass-env-name: OP_PASSWORD\n    signing-key: ${OP_SIGNING_KEY}\n    keyring-dir: /root/.pigeon/keys/evm/op-main\n    gas-adjustment: 2\n    tx-type: 2\n\n  base-main:\n    chain-id: 8453\n    base-rpc-url: ${BASE_RPC_URL}\n    keyring-pass-env-name: BASE_PASSWORD\n    signing-key: ${BASE_SIGNING_KEY}\n    keyring-dir: /root/.pigeon/keys/evm/base-main\n    gas-adjustment: 2\n    tx-type: 2\n\n  arbitrum-main:\n    chain-id: 42161\n    base-rpc-url: ${ARB_RPC_URL}\n    keyring-pass-env-name: ARB_PASSWORD\n    signing-key: ${ARB_SIGNING_KEY}\n    keyring-dir: /root/.pigeon/keys/evm/arbitrum-main\n    gas-adjustment: 2\n    tx-type: 2\n\n gnosis-main:\n    chain-id: 100\n    base-rpc-url: ${GNOSIS_RPC_URL}\n    keyring-pass-env-name: GNOSIS_PASSWORD\n    signing-key: ${GNOSIS_SIGNING_KEY}\n    keyring-dir: /root/.pigeon/keys/evm/gnosis-main\n    gas-adjustment: 2\n    tx-type: 2\n\n  blast-main:\n    chain-id: 81457\n    base-rpc-url: ${BLAST_RPC_URL}\n    keyring-pass-env-name: BLAST_PASSWORD\n    signing-key: ${BLAST_SIGNING_KEY}\n    keyring-dir: ~/.pigeon/keys/evm/blast-main\n    gas-adjustment: 2\n    tx-type: 2\n```\n\n#### Support for multiple signing keys\n\nBy default, Pigeon will use your validator key to sign any transactions sent to Paloma. In high throughput environments, this may lead to `account sequence mismatch` errors.\nIt's possible to define more than one signing key to be used in rotation to combat this issue. In order to do so, you will need to create a number of new keys and register them with Pigeon like this:\n\n```bash\n# First, create a number of new keys. You may create an arbitrary amount of keys.\npalomad keys add pigeon-operator-alpha\npalomad keys add pigeon-operator-bravo\npalomad keys add pigeon-operator-charlie\n\n# Second, your new addresses will need to receive an active feegrant from your validator address.\n# This step is very important. It's not enough to simply fund those addresses manually.\n# The active feegrant is considered a \"permission\" to send transactions from your validator address\".\npalomad tx feegrant grant $VALIDATOR_ADDRESS $(palomad keys show pigeon-operator-alpha-$(hostname) -a) --fees 500ugrain -y\npalomad tx feegrant grant $VALIDATOR_ADDRESS $(palomad keys show pigeon-operator-bravo-$(hostname) -a) --fees 500ugrain -y\npalomad tx feegrant grant $VALIDATOR_ADDRESS $(palomad keys show pigeon-operator-charlie-$(hostname) -a) --fees 500ugrain -y\n```\n\nAfter creating your signing keys, all you need to do is register them with Pigeon by adding the following to your pigeon config. Make sure to restart the service after making these changes.\n\n```yaml\npaloma:\n  signing-keys:\n    - pigeon-operator-alpha\n    - pigeon-operator-bravo\n    - pigeon-operator-charlie\n```\n\n### Start pigeon\n\nFirst pigeon will need some keys:\n\n```shell\ncat \u003c\u003cEOT \u003e~/.pigeon/env.sh\nPALOMA_KEYRING_PASS=\u003cyour Paloma key password\u003e\nETH_RPC_URL=\u003cYour Ethereum mainnet RPC URL\u003e\nETH_PASSWORD=\u003cYour ETH Key Password\u003e\nETH_SIGNING_KEY=\u003cYour ETH SIGNING KEY\u003e\nBNB_RPC_URL=\u003cYour Binance mainnet RPC URL\u003e\nBNB_PASSWORD=\u003cYour BNB Key Password\u003e\nBNB_SIGNING_KEY=\u003cYour BNB SIGNING KEY\u003e\nMATIC_RPC_URL=\u003cYour Binance mainnet RPC URL\u003e\nMATIC_PASSWORD=\u003cYour BNB Key Password\u003e\nMATIC_SIGNING_KEY=\u003cYour BNB SIGNING KEY\u003e\nBASE_RPC_URL=\u003cYour Base mainnet RPC URL\u003e\nBASE_PASSWORD=\u003cYour Base Key Password\u003e\nBASE_SIGNING_KEY=\u003cYour Base SIGNING KEY\u003e\nGNOSIS_RPC_URL=\u003cYour Gnosis mainnet RPC URL\u003e\nGNOSIS_PASSWORD=\u003cYour Gnosis Key Password\u003e\nGNOSIS_SIGNING_KEY=\u003cYour Gnosis SIGNING KEY\u003e\nARB_RPC_URL=\u003cYour Arbitrum mainnet RPC URL\u003e\nARB_PASSWORD=\u003cYour Arbitrum Key Password\u003e\nARB_SIGNING_KEY=\u003cYour Arbitrum SIGNING KEY\u003e\nBLAST_RPC_URL=\u003cYour Blast mainnet RPC URL\u003e\nBLAST_PASSWORD=\u003cYour Blast Key Password\u003e\nBLAST_SIGNING_KEY=\u003cYour Blast SIGNING KEY\u003e\nOP_RPC_URL=\u003cYour Optimism mainnet RPC URL\u003e\nOP_PASSWORD=\u003cYour Optimism Key Password\u003e\nOP_SIGNING_KEY=\u003cYour Optimism SIGNING KEY\u003e\nVALIDATOR=\u003cVALIDATOR NAME\u003e\nEOT\n```\n\nThen we can run pigeon with:\n\n```shell\nsource ~/.pigeon/env.sh\npigeon start\n```\n\n#### Using systemd\n\nMake sure you have configured `.pigeon/env.sh` as above. Then create a systemctl configuration:\n\n```shell\ncat \u003c\u003cEOT \u003e/etc/systemd/system/pigeond.service\n[Unit]\nDescription=Pigeon daemon\nAfter=network-online.target\nConditionPathExists=/usr/local/bin/pigeon\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nUser=${USER}\nWorkingDirectory=~\nEnvironmentFile=${HOME}/.pigeon/env.sh\nExecStart=/usr/local/bin/pigeon start\nExecReload=\n\n[Install]\nWantedBy=multi-user.target\nEOT\n```\n\nThen start our pigeon!\n\n```shell\nservice pigeond start\n\n# Check that it's running successfully:\nservice pigeond status\n# Or watch the logs:\njournalctl -u pigeond.service -f -n 100\n```\n\n### Definitions and Descriptions of Pigeons Variables\n\n- for paloma key:\n  - keyring-dir\n  - right now it's not really super important where this points. The important things for the future is that pigeon needs to send transactions to Paloma using its validator (operator) key!\n    - it's best to leave it as is\n  - keyring-pass-env-name\n    - this one is super important!\n    - it is the name of the ENV variable where password to unlock the keyring is stored!\n    - you are not writing password here!! You are writing the ENV variable's name where the password is stored.\n    - you should obviously use a bit more advanced method than shown here, but here is the example:\n      - if the `keyring-pass-env-name` is set to `MY_SUPER_SECRET_PASS` then you should provide ENV variable `MY_SUPER_SECRET_PASS` and store the password there\n      - e.g. `MY_SUPER_SECRET_PASS=abcd pigeon start`\n  - keyring-type\n    - it should be the same as it's defined for paloma's client. Look under the ~/.paloma/config/client.toml\n  - signing-key\n    - right now it's again not important which key we are using. It can be any key that has enough balance to submit TXs to Paloma. It's best to use the same key that's set up for the validator.\n  - gas-adustment:\n    - gas multiplier. The pigeon will estimate the gas to run a TX and then it will multiply it with gas-adjustment (if it's a positive number)\n- for evm -\u003e eth-main:\n  - keyring-pass-env-name: same as above for paloma.\n  - signing-key\n    - address of the key from the keyring used to sign and send TXs to EVM network (one that you got when running `pigeon evm keys generate-new` from the install section)\n  - keyring-dir:\n    - a directory where keys to communicate with the EVM network is stored\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalomachain%2Fpigeon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpalomachain%2Fpigeon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalomachain%2Fpigeon/lists"}