{"id":13573237,"url":"https://github.com/confio/ts-relayer","last_synced_at":"2025-04-04T12:30:28.700Z","repository":{"id":38394903,"uuid":"333112108","full_name":"confio/ts-relayer","owner":"confio","description":"IBC Relayer in TypeScript","archived":true,"fork":false,"pushed_at":"2024-07-21T11:26:06.000Z","size":2223,"stargazers_count":109,"open_issues_count":26,"forks_count":66,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-01T10:37:51.307Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/confio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/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":"2021-01-26T14:34:33.000Z","updated_at":"2025-02-13T08:19:05.000Z","dependencies_parsed_at":"2024-04-15T05:43:56.151Z","dependency_job_id":"89f683e5-6b2b-4f76-9f17-e639485e0179","html_url":"https://github.com/confio/ts-relayer","commit_stats":{"total_commits":868,"total_committers":17,"mean_commits":51.05882352941177,"dds":0.5472350230414746,"last_synced_commit":"e0b369407996b34dcb3830214b8a9d44d2202420"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/confio%2Fts-relayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/confio%2Fts-relayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/confio%2Fts-relayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/confio%2Fts-relayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/confio","download_url":"https://codeload.github.com/confio/ts-relayer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247179327,"owners_count":20897015,"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":[],"created_at":"2024-08-01T15:00:32.203Z","updated_at":"2025-04-04T12:30:27.597Z","avatar_url":"https://github.com/confio.png","language":"TypeScript","funding_links":[],"categories":["IBC"],"sub_categories":["External Modules","Terminal Block Explorers"],"readme":"# Relayer\n\n[![npm version](https://img.shields.io/npm/v/@confio/relayer.svg)](https://www.npmjs.com/package/@confio/relayer)\n\nTypeScript implementation of an [IBC](https://www.ibcprotocol.dev/) Relayer.\n\nTo get a good overview of what it can do, please\n[check our feature matrix](./FEATURES.md)\n\nYou can also read [our specification page](./spec/index.md), which explains how\nthe relayer works, but the Quick Start probably gives a better intro.\n\nThis repo is mainly used as a node binary to perform IBC relaying. However, all logic is\navailable in the library, which can be run equally well in the browser or in Node.\nYou can see an example of embedding the relayer in a [webapp below](#Web-App).\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) 18 or later\n- RPC addresses of 2 full nodes on compatible, IBC-enabled chains\n- See [Chain Requirements below](#Chain-Requirements) for details of what chains are supported\n\n## Important Note\n\nVersions until `v0.1.6` support Cosmos SDK `v0.41.1+`.\nFrom `v0.2.0` on we require Tendermint `v0.34.9+` (which is used in SDK `v0.42.4+`).\nIf you are connecting to a v0.41 chain, please use the `v0.1.x` relayer.\n\nWith `v0.2.0` we add support for relaying packets in BeginBlock and EndBlock. However, this requires\nan extra rpc endpoint in Tendermint that is not available in `v0.41.1`. We therefore increase the\nminimum compatible version of the SDK.\n\n## Installation\n\n### NPM\n\nInstall the [latest release](https://github.com/confio/ts-relayer/releases/latest).\n\n```sh\nnpm i -g @confio/relayer\n```\n\nAlternatively, install from the `main` branch.\n\n```sh\nnpm i -g @confio/relayer@main\n```\n\n\u003e **NOTE:** We do a manual release after completing a predefined milestone or when it feels right. No release schedule is in place \u003cem\u003eyet\u003c/em\u003e. To utilize the latest changes, use the `main` tag during the installation.\n\n## Usage\n\nAfter installation, `ibc-setup` and `ibc-relayer` executables are available.\n\n### ibc-setup\n\nCollection of commands to quickly setup a relayer and query IBC/chain data.\n\n- run `ibc-setup --help` to print usage\n- [ibc-setup spec](spec/ibc-setup.md)\n\n### ibc-relayer\n\nReads the configuration and starts relaying packets.\n\n- run `ibc-relayer --help` to print usage\n- [ibc-relayer spec](spec/ibc-relayer.md)\n\n## Quick start\n\n### Configure and start the relayer\n\n1. Init the configuration\n\n   ```sh\n   ibc-setup init --src malaga --dest uni\n   ```\n\n   - creates relayer's home directory at `~/.ibc-setup`\n   - creates `app.yaml` inside relayer's home with `src`, `dest` and newly generated `mnemonic`\n   - pulls default `registry.yaml` to relayer's home\n   - funds addresses on `malaga` so relayer can pay the fee while relaying packets\n\n   \u003e **NOTE:** Both testnets are running in the public. You do not need to start any blockchain locally to complete the quick start guide.\n\n   \u003e **NOTE:** Run `ibc-setup balances` to see the amount of tokens on each address.\n\n2. Get testnet tokens for `uni`\n\n   - Find your relayer address on uni via: `ibc-setup keys list | grep uni`\n   - Join Juno discord with [this invite link](https://discord.gg/NbB8zCPX)\n   - Go to the `faucet` channel\n   - Request tokens at this address in the above channel: `$request iaa1fxmqew9dgg44jdf3l34zwa8rx7tcf42wz8ehjk`\n   - Check you have tokens on malaga and uni via `ibc-setup balances`\n\n   See [original instructions](https://docs.junonetwork.io/validators/joining-the-testnets#get-some-testnet-tokens)\n\n3. Create `ics20` channel\n\n   ```sh\n   ibc-setup ics20 -v\n   ```\n\n   - creates a new connection on source and desination chains\n   - saves connection ids to `app.yaml` file\n   - creates a new channel\n\n4. Start the relayer in the verbose mode and 10s frequency polling\n   ```sh\n   ibc-relayer start -v --poll 15\n   ```\n\n### Send tokens between chains\n\n1. Make sure `wasmd` binary is installed on your system\n\n   - you must be running Linux or OSX on amd64 (not arm64/Mac M1)\n   - [install Go 1.17+](https://golang.org/doc/install) and ensure that `$PATH` includes Go binaries (you may need to restart your terminal session)\n   - clone and install `wasmd`:\n     ```sh\n     git clone https://github.com/CosmWasm/wasmd.git\n     cd wasmd\n     git checkout v0.27.0\n     make install\n     ```\n\n2. Make sure `juno` binary is installed on your system\n\n   - you must be running Linux or OSX on amd64\n   - [install Go 1.17+](https://golang.org/doc/install) and ensure that `$PATH` includes Go binaries (you may need to restart your terminal session)\n   - clone and install `juno`:\n     ```sh\n     git clone https://github.com/CosmosContracts/juno\n     cd juno\n     git checkout v6.0.0\n     make install\n     ```\n\n3. Create a new account and fund it\n\n   ```sh\n   wasmd keys add sender\n   JSON=$(jq -n --arg addr $(wasmd keys show -a sender) '{\"denom\":\"usponge\",\"address\":$addr}')\n   curl -X POST --header \"Content-Type: application/json\" --data \"$JSON\" https://faucet.malaga.cosmwasm.com/credit\n   ```\n\n4. Create a valid IRISnet address to send tokens to\n\n   ```sh\n   junod keys add receiver\n   ```\n\n   [Get testnet tokens](https://docs.junonetwork.io/validators/joining-the-testnets#get-some-testnet-tokens) if you want to send tokens to `malaga`.\n\n5. Send tokens\n   ```sh\n   wasmd tx ibc-transfer transfer transfer \u003cchannel-id\u003e $(junod keys show -a receiver) 200usponge --from $(wasmd keys show -a sender) --node http://rpc.malaga.cosmwasm.com:80 --chain-id malaga-1 --fees 2000usponge --packet-timeout-height 0-0\n   ```\n   - replace `\u003cchannel-id\u003e` with the channel id obtained while configuring the relayer (2nd point)\n   - if you cleared out the terminal, query the channel\n     ```sh\n     ibc-setup channels --chain malaga\n     ```\n6. Observe the relayer output\n\n## Configuration overview\n\nThe relayer configuration is stored under relayer's home directory. By default, it's located at `$HOME/.ibc-setup`, however, can be customized with `home` option, e.g.:\n\n```sh\n# initialize the configuration at /home/user/relayer_custom_home\nibc-setup init --home /home/user/relayer_custom_home\n\n# read the configuration from /home/user/relayer_custom_home\nibc-relayer start --home /home/user/relayer_custom_home\n```\n\nThere are 3 files that live in the relayer's home.\n\n- **registry.yaml** (required)\n\n  Contains a list of available chains with corresponding information. The chains from the registry can be referenced by `ibc-setup` binary or within the `app.yaml` file. [View an example of registry.yaml file.](demo/registry.yaml)\n\n- **app.yaml** (optional)\n\n  Holds the relayer-specific options such as source or destination chains. These options can be overridden with CLI flags or environment variables.\n\n- **last-queried-heights.json** (optional)\n\n  Stores last queried heights for better performance on relayer startup. It's constantly overwritten with new heights when relayer is running. Simply delete this file to scan the events since forever.\n\n[Learn more about configuration.](spec/config.md)\n\n## Monitoring\n\nThe relayer collects various metrics that a [Prometheus](https://prometheus.io/docs/introduction/overview/) instance can consume.\n\nTo enable metrics collection, pass the `--enable-metrics` flag when starting the relayer:\n\n```sh\nibc-relayer start --enable-metrics\n```\n\n\u003e **NOTE:** Metrics can also be enabled via an environment variable `RELAYER_ENABLE_METRICS=true`, or with an `enableMetrics: true` entry in the `app.yaml` file, as explained in the [config specification](./spec/config.md#configuration).\n\nThe `GET /metrics` endpoint will be exposed by default on port `8080`, which you can override with `--metrics-port` flag, `RELAYER_METRICS_PORT` env variable, or `metricsPort` entry in `app.yaml`.\n\n### Local setup\n\n#### Prometheus\n\n1. Start the relayer with metrics enabled\n2. Spin up the Prometheus instance:\n   ```sh\n   docker run -it -v $(pwd):/prometheus -p9090:9090 prom/prometheus --config.file=demo/prometheus.yaml\n   ```\n   \u003e **NOTE:** Ensure that `the --config.file=\u003cpath\u003e` flag points at the existing configuration file. If you wish to use [the example config](demo/prometheus.yaml), just run the command above in the root of this repository. Otherwise, you must adjust the volume (`-v`) and config file path to your setup.\n3. Open the Prometheus dashboard in a browser at [http://localhost:9090](http://localhost:9090)\n\n#### Grafana\n\n1. Spin up the Grafana instance:\n   ```sh\n   docker run -d --name=grafana -p 3000:3000 grafana/grafana\n   ```\n2. Navigate to [http://localhost:3000](http://localhost:3000) and log in (`admin`/`admin`)\n3. [Create a Prometheus data source](https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source)\n   \u003e **NOTE:** Use `http://host.docker.internal:9090` as the server URL and `Server` as the Access method.\n4. Create a new graph and query data\n   \u003e **NOTE:** Useful guides:\n   - https://grafana.com/docs/grafana/latest/getting-started/getting-started/#step-3-create-a-dashboard\n   - https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-graph\n\n## Development\n\n[Refer to the development page.](DEVELOPMENT.md)\n\n## Integration Tests\n\nts-relayer can be used as a library as well as a binary. This allows us to make powerful node scripts, or to\neasily test CosmWasm contract IBC flows in CI code. You can look at the following two examples on how to do so:\n\n- [Simple CW20-ICS20 talking to non-CosmWasm node](https://github.com/confio/ibc-tests-ics20)\n- [A pair of CosmWasm contracts talking on multiple chains](https://github.com/confio/cw-ibc-demo/tree/main/tests)\n\n## Chain Requirements\n\nThe blockchain must be based on Cosmos SDK `v0.42.4+`. In particular it must have\n[PR 8458](https://github.com/cosmos/cosmos-sdk/pull/8458) and [PR 9081](https://github.com/cosmos/cosmos-sdk/pull/9081)\nmerged (if you are using a fork) in order for the relayer to work properly. `ibc-setup` should work on `v0.40.0+`\n\nThe chain must have a large value for `staking.params.historical_entries` (often set in genesis).\nThe default is \"10000\" and this should work with \"1000\", but no relayer will work if it is set to 0.\n\n### Full Node Requirements\n\nIdeally you are in control of the node that the relayer connects to. If not, it should be run\nby a known and trusted party, whom you can check the configuration with. Note that a malicious node\ncould cause the relayer to send invalid packets and waste tokens on gas (but not create invalid state).\n\nThe indexer should be enabled (`tx_index.indexer = \"kv\"` in `config.toml`),\nand all events should be indexed (`index-events = []` in `app.toml`).\n\nThe node must support historical queries. `--pruning=nothing` will definitely work, but will use an\nenormous amount of disk space. You can also trim it to 3 weeks of data with\n`--pruning=custom --pruning-keep-recent=362880 --pruning-keep-every=0 --pruning-interval=100`, which has been\ntested. It is likely you could reduce `pruning-keep-recent` to as low as, say, 3600, but that would need testing.\n\n## Web App\n\nThis repo can also be imported as a library and used in a web app. @clockworkgr has been so nice\nto share a [sample Vue.js app using the relayer](https://github.com/clockworkgr/ts-relayer-example).\nThis includes some nice code samples to\n[send a IbcTransfer message with CosmJS](https://github.com/clockworkgr/ts-relayer-example/blob/main/src/App.vue#L153-L186)\nas well as [setting up](https://github.com/clockworkgr/ts-relayer-example/blob/main/src/App.vue#L218-L289)\nand [running the relayer](https://github.com/clockworkgr/ts-relayer-example/blob/main/src/App.vue#L187-L207).\n\n![screenshot](https://user-images.githubusercontent.com/6826762/116312118-b3f40e00-a7b4-11eb-879b-ce3135764460.png)\n\nThe key import is `import { IbcClient, Link } from \"@confio/relayer/build\";`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconfio%2Fts-relayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconfio%2Fts-relayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconfio%2Fts-relayer/lists"}