The Crosschain API allows a user to transfer (or "migrate") assets from one chain to another. Compatible forms of assets include coins and tokens.
The fundamental principle of migration is that a specific amount of assets are burned in the source chain and then the same specific amount of assets are created on the destination chain.
Different methods of migration using the Komodo Platform
MoMoM notarized migration
"MoMoM" stands for "Merkle root of Merkle roots of Merkle roots"
An alternative migration method with notarization of the given burn transaction by notary operators (this is a backup solution to the above MoMoM method)
Self-managed import
Crosschain API Flow
Make an export or burn transaction in the source chain.
Create an "import" transaction for the burned value.
This is created on the source chain, but the transaction is sent on the destination chain
Komodo's validation code checks that for the import transaction there exists a corresponding burn transaction, and that this transaction is not spent more than once.
Requirement
The source and destination chains should have the same CCid parameter (ac_cc). The value of this parameter should be greater than 100; this indicates to the Komodo software that the coins on both chains are fungible with each other.
:::tip Note
In the examples, we use two chains. The source chain is CFEKHOUND and the destination chain is CFEKDRAGON.
:::
MoMoM Notarized Migration
The MoMoM notarized migration API allows the migration of coin or token value using Komodo's notary network. This facilitates the highly scalable multi-chain architecture of Smart Chains on the Komodo Platform.
Notary nodes store "fingerprints" of the blocks belonging to the blockchains of the various assets in the main Komodo chain (KMD). The "fingerprints" can also be referred to as MoM, or merkle root of merkle roots.
The fingerprints of fingerprints are delivered back into the blockchain of the assets as back notarizations. To learn more about the notarization process, please visit this linked article.
Workflow of the MoMoM value migration
On the source chain, the user calls the method migrate_createburntransaction and broadcasts the hex of the returned burn transaction (BurnTxHex) using the sendrawtransaction method. The user also receives the payouts object from this method
On the source chain, the user runs migrate_createimporttransaction with the hex value of the burn transaction and the payouts object in hex format as arguments
On the main Komodo chain (KMD) the user calls migrate_completeimporttransaction with the import transaction in hex format which was received from the previous call as an argument.
As a part of this process, the proof object for the burn transaction inside the import transaction is extended with MoMoM data. This allows verification of the burn transaction on the destination chain by using the standard Komodo notarization process without the need to create additional proof objects
The migrate_createburntransaction method creates a transaction burning a specific amount of coins or tokens. This method also creates a payouts object which is later used to create an import transaction for the value corresponding to the burned amount. This method should be called on the source chain.
The method creates a burn transaction and returns it. This should be broadcast to the source chain using the sendrawtransaction method. After the burn transaction is successfully mined, the user might have to wait for some amount of time for the back notarization to reach the source chain. The back notarization contains the MoMoM fingerprints of the mined block that contains the burn transaction.
The hex value of the burn transaction along with the other returned value payouts are used as arguments for the migrate_createimporttransaction method.
Arguments
Name
Type
Description
"destChain"
(string, required)
the name of the destination chain
"destAddress"
(string, required)
the address on the destination chain where coins are to be sent; the pubkey if tokens are to be sent
"amount"
(numeric, required)
the amount in coins or tokens that should be burned on the source chain and created on the destination chain; if the indicated assets are tokens, the amount can be set only to 1, as only migration of non-fungible tokens are supported at this time
"tokenid"
(string, optional)
token id in hex; if set, the software assumes that the user is migrating tokens
Response
Name
Type
Description
"payouts"
(string)
a hex string of the created payouts; this value is passed into the migrate_createimporttransaction method
The migrate_converttoexport method allows the user to create a customized burn transaction (as opposed to a fully automated burn transaction). This method converts a given transaction to a burn transaction.
The method adds proof data to the transaction, extracts the transaction vouts, calculates their value, and burns the value by sending it to an opreturn vout. This vout is then added to the created transaction. (An opreturn vout cannot be spent at a later date, and therefore funds sent to an opreturn vout are permanently burnt.)
The other returned value, payouts, is used in the migrate_createimporttransaction method.
The caller of the method bears the responsibility to fund and sign the returned burn transaction using the methods fundrawtransaction and signrawtransaction.
The signed burn transaction must be broadcast to the source chain using the sendrawtansaction method.
::: warning Limitations
The migrate_converttoexport method supports only coins (tokens are not supported)
The burn transaction must be stored in the import transaction's opreturn vout. Because an opreturn's data size is limited to 10,001 bytes, we recommend that the user limit the burn transaction's size to 30% of the opreturn object
:::
Arguments
Name
Type
Description
"burntx"
(string, required)
the burn transaction in hex format
"destChain"
(string, required)
the name of the destination chain
Response
Name
Type
Description
"payouts"
(string)
a hex string of the created payouts; this is passed into the migrate_createimporttransaction method
The migrate_createimporttransaction method performs the initial step in creating an import transaction. This method should be called on the source chain.
This method returns a created import transaction in hex format. This string should be passed to the migrate_completeimporttransaction method on the main KMD chain to be extended with the MoMoM proof object.
When using the MoMoM backup solution (described later), the created import transaction is not passed to the migrate_completeimporttransaction method.
The user may need to wait for some time before the back notarizations objects are stored in the destination chain.
Arguments
Name
Type
Description
"burntx"
(string, required)
the burn transaction in hex format returned from the previous method
"payouts"
(string, required)
the payouts object in hex format returned from the previous method and used for creating an import transaction
"notaryTxid1"
(string, optional)
the notary approval transaction id 1, to be passed if the MoMoM backup solution is used for notarization
"notaryTxidN"
(string, optional)
the notary approval transaction id N, to be passed if the MoMoM backup solution is used for notarization
The migrate_completeimporttransaction method performs the finalizing step in creating an import transaction. This method should be called on the KMD (Komodo) chain.
This method returns the import transaction in hex format, updated with the MoMoM proof object. This object provides confirmation that the burn transaction exists in the source chain.
The finalized import transaction should be broadcast on the destination chain through the sendrawtransaction method.
Komodo recommends that the user wait until the notarization objects are stored in the destination chain before broadcasting the import transaction. Otherwise an error message is returned.
In the event that an error is returned, simply wait until the notarization objects are stored in the KMD chain and try again.
Arguments
Name
Type
Description
"importtx"
(string, required)
the import transaction in hex format created using the previous method
"offset"
(string, optional)
the number of blocks below the current KMD(Komodo) blockchain height in which a MoMoM proof must be searched
Response
Name
Type
Description
"ImportTxHex"
(string)
import transaction in hex extended with the MoMoM proof of burn transaction
There is an alternative solution to notarize burn transactions. This method is useful when the automated MoMoM notarization method fails or is slow.
In this method, the user sends burn transactions to a special publishing resource that is monitored by the notary operators. The notary operators check this publishing resource, pick a burn transaction, validate and check the existence of the burn transaction in its source chain. The notary operators then create an approval transaction in the destination chain and return the transaction ids to the publishing resource.
Alternative Transfer Method Flow
A user creates a burn transaction using the migrate_createburntransaction method and publishes the transaction in hex format to a publishing resource
The publishing resource is monitored by the notary operators (currently the discord channel: #cc-momom)
The notary operators must collect the burn transaction, and check its validity and existence in the source chain
To check the transaction, the notary operators use the migrate_checkburntransactionsource method
If the burn transaction is successfully validated, the notary operators must create approval transactions using the method migrate_createnotaryapprovaltransaction in the destination chain and publish their transaction ids back into the publishing resource
The user collects the transaction ids and calls the migrate_createimporttransaction method, passing the collected notary approval transaction ids as arguments in the destination chain
Currently, the user must have at least 5 successful notary-approval transactions for an import transaction to be considered as valid in the destination chain
migrate_checkburntransactionsource
migrate_checkburntransactionsource burntxid
The migrate_checkburntransactionsource method allows a notary operator to check the burn transaction's structure and verify its presence in the source chain.
Arguments
Name
Type
Description
"burntxid"
(string, required)
the burn transaction's id
Response
Name
Type
Description
"sourceSymbol"
(string)
the source chain's name
"targetSymbol"
(string)
the target chain's name
"targetCCid"
(number)
the target chain's CCid
"tokenid"
(string, optional)
the token id if a token is to be migrated
"TxOutProof"
(string)
the proof of the burn transaction's existence in the source chain
A notary operator uses the migrate_createnotaryapprovaltransaction method to create an approval transaction in the destination chain with the proof of the burn transaction's existence in the source chain.
The returned notary approval transaction should be broadcast to the destination chain using the sendrawtransaction method.
The Self Import API is a special API available only in chains that need a pubkey to create new coins arbitrarily.
selfimport
selfimport destAddress amount
The Self Import API allows a trusted pubkey to create more coins on the same chain.
Requirements
The chain must have the custom parameters -ac_import=PUBKEY and -ac_pubkey set to a pubkey which is allowed to create coins.
Self Import Flow
For creating more coins in the chain with -ac_import=PUBKEY enabled, use the selfimport method
The method returns a source transaction that contains a parameter with the amount of coins to create
The returned value is a proof of the trusted pubkey owner's intention to create new coins in the chain
The returned source transaction should be broadcast to the chain using the sendrawtransaction method. The source transaction spends a txfee=10000 satoshis from the -ac_pubkey owner's uxtos
After the source transaction is mined, the import transaction should also be broadcasted to the chain with the sendrawtransaction method. After this transaction is mined, its vout contains the amount of created coins in the chosen destination address
Arguments
Name
Type
Description
"destAddress"
(string, required)
the address where the created coins should be sent
./komodod -ac_name=IMPORTTEST -ac_import=PUBKEY -ac_pubkey=0257e1074b542c47cd6f603e3d78400045df0781875f698138e92cb03055286634 -ac_supply=777777 -ac_reward=100000000 -addnode=<ip address of Node1>
Notice that there is only -ac_pubkey in the above command but not pubkey. That's because, -ac_pubkey is part of the chain parameters and -pubkey is just indicating the pubkey to the particular daemon for various features.
Verify that connections:1 from the getinfo method.
Confirm that the address given to the selfimport command received the newly created funds.
Notary API
The following methods are available to the notary nodes for retrieving the blockchain "fingerprints" and notarization data.
calc_MoM
calc_MoM height MoMdepth
The calc_MoM method calculates the value of the merkle root of the blocks' merkle roots (MoM), starting from the block of the indicated height for the chosen depth.
:::tip Note This method should be run on a Smart Chain. :::
Arguments
Name
Type
Description
"height"
(number, required)
the block height from which the MoM calculation must begin
"MoMdepth"
(number, required)
the number of blocks to include in the MoM calculation
Response
Name
Type
Description
"coin"
(string)
the chain's name
"height"
(string)
the starting block height
"MoMdepth"
(number)
the number of blocks included in the MoM calculation
The MoMoMdata method calculates the value of the merkle root of merkle roots of the blocks' merkle roots (MoMoM), starting from the block of the indicated height for the data of the indicated chain.
:::tip Note
Execute this method on the KMD chain.
:::
Arguments
Name
Type
Description
"symbol"
(string, required)
the chain's name whose data's MoMoM value is to be calculated
"kmdheight"
(number, required)
the number of blocks to include in the MoM calculation
"ccid"
(number, required)
the chain's CCid
Response
Name
Type
Description
"coin"
(string)
the chain's name
"kmdheight"
(string)
the starting block's height
"ccid"
(number)
the chain's CCid
"MoMs"
(string)
the array of MoM values
"notarizationHash"
(string)
the first found notarization transaction id for the chain
The assetchainproof method scans the chain for the back MoM notarization for a transaction corresponding to the given transaction id and returns a proof object with MoM branch. Scanning is performed from the height up to the chain tip, with a limit of 1440 blocks.
Arguments
Name
Type
Description
"txid"
(string, required)
the transaction id for which a proof object must be returned
Response
Name
Type
Description
"proof object"
(string)
the returned proof object with MoM branch in hex format
scanNotarisationsDB blockHeight symbol [blocksLimit=1440]
The scanNotarisationsDB method scans the notarization database backwards from the given block height for a notarization of the chain with the given name (symbol).
Arguments
Name
Type
Description
"blockHeight"
(number, required)
the starting block height from which notarizations are to be searched
"symbol"
(string, required)
the chain's name whose notarizations are to be searched
"blocksLimit"
(number, optional)
an optional block depth to search for notarizations
Response
Name
Type
Description
"height"
(number)
the block height of the notarization transaction id that has been found
"hash"
(string)
the hash of the notarization transaction id that has been found