Bridges

Abstract

Decentralized exchange (DEX) functionality on Iroha v2 requires a mechanism for communication between third-party blockchains. This proposal introduces Bridges as such mechanism - entities, that can interact with other blockchain networks by a specific set of protocols built on top of already existing ISIs.

Glossary

• Host blockchain - Blockchain where the current bridge module is deployed.
• Client blockchain - any other blockchain network connected to Iroha2 via Bridge module.
• Bridge contract - part of the bridge module responsible for interaction with client bridge component or module and third-party blockchain.
• Client Bridge component - It is a component whose purpose is to perform communication between Iroha2 and other blockchain networks according to the protocol in bridge contract.

Introduction

The main goal is to have the following functionality:

1. Register a bridge that will be associated with a specific network (e.g. Etherium network);
2. Register external asset (token) on an existing bridge (e.g. ETH20 token);
3. Be able to transfer all of 3rd-party and Iroha blockchain tokens;
4. Lock/demint funds for sending external tokens;
5. Mint/unlock funds for receiving external tokens.

To implement these functions, a few new Iroha instructions and a bridge module need to be added, those will be accessible behind the "bridge" feature.

Bridge registration

A bridge can be constructed from 3 parameters (BridgeDefinition):

• Bridge type (kind). An enumeration of supported communication protocols (for now it's only IClaim).
• Bridge name. A string. It should be unique. OR Bridge domain. This domain will store all bridge accounts.
• Creator account (maybe should be eliminated in the future). A common Iroha account that owns the bridge.
• Maybe: Bridge account.

We assume, that every bridge will be a part of the Peer state. It means that for bridge registration, a new variant of the `PeerInstruction` should be added (RegisterBridge(BridgeDefinition, PeerId) with a corresponding generic Register<Peer, BridgeDefinition> instruction). This instruction should be called only with minimal required bridge parameters (definition). This ISI creates a domain with a bridge account named 'bridge' and sets the public key for this account, finally it creates a new bridge entity based on these parameters. The public key for the bridge account is generated from a hash of the bridge definition (seed). To generate determined public keys for bridge accounts, a new crypto function for generating keypairs from a given seed should added: generate_key_pair_from_seed(Hash) → Result<(PublicKey, PrivateKey), String>. 

So, the final bridge should contain the following (Bridge):

• All data from the bridge the definition.
• Bridge account.

Permissions:

• CanRegisterBridge. By default allowed to the network admin.

Also, there will be added a 'bridges' map (String → Bridge) in the Peer and three new helper-methods to the WorldStateView:

• add_bridge(&mut self, Bridge) // Adds a new bridge
• read_bridge(&self, &str) → Option<&Bridge> // Returns shared reference to a bridge by its name
• bridge(&mut self, &str) → Option<&mut Bridge> // Returns exclusive reference to a bridge by its name

This ISI can be executed multiple times for one bridge type and different bridge domains. So one bridge type can be used to create a bridge with multiple third-party networks.

Unresolved questions

1. Should we generate this public key from the seed or let the user choose one?
2. How can we implement this ISI as a composition of AddDomain, AddAccount...?

Bridge client registration

Command to register an external bridge component account. From here, a new set of Iroha instructions should be added (BridgeInstruction).

For example, we have Polkadot parachain as a connector to the Iroha bridge module for Polkadot. Then we have to register a parachain node as an external validator for this bridge. So it can start using Bridge API with its own signature. This instruction should create an external bridge client component account in a bridge domain and let the bridge know that this account should sign MST token transfer commands from the external blockchain. So for every transfer, this bridge should collect quorum of 2/3(make it configurable in future versions) client bridge components to process further actions in Iroha.

ISI parameters:

• Bridge title. Identifies the bridge to which this external component belongs and the domain in which this account will be created.
• Account name. A name for this external bridge component.
• Public key. A public key for the external account.

Permissions:

• CanRegisterClientBridge. By default allowed to bridge owner.

External asset registration

When a bridge is registered, external tokens may be added to it. For example, one may add a new ERC-20 token from Ethereum. The corresponding Bridge ISI (RegisterExternalAsset) should create a mapping between an external token ID (which can be used in ExternalTokenTransfer instruction) and a mirror token in Iroha. The asset should be created in the bridge's domain with the specified name. Also, a mapping between this asset and the name of the external token should be created.

ISI arguments:

• Bridge name.
• Token title. It should be unique.
• External token ID. A token identifier in an external network. Used by client bridge functionality when it will send transfer information from the external network.

Permissions:

• AddExternalTokenToBridge(bridge_name). By default assigned to the bridge owner (admin) account.

External asset transfers

To Iroha

There will be TransferAssetToBridge ISI.

Within Iroha

Like regular transfer in Iroha

From Iroha

TODO

Bridge protocol

As the first protocol for interoperability between blockchains, there will be a slightly modified version of XClaim, that we call IClaim (Iroha Claim). 

The flow of the protocol is the following (vault = client bridge, TOK = some 3rd-party token):

1. Transfer from third-party blockchain to Iroha.
   1. Alice sends TOK to vault
   2. Alice sends proof of transaction inclusion in block to a bridge client
   3. Bridge contract unlocks & transfers tokens to Alice on Iroha
2. Transfer from Iroha to third-party blockchain
   1. Alice sends TOK-asset to bridge contract
   2. Bridge contract signals to vault
   3. Vault observes the command, releases and transfers TOKs to Alice
   4. Vault finishes the process by proofing the transfer to bridge contract, then bridge contract releases the collateral to the vault in Iroha
   5. Otherwise, the locker receives his tokens back