Bridging ERC20 Tokens to MEM Protocol
This repository focuses on a design for a lock-mint ERC20 bridge to the MEM protocol. The bridge's tech stack utilizes MEM serverless functions, MEM molecules, EVM smart contracts, and Chainlink's AnyAPI.
This is an experimental bridge, unaudited and not tested on mainnet, don't use it in production
git clone https://github.com/mem-fdn/mem-bridge.git
cd mem-bridge
npm install && npm run start
npm i -g mem-cli-js
And to deploy the /contracts/mem
functions:
cd contracts
cd mem
mem deploy --src ./bridge.js --init-state bridge.json
If you intend to modify and test the code yourself, please ensure to follow these steps:
-
Update the new
bridge.sol
contract address in the/src/utils/constants.js
file. -
Update the bridge address in the MEM function state (and redeploy it) located at
./contracts/mem/state.json
. -
After redeploying the MEM changes, obtain a new function ID that you must update again in
/src/utils/constants.js
. -
If you change the API endpoint, make sure to update it in the
./contracts/evm/bridge.sol
contract.
These modifications are essential to ensure that the API, which Chainlink interacts with and is hosted under 0xmem.net, accurately reads the token changes.
This section elucidates the transaction lifecycle of a lock-mint process:
-
User Initiates Locking:
- The user calls the
lock()
function frombridge.sol
.
- The user calls the
-
Verification and Execution:
- Dapps retrieve the resulting TXID from step 1 and invoke the
executeLock()
function in thebridge.js
serverless function. - This function verifies the data from the TXID of the lock function using the MEM molecule (
/vl/
server endpoint).
- Dapps retrieve the resulting TXID from step 1 and invoke the
-
Mirror of Token Balance:
- The
executeLock()
MEM function mirrors the token balance locked inbridge.sol
, effectively bridging tokens to the MEM protocol.
- The
-
Initiating Unlock Process:
- To bridge tokens back to the EVM network, the user calls the
initiateUnlock()
function inbridge.js
, providing a uniquecaller
for authentication and assigning it to themid
ormemid
data property. - This function removes the caller's balance from circulation on the MEM side.
- To bridge tokens back to the EVM network, the user calls the
-
Unlock Validation:
- The caller retrieves the resulting
mid
from./mem/bridge.json
and calls thevalidateUnlock()
function inbridge.sol
. - This function utilizes Chainlink's AnyAPI node to read back from MEM function state, verifying the issued unlock status and authorized amount. It also verifies the
caller
withmsg.sender
. - Additionally, it maps the oracle request ID to
msg.sender
(reqToCaller()
), the unique request ID to the uniquemid
(reqToMemId
), and themid
to redeeming status (midIsRedeemed
).
- The caller retrieves the resulting
-
Fulfillment by Chainlink Node:
- The Chainlink node invokes the
fulfill()
function to update the contract state variables (maps) with the authorized token unlock amount for the givenmid
ormemid
per caller (msg.sender
).
- The Chainlink node invokes the
-
Execution of Unlock:
- The user retrieves the request ID from the TXID resulting from
validateUnlock()
and then callsexecuteUnlock()
on the solidity contract. - The
executeUnlock()
function unlocks the token on EVM based on the validity of the initialmemid
per request ID.
- The user retrieves the request ID from the TXID resulting from
- The contract utilizes LinkWell Nodes as the Chainlink oracle provider.
- The
constructor()
function is commented with initial values used for testing purposes. - The bridge has been tested to bridge Sepolia Chainlink token ($LINK -
0x779877A7B0D9E8603169DdbD7836e478b4624789
). - The current repository version has been tested using 0xe1225ecbBDAB62Eba6F2Bc4366B7A6943F07A5e0 for
bridge.sol
, KHuOj-dvS7VLfuTNKz3GBr2LmwlP2kBfDc_4iFoRzKw forbridge.js
, and 0xmem.net for the API called by Chainlink.
This is an experimental bridge, and it has not undergone auditing or testing on the mainnet. Do not use it in production environments.
This repository is licensed under the MIT License