{"id":19107358,"url":"https://github.com/smartcontractkit/chain-selectors","last_synced_at":"2026-02-09T22:05:12.640Z","repository":{"id":190192540,"uuid":"678468541","full_name":"smartcontractkit/chain-selectors","owner":"smartcontractkit","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-16T11:41:34.000Z","size":506,"stargazers_count":22,"open_issues_count":6,"forks_count":8,"subscribers_count":83,"default_branch":"main","last_synced_at":"2026-01-17T00:41:22.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"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/smartcontractkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"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":"2023-08-14T16:13:27.000Z","updated_at":"2026-01-16T11:41:42.000Z","dependencies_parsed_at":"2023-08-23T15:55:21.908Z","dependency_job_id":"82ebe38d-8869-4f7b-ba77-e2a5c05ab2c2","html_url":"https://github.com/smartcontractkit/chain-selectors","commit_stats":null,"previous_names":["smartcontractkit/chain-selectors","smartcontractkit/ccip-chain-selectors"],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/smartcontractkit/chain-selectors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fchain-selectors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fchain-selectors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fchain-selectors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fchain-selectors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcontractkit","download_url":"https://codeload.github.com/smartcontractkit/chain-selectors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fchain-selectors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28606433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T14:45:23.139Z","status":"ssl_error","status_checked_at":"2026-01-20T14:44:16.929Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":"2024-11-09T04:12:17.532Z","updated_at":"2026-01-20T16:08:17.267Z","avatar_url":"https://github.com/smartcontractkit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chain Selectors [![Go Reference](https://pkg.go.dev/badge/github.com/smartcontractkit/chain-selectors.svg)](https://pkg.go.dev/github.com/smartcontractkit/chain-selectors)\n\nCCIP uses its own set of chain selectors represented by uint64 to identify blockchains. It is a random\ninteger generated as follows:\n\n```python3\npython3\n\u003e\u003e\u003e import random\n\u003e\u003e\u003e random.randint(1, 2**64-1)\n```\n\nThe scheme is used for several reasons:\n\n- Global uniqueness across blockchain families\n- Very unlikely to collide with existing chain ID schemes, reducing confusion\n- Efficient on/off-chain representation\n- No preference towards any family or chain\n- Decoupled from chain name which may change over time with rebrands/forks\n\nThis repository contains a\nmapping between the custom chain identifiers (`chainSelectorId`) chain names and the chain identifiers\nused by the blockchains themselves (`chainId`). For solana we use the base58 encoded genesis hash as the chain id.\n\nPlease refer to the [official documentation](https://docs.chain.link/ccip/supported-networks) to learn more about\nsupported networks and their selectors.\n\n### Installation\n\n`go get github.com/smartcontractkit/chain-selectors`\n\n### Usage\n\n```go\nimport (\n    chainselectors \"github.com/smartcontractkit/chain-selectors\"\n)\n\nfunc main() {\n    // -------------------Chains agnostic --------------------:\n\n    // Getting chain family based on selector\n    family, err := GetSelectorFamily(2664363617261496610)\n\n    // -------------------For EVM chains--------------------\n\n    // Getting selector based on ChainId\n    selector, err := chainselectors.SelectorFromChainId(420)\n\n    // Getting ChainId based on ChainSelector\n    chainId, err := chainselectors.ChainIdFromSelector(2664363617261496610)\n\n    // Getting ChainName based on ChainId\n    chainName, err := chainselectors.NameFromChainId(420)\n\n    // Getting ChainId based on the ChainName\n    chainId, err := chainselectors.ChainIdFromName(\"binance_smart_chain-testnet\")\n\n    // Accessing mapping directly\n    lookupChainId := uint64(1337)\n    if chainSelector, exists := chainselectors.EvmChainIdToChainSelector()[lookupChainId]; exists {\n        fmt.Println(\"Found evm chain selector for chain\", lookupChainId, \":\", chainSelector)\n    }\n\n    // -------------------Solana Chain --------------------:\n\n    // Getting chain family based on selector\n    family, err := SolanaNameFromChainId(\"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d\")\n\n    // Getting chain id from chain selector\n\tchainId, err := chainselectors.SolanaChainIdFromSelector(124615329519749607)\n\n    // Accessing mapping directly\n    lookupChainId := \"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d\"\n    if chainSelector, exists:= chainselectors.SolanaChainIdToChainSelector()[lookupChainId]; exists {\n        fmt.Println(\"Found solana chain selector for chain\", lookupChainId, \":\", chainSelector)\n    }\n}\n```\n\n### Remote API (Fetch from GitHub)\n\nYou can fetch chain information dynamically from GitHub. This allows you to get the latest chain data without updating the package.\n\n```go\nimport (\n    chainsel \"github.com/smartcontractkit/chain-selectors/remote\"\n)\n```\n\n#### Chain-Agnostic Functions\n\nThese functions work across all blockchain families (EVM, Solana, Aptos, Sui, Ton, Tron, Starknet):\n\n```go\n// Get chain details by selector (returns family, chain ID, and name)\ndetails, err := chainsel.GetChainDetailsBySelector(ctx, 5009297550715157269)\n// Returns: ChainDetailsWithMetadata{Family: \"evm\", ChainID: \"1\", ChainName: \"ethereum-mainnet\", ...}\n\n// Get chain details by chain ID and family\ndetails, err := chainsel.GetChainDetailsByChainIDAndFamily(ctx, \"1\", \"evm\")\n// Returns: ChainDetails{ChainSelector: 5009297550715157269, ChainName: \"ethereum-mainnet\"}\n```\n\n#### EVM-Specific Functions\n\nThese functions are specific to EVM chains:\n\n```go\n// Get all EVM chain ID to selector mappings\nmapping, err := chainsel.EvmChainIdToChainSelector(ctx)\n\n// Get EVM chain ID from chain name\nchainID, err := chainsel.EvmChainIdFromName(ctx, \"ethereum-mainnet\")\n\n// Get chain details by selector\nchain, exists, err := chainsel.EvmChainBySelector(ctx, 5009297550715157269)\n\n// Get chain details by EVM chain ID\nchain, exists, err := chainsel.EvmChainByEvmChainID(ctx, 1)\n\n// Check if a selector belongs to an EVM chain\nisEvm, err := chainsel.IsEvm(ctx, 5009297550715157269)\n```\n\n**Note:** When using remote fetching:\n\n- Extra selectors (from `EXTRA_SELECTORS_FILE`) are **not included** in remote API responses\n- Embedded chains from the package are **ignored** - only chains from GitHub are used\n- Use remote fetching when you need the latest chain data from the repository\n- Use in-memory functions when you need to include extra selectors or prefer faster lookups\n- Caching is **enabled by default** with a 5-minute TTL to reduce network calls\n- use `WithCacheTTL(0)` to disable or customize the TTL\n\n### Adding additional chains at runtime\n\nYou can add additional chains at runtime by setting the `EXTRA_SELECTORS_FILE` environment variable to point to a YAML file containing additional chain mappings. This is useful for adding custom chains or test networks without modifying the main selectors file.\n\nThe extra selectors file should follow this format with blockchain family keys:\n\n```yaml\nevm:\n  $chain_id:\n    selector: $chain_selector\n    name: $chain_name\n```\n\n### Contributing\n\n#### Naming new chains\n\nChain names must respect the following format:\n`\u003cblockchain\u003e-\u003ctype\u003e-\u003cnetwork_instance\u003e`\n\nWhen a component requires more than 1 word, use snake-case to connect them, e.g `polygon-zkevm`.\n\n| Parameter        | Description                                          | Example                                  |\n| ---------------- | ---------------------------------------------------- | ---------------------------------------- |\n| blockchain       | Name of the chain                                    | `ethereum`, `avalanche`, `polygon-zkevm` |\n| type             | Type of network                                      | `testnet`, `mainnet`, `devnet`           |\n| network_instance | [Only if not mainnet] Identifier of specific network | `alfajores`, `holesky`, `sepolia`, `1`   |\n\nMore on `network_instance`: only include it if `type` is not mainnet. This is because legacy testnet instances are often dropped after a new one is spun up, e.g Ethereum Rinkeby.\n\nRules for `network_instance`:\n\n1. If chain has an officially-named testnet, use it, e.g\n   `celo-testnet-alfajores`, `ethereum-testnet-holesky`\n2. If not above, and chain is a rollup, use the name of its settlement network, e.g `base-testnet-sepolia`\n3. If not above, use a number, e.g `bsc-testnet-1`\n\nExample chain names that comply with the format:\n\n```\nastar-mainnet\nastar-testnet-shibuya\ncelo-mainnet\ncelo-testnet-sepolia\npolygon-zkevm-mainnet\npolygon-zkevm-testnet-cardona\nethereum-mainnet\nethereum-testnet-sepolia\nethereum-testnet-holesky\noptimism-mainnet\noptimism-testnet-sepolia\nbsc-mainnet\nbsc-testnet-1\n```\n\nYou may find some existing names follow a legacy naming pattern: `\u003cblockchain\u003e-\u003ctype\u003e-\u003cnetwork_name\u003e-\u003cparachain\u003e-\u003crollup\u003e-\u003crollup_instance\u003e`. Those names are kept as is due to complexity of migration. The transition form legacy pattern to the new pattern is motivated by chain migrations, e.g Celo migrating from an L1 into an L2, rendering the legacy name stale.\n\n#### Adding new chains\n\nAny new chains and selectors should be always added to [selectors.yml](selectors.yml) and client libraries should load\ndetails from this file. This ensures that all client libraries are in sync and use the same mapping.\nTo add a new chain, please add new entry to the `selectors.yml` file and use the following format:\n\nMake sure to run `go generate` after making any changes.\n\n```yaml\n$chain_id:\n  selector: $chain_selector as uint64\n  name: $chain_name as string # Although name is optional parameter, please provide it and respect the format described below\n```\n\n[selectors.yml](selectors.yml) file is divided into sections based on the blockchain type.\nPlease make sure to add new entries to the both sections and keep them sorted by chain id within these sections.\n\nIf you need to add a new chain for testing purposes (e.g. running tests with simulated environment) don't mix it with\nthe main file and use [test_selectors.yml](test_selectors.yml) instead. This file is used only for testing purposes.\n\n#### Adding new client libraries\n\nIf you need a support for a new language, please open a PR with the following changes:\n\n- Library codebase is in a separate directory\n- Library uses selectors.yml as a source of truth\n- Proper Github workflow is present to make sure code compiles and tests pass\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fchain-selectors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcontractkit%2Fchain-selectors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fchain-selectors/lists"}