{"id":14992083,"url":"https://github.com/octopus-network/near-ibc","last_synced_at":"2026-02-03T07:09:34.367Z","repository":{"id":103059432,"uuid":"550396651","full_name":"octopus-network/near-ibc","owner":"octopus-network","description":"near smart contract implement ibc protocol","archived":false,"fork":false,"pushed_at":"2024-07-25T12:15:37.000Z","size":1521,"stargazers_count":14,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-16T12:54:04.508Z","etag":null,"topics":["ibc","near","smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/octopus-network.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"auditing/blocksec_near-ibc_v1.0_signed.pdf","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-12T17:39:10.000Z","updated_at":"2024-08-01T14:26:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"d6e5d1cc-df95-46c8-9e7e-d6f7af50e2bf","html_url":"https://github.com/octopus-network/near-ibc","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/octopus-network/near-ibc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octopus-network%2Fnear-ibc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octopus-network%2Fnear-ibc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octopus-network%2Fnear-ibc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octopus-network%2Fnear-ibc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/octopus-network","download_url":"https://codeload.github.com/octopus-network/near-ibc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octopus-network%2Fnear-ibc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276932074,"owners_count":25730719,"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","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ibc","near","smart-contracts"],"created_at":"2024-09-24T15:00:43.395Z","updated_at":"2025-09-25T14:30:49.013Z","avatar_url":"https://github.com/octopus-network.png","language":"Rust","funding_links":[],"categories":["Web3 and ZKP Framework"],"sub_categories":[],"readme":"# near-ibc\n\nThis is an implementation of the IBC protocol (IBC/TAO) in the NEAR protocol, which includes additional applications such as ICS-20, written by Octopus Network.\n\n## Implementation of IBC/TAO\n\nThe `near-ibc` crate is a NEAR smart contract that contains the implementation of interfaces (traits) defined in [ibc-rs](https://github.com/cosmos/ibc-rs). These interfaces are essential for IBC/TAO processes. The smart contract also offers view functions for IBC relayer [hermes](https://github.com/informalsystems/hermes). These functions enable querying of the state of hosted clients, connections, channels and other necessary IBC data.\n\n## Implementation of ICS-20\n\nThe `near-ibc` crate also includes the implementation of the `transfer` module (ICS-20) to reduce the impact of current `ibc-rs` implementation.\n\nOur implementation of the `BankKeeper` trait uses sub-accounts mechanism of NEAR protocol. The general design is as the following:\n\n![NEAR IBC accounts](/images/near-ibc-accounts.png)\n\n### Root account\n\nThe root account will be deployed by the wasm of the `near-ibc` crate. It includes the whole implementation of IBC/TAO and application module `transfer` (ICS-20).\n\nThe contract `near-ibc` will at least provide the following interfaces (functions):\n\n* Function `deliver`:\n  * Any account can call this function.\n  * This function is for relayers to deliver IBC packet to IBC/TAO implementation. It will perform full standard processes for IBC packet implemented by `ibc-rs` crate.\n* Function `setup_wrapped_token`:\n  * Only the governance account can call this function.\n  * This function will call `setup_asset` function of `token-factory` contract to create and initialize a wrapped token contract for a specific asset from a certain channel.\n* Function `setup_channel_escrow`:\n  * Only the governance account can call this function.\n  * This function will call `create_escrow` function of `escrow-factory` contract to create and initialize an escrow contract for a specific channel.\n* Function `register_asset_for_channel`:\n  * Only the governance account can call this function.\n  * This function will call `register_asset` function of `channel-escrow` contract to register a `token contract` and its `denom` as a whitelisted asset for a certain channel.\n* Function `process_transfer_request`:\n  * Only the sub-accounts of `near-ibc` account can call this function.\n  * This function will call the `send_transfer` function implemented in `ibc-rs` crate to update on-chain state and generate necessary IBC events for relayers to perform a cross-chain token transfer. (Refer to [Sub accounts for assets from other chains](#sub-accounts-for-assets-from-other-chains) and [Sub accounts for channel escrows](#sub-accounts-for-channel-escrows) for more details.)\n\n### Sub account `transfer`\n\nFull account id: `transfer.\u003croot account\u003e`.\n\nThe sub-accounts at this level are reserved for applications (modules) in IBC protocol. In our implementation of ICS-20, this sub-account doesn't require any smart contract code deployment, as it is only acting as a placeholder.\n\n### Sub account `token-factory`\n\nFull account id: `tf.transfer.\u003croot account\u003e`.\n\nThis account is for deploying token contracts for assets from other chains. The contract in this account is implemented by the `token-factory` crate.\n\nThe contract `token-factory` will at least provide the following interfaces (functions):\n\n* Function `setup_asset`:\n  * Only the ancestor accounts of current account can call this function. The original caller should be the governance account set in `near-ibc` contract.\n  * This function checks whether the sub-account for the asset corresponding to the `denomination` of the coin (passed by the caller) exists. If not, a new sub-account will be created and initialized automatically.\n  * When it is necessary to create sub-account for a new asset, this function will also check for duplication of both `denomination` and `asset id` (refer to [sub-accounts for assets from other chains](#sub-accounts-for-assets-from-other-chains)) in order to avoid hash collisions. Besides, the mappings of `denomination` and `asset id` will also be stored in this contract.\n* Function `mint_asset`:\n  * Only the ancestor accounts of current account can call this function.\n  * This function will be called in function `BankKeeper::mint_coins`, which is implemented by the `transfer` module in `near-ibc` contract.\n  * This function will call the `mint` function of the contract of the sub-account automatically. (Also refer to [sub-accounts for assets from other chains](#sub-accounts-for-assets-from-other-chains).)\n* Necessary view functions for querying `denomination`s and `asset id`s.\n\n### Sub accounts for assets from other chains\n\nFull account id: `\u003casset id\u003e.tf.transfer.\u003croot account\u003e`, where the `asset id` is the leftmost 128 bits of sha256 hash of the denomination of a certain cross-chain asset, in hex format. Thus, the length of the whole account id will be `32 + 13 + (length of root account id)`, which can be controlled not longer than `64`.\n\nThis account is for minting and burning cross-chain assets that are NOT native in NEAR protocol. The contract in this account is implemented by the `wrapped-token` crate.\n\nThe contract `wrapped-token` will at least provide the following interfaces (functions):\n\n* Function `mint`:\n  * Only the parent account of current account (the `token-factory` account) can call this function.\n  * This function will mint a given amount of tokens to a given account in current token contract.\n* Function `request_transfer`:\n  * Only the token holders of in this contract can call this function.\n  * If all checks passed, this function will lock the given amount of tokens from the caller account (internal transfer them to the current account) and generate a `pending transfer request` for the caller account. Then it will schedule a call of `process_transfer_request` function of `near-ibc` contract.\n* Function `apply_transfer_request`:\n  * Only the `near-ibc` contract account can call this function.\n  * If the given parameters matches the `pending transfer request` of the given user account, the `pending transfer request` will be applied and removed. The given amount of tokens will be internal burnt from the current account.\n* Function `cancel_transfer_request`:\n  * Only the `near-ibc` contract account can call this function.\n  * If the given parameters matches the `pending transfer request` of the given user account, the `pending transfer request` will be canceled and removed. The given amount of tokens will be unlocked (internal transferred from the current account to the caller account corresponding to the `pending transfer request`).\n\n### Sub account `escrow-factory`\n\nFull account id: `ef.transfer.\u003croot account\u003e`.\n\nThis account is for deploying escrow contracts for assets native in NEAR protocol. The contract in this account is implemented by the `escrow-factory` crate.\n\nThe contract `escrow-factory` will at least provide the following interfaces (functions):\n\n* Function `create_escrow`:\n  * Only the ancestor accounts of current account can call this function.\n  * This function will create a sub-account for a certain IBC channel if it does not already exist. Then deploy and initialize the escrow contract (implemented by crate `channel-escrow`) in the sub-account automatically.\n\n### Sub accounts for channel escrows\n\nFull account id: `\u003cchannel id\u003e.ef.transfer.\u003croot account\u003e`.\n\nThis account is for receiving/locking NEP-141 assets that are native in NEAR protocol when they are transferred out of the NEAR protocol. It is also responsible for transferring/unlocking these NEP-141 assets when they are transferred back to the NEAR protocol. The contract in this account is implemented by the `channel-escrow` crate.\n\nThe contract `channel-escrow` will at least provide the following interfaces (functions):\n\n* Function `register_asset`:\n  * Only the `near-ibc` contract account can call this function. The original caller should be the governance account set in `near-ibc` contract.\n  * This function stores the given `token contract` and its `denom` as a whitelisted asset.\n* Function `ft_on_transfer`:\n  * This function is for receiving assets (whose source chain is the NEAR protocol) from the NEAR protocol. It acts as a callback function which will be triggered when a token transfer to this account happens by calling the `ft_transfer_call` function of any NEP-141 contract.\n  * Only the transfers from `registered token contracts` will be accepted.\n  * If all checks passed, this function will generate a `pending transfer request` for the sender account. Then it will schedule a call of `process_transfer_request` function of `near-ibc` contract.\n* Function `apply_transfer_request`:\n  * Only the `near-ibc` contract account can call this function.\n  * If the given parameters matches the `pending transfer request` of the given user account, the `pending transfer request` will be applied and removed.\n* Function `cancel_transfer_request`:\n  * Only the `near-ibc` contract account can call this function.\n  * If the given parameters matches the `pending transfer request` of the given user account, the `pending transfer request` will be canceled and removed. The given amount of tokens will be transferred back to the sender account corresponding to the `pending transfer request`.\n* Function `do_transfer`:\n  * Only the `near-ibc` contract account can call this function.\n  * The `BankKeeper::send_coins` function, implemented by the `transfer` module in `near-ibc` contract, will call this function to transfer a certain amount of previously locked NEP-141 tokens from current account to a specific receiver in the NEAR protocol.\n\n### General process of ICS20 implementation\n\n#### Transfer asset from other chain to NEAR protocol\n\n![3-1](/images/near_ibc-Page-3-1.drawio.png)\n\n#### Redeem cross-chain asset from NEAR protocol back to the source chain\n\n![3-2](/images/near_ibc-Page-3-2.drawio.png)\n\n#### Transfer asset from NEAR protocol to other chains\n\n![4-1](/images/near_ibc-Page-4-1.drawio.png)\n\n#### Redeem cross-chain asset from other chains back to NEAR protocol\n\n![4-2](/images/near_ibc-Page-4-2.drawio.png)\n\n## Supporting features\n\nPlease refer to release notes for details.\n\n* [v1.0.0 pre-release 1](https://github.com/octopus-network/near-ibc/releases/tag/v1.0.0-pre.1)\n\n## Auditing\n\nThese contracts had completed auditing by:\n\n* [Blocksec](https://blocksec.com) - The report is [here](/auditing/blocksec_near-ibc_v1.0_signed.pdf).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopus-network%2Fnear-ibc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctopus-network%2Fnear-ibc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopus-network%2Fnear-ibc/lists"}