The Calimero blockchain bridge connects Near and Calimero. It can bridge two types of assets: FTs (Fungible Tokens) and NFTs (Non-Fungible Tokens). Additionally, it can perform Cross-Shard Contract Calls, where a smart contract on one chain can call smart contracts on the opposite chain and receive callbacks. These three ways of using the Calimero blockchain bridge share some smart contracts (most importantly, the permissions contract) and all off-chain Calimero bridge components. For more information, please refer to the official doc.
The Calimero console deploys three components separately. After installing a specific blockchain bridge, setting the correct bridging permissions becomes crucial for its successful operation. By default, the installation of any (FT/NFT/XSC) bridge denies all bridging.
All three bridges (FT, NFT, and XSC) manage permissions based on the Account ID that initiates bridging on the source side. For example, on the Near side for Near-to-Calimero bridging. Additionally, for the XSC connector, managing permissions is based on the Contract ID of the smart contract that the user is trying to call on the destination side.
Motivation for Creating and Properly Using Bridge Permissions
The bridge permissions protect Calimero shard users and organizations from malicious actors. We will list the most important security risks that we mitigate by properly setting blockchain bridge permissions:
- Preventing Malicious Bridge Usage: Proper permissions can prevent malicious entities from bridging FTs and NFTs into the private shard. By carefully controlling permissions, you can mitigate potential security risks.
- Protecting Privacy in Cross-Shard Calls: The Calimero private sharding solution aims to protect customer privacy. By managing XSC permissions, you can ensure that public network users (NEAR) cannot access sensitive information stored in contracts on the private shard.
- Avoiding Malicious and Unnecessary Transactions: Misconfigured permissions can result in paying gas fees on the destination chain (e.g., NEAR) for calls initiated by malicious actors. By setting strict permissions, you can avoid financial harm caused by excessive bridging operations. This problem also exists in the opposite direction, where a malicious actor bridges a lot of worthless tokens to the shard. This takes up a lot of space in produced blocks while extensively using the bridge components.
Blockchain Bridge permissions for FTs and NFTs
As described above, the installation of the FT or NFT bridge denies bridging for all accounts. Permissions for assets bridging are always managed on the permissions contract on the source side. For example on Near for bridging FTs from Near to Calimero. Connectors, which are the smart contracts responsible for bridging, consistently verify with the permissions smart contract. This ensures that bridging adheres to the established permissions. Each connector (FT, NFT, and XSC) has its own set of permissions to manage.
By default, bridging is forbidden for all accounts. If the Calimero shard admin decides to grant bridging permissions to a particular account or a specific group of accounts, the admin can add a new allow regex rule (or rules) that matches the approved accounts for asset bridging.
Let us assume that the shard admin added an allow regex rule .*\.john\.testnet for the FT connector. Now let us look at a few examples of bridging attempts:
- Account ID alice.john.testnet wants to bridge FT wrap.testnet. This bridging is allowed since it passes at least one (currently the only one) regex allow rule, concretely rule .*\.john\.testnet. Permissions management doesn’t include asset names, so john.testnet can bridge any asset.
- Account ID bob.testnet wants to bridge FT wrap.testnet. This bridging is denied since bob.testnet does not match any allow regex rules.
Note here that Account IDs that do not match at least one allow regex rule can’t bridge any assets, while all Account IDs that match at least one allow regex rule can bridge any asset.
Blockchain Bridge Permissions for XSC bridge
Cross-shard contract calls are trickier than FT and NFT bridging. If administrators don’t set those permissions correctly, a malicious actor can initiate a cross-shard contract call from the public Near side and access sensitive information on the private Calimero shard.
Because of this, we decided to implement an extra layer of protection through permissions management. We manage permissions for the XSC bridge as follows:
- By default, all Account IDs are denied for calling any smart contract on the opposite side of the bridge.
- Account ID that matches at least one allow regex rules for accounts can make cross-shard contract calls.
- Additionally, we have established a deny list using pairs of regexes (account regex, contract regex). A cross-shard contract call is allowed if the Account ID matches at least one allow regex rule for accounts and, simultaneously, the Account ID initiating the cross-shard contract call for a contract with a specific Contract ID doesn’t match any deny regex rule pair.
Let us assume that the shard admin added an allow regex rule .*\.john\.testnet for the XSC connector. Admin also added a deny rule pair (.*, .*sensitive.*) in format (Account ID, Contract ID). Now let us look at a few examples of bridging attempts:
- Account ID alice.john.testnet wants to make a cross shard contract call to contract with address mycontract.calimero.testnet. This bridging is allowed since Account ID matches at least one allow regex rule and the pair (john.testnet, mycontract.calimero.testnet) does not match any deny rule pairs.
- Account ID alice.testnet wants to make a cross shard contract call to contract with address sensitive.calimero.testnet. This bridging is denied since alice.testnet does not match any allow regex rules.
- Account ID alice.john.testnet wants to make a cross shard contract call to contract with address sensitive.calimero.testnet. Account ID alice.john.testnet matches at least one regex rule, but since pair (alice.john.testnet, sensitive.calimero.testnet) also matches a deny regex rule this bridging is denied.
For a more detailed overview of the Calimero blockchain bridge permissions please refer to the official documentation.