# LUKSO tokenbridge architecture

https://github.com/crosschain-alliance/lukso-tokenbridge

## Workflow (Ethereum → LUKSO)


**Ethereum**

1. User transfer ERC20 token to Hyp Collateral contract and the token is locked in the collateral contract.
2. Hyp Collateral contract call Mailbox to pass the message.
3. Mailbox call Default Hook (created by Hyperlane) and Hashi Hook (created by CCIA team).
4. Hashi Hook dispatch the token relaying message from Yaho contracts.

**Off chain**

1. ZK light client will update the header from Ethereum periodically on LUKSO.
1. Zk Light Client will listen to the `MessageDispatched` event from Yaho, generate proof, and verify on the adapter contract.
1. Hashi [executor](https://github.com/gnosis/hashi/tree/feat/v0.2.0/packages/executor) (managed by CCIA team) will listen to event from each Hashi adapter contracts and call Yaru.executeMessages. This step will check whether the Hashi adapters agree on a specify message id (a threshold number of hash is stored), and set the message Id to verified status.
1. [Validator](https://docs.hyperlane.xyz/docs/protocol/agents/validators) (run by Hyperlane & LUKSO team) will sign the Merkle root when new dispatches happen in Mailbox.
1. [Hyperlane relayer](https://docs.hyperlane.xyz/docs/protocol/agents/relayer) (run by Hyperlane team) relays the message by calling Mailbox.process().

**LUKSO**

1. When Mailbox.process() is called, it will verify with Static Aggregation ISM (aggregate result from Hyperlane default ISM, Multisig ISM (validated by LUKSO validator), Hashi ISM). If so, it will mint hypERC20 token to the receiver.
2. For compatibility, LSP7 wrapper need to be created to mint LSP7 token to the user.

## Workflow ( LUKSO → Ethereum)


**LUKSO**

1. User transfer LSP7 token to HypLSP7 contract and the token is locked.
2. HypLSP7 contract call Mailbox to pass the message.
3. Mailbox call Default Hook (created by Hyperlane) and Hashi Hook (created by CCIA team).
4. Hashi Hook dispatch the token relaying message from Yaho contracts.

**Off chain**

1. Off chain process remains the same as the previous section.

**Ethereum**

1. When Mailbox.process() is called, it will check with Static Aggregation ISM (aggregate result from Hyperlane defualt ISM, Multisig ISM (validated by LUKSO validator), Hashi ISM). If so, it will unlock ERC20 token to the receiver.

# Contract addresses
## Testnet
1. Hashi: [0x94c04fE1d20B0c3fcADB44C042c38C4E337Ccc49](https://explorer.execution.testnet.lukso.network/address/0x94c04fE1d20B0c3fcADB44C042c38C4E337Ccc49?tab=contract)
2. Header Storage: [0xE644169dd6E3c375772386dF39Ef6F2928Df921a](https://explorer.execution.testnet.lukso.network/address/0xE644169dd6E3c375772386dF39Ef6F2928Df921a#code)
3. Yaho: [0x58CCfAadc4E9A8f3448494281d030843dE137B8c](https://explorer.execution.testnet.lukso.network/address/0x58CCfAadc4E9A8f3448494281d030843dE137B8c#code)
4. Yaru(w.r.t Sepolia): [0xBd5CE0aAE635B36Eec47018aA42e1A322CE26A54](https://explorer.execution.testnet.lukso.network/address/0xBd5CE0aAE635B36Eec47018aA42e1A322CE26A54#code)
5. DendrETH Adapter(w.r.t Sepolia): [0xD875797F284887296B8812a8E50a1da3AD92f6Da](https://explorer.consensus.testnet.lukso.network/address/0xD875797F284887296B8812a8E50a1da3AD92f6Da)
6. pingpong: [0xbD5210A110830f42e18AC6490431713bA2A61eDd](https://explorer.execution.testnet.lukso.network/address/0xbD5210A110830f42e18AC6490431713bA2A61eDd#code)
7. Mock Adapter: [0x6f9021F5aAf61da91ce7F7D477E346d83bfdFee2](https://explorer.execution.testnet.lukso.network/address/0x6f9021F5aAf61da91ce7F7D477E346d83bfdFee2#code)
8. Mock Reporter: [0xeC1DD85CEff76F9C69c24C3945af624B3941aA22](https://explorer.execution.testnet.lukso.network/address/0xeC1DD85CEff76F9C69c24C3945af624B3941aA22#code)

Sepolia

1. Yaru(w.r.t LUKSO): [0x05B40580B851eA6c73CEd39d5c8aB91bAd7C4FF7](https://sepolia.etherscan.io/address/0x05B40580B851eA6c73CEd39d5c8aB91bAd7C4FF7#readProxyContract)
2. pingpong: [x53B79b9173Ac01E879D59523d8920212400c57C6](https://sepolia.etherscan.io/address/0x53B79b9173Ac01E879D59523d8920212400c57C6#code)

More on https://crosschain-alliance.gitbook.io/hashi/v0.2/deployment#testnet

PingPong task: https://github.com/crosschain-alliance/lukso-tokenbridge/blob/main/task/pingpong.js

## Mainnet

## Ethereum

### Hyperlane components
1. StaticAggregationHook: [0xe42216a313d224658cfc324415005f771a3e7e96](https://etherscan.io/address/0xe42216a313d224658cfc324415005f771a3e7e96)
- [Default Hook](https://github.com/hyperlane-xyz/hyperlane-registry/blob/main/chains/ethereum/addresses.yaml#L4) +[Hashi Hook](https://etherscan.io/address/0x050c0c205ceB17d7388F9B0e45919Ba82480D93b)
3. StaticAggregationISM:
- [Default ISM](https://github.com/hyperlane-xyz/hyperlane-registry/blob/main/chains/ethereum/addresses.yaml#L8) + [MultisigISM (LUKSO validator)](https://etherscan.io/address/0x65b9b2ad51e38cdc8e62dd0c3c19995267dc177c)(0x936b6a667E4334cA58e09A7C3d0D0265d1432A8C) + [Hashi ISM](https://etherscan.io/address/0x54F42816229F0022c2EcD4d05c9f823a9d7F3093)
- Threshold: 3 [0x10c82311163218d6ec8cfb42a6441f1794b5b579](https://etherscan.io/address/0x10c82311163218d6ec8cfb42a6441f1794b5b579)
- Threshold: 2 [0x14db211592d31302962e74ecf4c5f6eb6ee3d783](https://etherscan.io/address/0x14db211592d31302962e74ecf4c5f6eb6ee3d783)
### Hashi Componetns
1. Hashi Hook: [0x050c0c205ceB17d7388F9B0e45919Ba82480D93b](https://etherscan.io/address/0x050c0c205ceB17d7388F9B0e45919Ba82480D93b)
2. Hashi ISM:[0x54F42816229F0022c2EcD4d05c9f823a9d7F3093](https://etherscan.io/address/0x54F42816229F0022c2EcD4d05c9f823a9d7F3093)
3. Hashi Manager: [0xa1836695013CE41C487a6DbDD0AB137dB603f036](https://etherscan.io/address/0xa1836695013CE41C487a6DbDD0AB137dB603f036#code)
6. Yaho: [0xbAE4Ebbf42815BB9Bc3720267Ea4496277d60DB8](https://etherscan.io/address/0xbAE4Ebbf42815BB9Bc3720267Ea4496277d60DB8)
7. Yaru(w.r.t LUKSO): [0x5e499f1845dEE19FD1eFdD4A9bf17c21446f613E](https://etherscan.io/address/0x5e499f1845dEE19FD1eFdD4A9bf17c21446f613E#readContract)

## LUKSO
### Hyperlane componetns
1. StaticAggregationHook: [0xd9ea210350751d5c7323abcaadebacd9d1960505](https://explorer.execution.mainnet.lukso.network/address/0xd9ea210350751d5c7323abcaadebacd9d1960505)
- [Default Hook](https://github.com/hyperlane-xyz/hyperlane-registry/blob/main/chains/lukso/addresses.yaml#L4) + [Hashi Hook](https://explorer.lukso.network/address/0xd270F259198340da5987a350b04b88139D304562)
3. StaticAggregationISM:
- [Default ISM](https://github.com/hyperlane-xyz/hyperlane-registry/blob/main/chains/lukso/addresses.yaml#L8) + [MulitsigISM (LUKSO validator)](https://explorer.execution.mainnet.lukso.network/address/0xa03eE82a353646c0047e607d7DcafF3de59BE628)(0x4e2555edeC23C92F135D6155BC6ccC8Ee57a6BD6) + [Hashi ISM]()
- Threshold: 3 0xf8199F8E39e1D7B70062E27AE1Fd0C0E778b6752
- Threshold: 2 0x0267f3ad580269b8ace60fa4d8b16bfd92cee2c9

### Hashi components
1. Hashi Hook:[0xd270F259198340da5987a350b04b88139D304562](https://explorer.lukso.network/address/0xd270F259198340da5987a350b04b88139D304562)
2. Hashi ISM:[0xdB5BfacbEa5ff1Dee5d8aACB48021c6F6Bc59930](https://explorer.execution.mainnet.lukso.network/address/0xdB5BfacbEa5ff1Dee5d8aACB48021c6F6Bc59930)
4. Hashi Manager: [0x998dA7f6cF98541E4F4469cc9d53B9374F186591](https://explorer.lukso.network/address/0x998dA7f6cF98541E4F4469cc9d53B9374F186591?tab=contract)
5. Yaho: [0xbAE4Ebbf42815BB9Bc3720267Ea4496277d60DB8](https://explorer.lukso.network/address/0xbAE4Ebbf42815BB9Bc3720267Ea4496277d60DB8)
6. Yaru (w.r.t Ehtereum): [0x5e499f1845dEE19FD1eFdD4A9bf17c21446f613E](https://explorer.lukso.network/address/0x5e499f1845dEE19FD1eFdD4A9bf17c21446f613E)

# Example e2e transactions
## Testnet Transactions

### Light Client verification

1. DendrETH Adapter verify MessageDispatched event (from Yaho on Sepolia): https://explorer.execution.testnet.lukso.network/tx/0x462ca7b88715f07a94d62faf61fbcbfd4aa80f312316a4dfd8567eca69ea168a
1. DendrETH Adapter on LUKSO testnet [0xF02162C83CD4bD876E9C5Dc6A47ba8bfbd5ba7dB](https://explorer.execution.testnet.lukso.network/address/0xF02162C83CD4bD876E9C5Dc6A47ba8bfbd5ba7dB)

### Message Dispatching

**Sepolia→Chiado**

1. Sepolia ping
1. https://sepolia.etherscan.io/tx/0xffb794b6323487e0cdc76346985354e78540545028a91b669658d2da160e31e4
2. LUKSO testnet MockAdapter setHashes
1. https://explorer.execution.testnet.lukso.network/tx/0x2a99c4bce8ada76e55fe39f5dd136e474e2842593a10820f66f4d334f80faa25
3. LUKSO testnet Yaru executeMessages
1. https://explorer.execution.testnet.lukso.network/tx/0x2099b5604d274fd225d68635b39278c05ef93650450094fe7a41476efc5dc0f8?tab=index

**Chiado→Sepolia**

1. LUKSO ping
1. https://explorer.execution.testnet.lukso.network/tx/0x126997f8b6df6af7a73ac80bd896f22e7131da7104649d0ad3803cce52e92f82
2. Sepolia MockAdapter setHashes
1. https://sepolia.etherscan.io/tx/0x72dc612075e8666b6dfa2a66f184e8e67174de03d66c0413897195252f9632da
3. Sepolia Yaru executeMessages
1. https://sepolia.etherscan.io/tx/0x9abff3c1e0b376c5282ae52583a2aec707a7d2d64f28a0ed2da2790599d02938

## Mainnet Transactions
### ETH -> LUKSO
https://explorer.hyperlane.xyz/message/0x53a383e32fdb68748c8af5c86be3669e58eadc377db2a9f420826cb9474dd55c
**Transactions breakdown:**
1. Send ERC20 from Ethereum (after approval): https://etherscan.io/tx/0x3fa1fdb2ab3b6ef4e502c5281000b2dd625f25b6c08baa11344008af07d4dfa0
2. Yaho relayMessagesToAdapter: https://etherscan.io/tx/0x3fa1fdb2ab3b6ef4e502c5281000b2dd625f25b6c08baa11344008af07d4dfa0
3. Adapter setHashes: https://explorer.execution.mainnet.lukso.network/tx/0x079bfc0ad3c54c00e20161d8b6571b3766a235445552b48c18353023cd605b99
4. Yaru executeMessages: https://explorer.execution.mainnet.lukso.network/tx/0x9e24f4c5a29823da4f3cae7fbef60bfae20e94f9f92f14da712908838c8938a8
5. Mailbox process: https://explorer.execution.mainnet.lukso.network/tx/0x097fd172d99d540104ca202d344007870f18a2f6319e6440afb0cb71afc40ec9

### LUKSO -> ETH
https://explorer.hyperlane.xyz/message/0xf9c86a22e7b5584fc87a9d4ffc39f967a8745cd28b98ed2eaeb220c43996c4ca
**Transactions breakdown:**
1. Send HypERC20 from LUKSO: https://explorer.execution.mainnet.lukso.network/tx/0x7b3f4165155b06fdc5b6df89890c578cfc5535d005a11dc611eb591ae5a43d74
2. Yaho relayMessagesToAdapter: https://explorer.lukso.network/tx/0x7b3f4165155b06fdc5b6df89890c578cfc5535d005a11dc611eb591ae5a43d74
3. Adapter setHashes: https://etherscan.io/tx/0x69a92417eba2f675b7978f540e30bab477daad85f4a8c0b14ceb15a477768259
4. Yaru executeMessages: https://etherscan.io/tx/0x528032f7ac7066175908ad40edcb30ada1096990a88a632f87c4da6a40444e64
5. Mailbox process: https://etherscan.io/tx/0xe1ddb7eacf14a6f4fb6793de273d49a97b43a71a43ac0ffd4da799ce773dbdca

## Reference

### Hyperlane

1. Warp Route: https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/README.md
2. **Implement Connext xERC20 and Circle FiatToken collateral:** https://github.com/hyperlane-xyz/hyperlane-monorepo/pull/3618
3. Hyperlane core contracts on LUKSO: https://github.com/hyperlane-xyz/hyperlane-registry/blob/main/chains/lukso/addresses.yaml

### Hashi

1. Hashi ISM: https://github.com/crosschain-alliance/lukso-tokenbridge/tree/main/contracts
2. Hashi: https://github.com/gnosis/hashi

### LUKSO

1. LSP7: https://docs.lukso.tech/standards/tokens/LSP7-Digital-Asset/