poanetwork
/
poa-bridge
mirror of https://github.com/poanetwork/poa-bridge.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

README.md: improve explanation and update for ERC20

This commit is contained in:
Maximilian Krüger 2018-01-26 09:43:21 +01:00
parent 1b454204c5
commit fbefc5e9ec
1 changed files with 41 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
README.md
View File

@ -8,17 +8,27 @@
[coveralls-image]: https://coveralls.io/repos/github/paritytech/parity-bridge/badge.svg?branch=master [coveralls-image]: https://coveralls.io/repos/github/paritytech/parity-bridge/badge.svg?branch=master
[coveralls-url]: https://coveralls.io/github/paritytech/parity-bridge?branch=master [coveralls-url]: https://coveralls.io/github/paritytech/parity-bridge?branch=master
the parity bridge connects two ethereum blockchains, `home` and `foreign`. the bridge is an
[ERC20 token](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20-token-standard.md)
contract that is backed by ether on **another** ethereum blockchain.
### current functionality given a bridge between two chains
users can freely convert any amount of ether
one one chain into the same amount of ERC20 tokens on the other and back.
the bridge securely relays these conversions.
the bridge allows users to deposit ether into a smart contract on `home` **the bridge can solve scaling issues:**
and get it on `foreign` in form of an ERC20 token. by deploying a [proof-of-authority](https://paritytech.github.io/wiki/Proof-of-Authority-Chains.html)
it also allows users to withdraw their tokens on `foreign` and get the equivalent ether on `home`. network and bridging it to mainnet users can convert their mainnet ether
on `foreign` users can freely transfer tokens between each other. into ERC20 tokens on the PoA chain
and there transfer them with much lower transaction fees,
faster block times and unaffected by mainnet congestion.
`foreign` is assumed to use PoA (proof of authority) consensus. at any point can the users withdraw their tokens worth of ether on the mainnet.
relays between the chains happen in a byzantine fault tolerant way using the authorities of `foreign`.
parity is using the bridge project to prototype
the system that will eventually connect ethereum and other non-parachains to
[polkadot](https://polkadot.io/)
### next steps ### next steps
@ -26,43 +36,52 @@ relays between the chains happen in a byzantine fault tolerant way using the aut
2. make bridge work with contract-based dynamic validator set 2. make bridge work with contract-based dynamic validator set
3. after kovan hardfork 2: deploy to kovan again with dynamic validator set 3. after kovan hardfork 2: deploy to kovan again with dynamic validator set
### eventual goals ### current functionality
connect ethereum to polkadot the bridge connects two chains `home` and `foreign`.
### deposit ether into `HomeBridge` and get it in form of a token balance on `ForeignBridge` when users deposit ether into the `HomeBridge` contract on `home`
they get the same amount of ERC20 tokens on `foreign`.
they can use `ForeignBridge` as they would use any ERC20 token.
to convert their `foreign` ERC20 into ether on `home`
users can always call `ForeignBridge.transferHomeViaRelay(homeRecipientAddress, value)`.
`foreign` is assumed to use PoA (proof of authority) consensus.
relays between the chains happen in a byzantine fault tolerant way using the authorities of `foreign`.
### `home` ether -> `foreign` ERC20
`sender` deposits `value` into `HomeBridge`. `sender` deposits `value` into `HomeBridge`.
the `HomeBridge` fallback function emits `Deposit(sender, value)`. the `HomeBridge` fallback function emits `Deposit(sender, value)`.
for each `Deposit` event on `HomeBridge` every authority makes a transaction
for each `Deposit` event on `HomeBridge` every authority executes
`ForeignBridge.deposit(sender, value, transactionHash)`. `ForeignBridge.deposit(sender, value, transactionHash)`.
once there are `ForeignBridge.requiredSignatures` such transactions once there are `ForeignBridge.requiredSignatures` such transactions
with identical arguments and from distinct authorities then with identical arguments and from distinct authorities then
`ForeignBridge.balances(sender)` is increased by `value` and `ForeignBridge.balanceOf(sender)` is increased by `value`.
`ForeignBridge.Deposit(sender, value)` is emitted.
### withdraw balance on `ForeignBridge` and get it as ether on `home` chain ### `foreign` ERC20 -> `home` ether
`sender` executes `ForeignBridge.transferHomeViaRelay(recipient, value)` `sender` executes `ForeignBridge.transferHomeViaRelay(recipient, value)`
which checks and reduces `ForeignBridge.balances(sender)` by `value` and emits `ForeignBridge.Withdraw(recipient, value)`. which checks and reduces `ForeignBridge.balances(sender)` by `value` and emits `ForeignBridge.Withdraw(recipient, value)`.
for each `ForeignBridge.Withdraw` every bridge authority creates a message containg for each `ForeignBridge.Withdraw` every bridge authority creates a message containg
`value`, `recipient` and the `transactionHash` of the transaction containing the `ForeignBridge.Withdraw` event, `value`, `recipient` and the `transactionHash` of the transaction containing the `ForeignBridge.Withdraw` event,
signs the message and makes a transaction `ForeignBridge.submitSignature(signature, message)`. signs the message and executes `ForeignBridge.submitSignature(signature, message)`.
this collection of signatures on `foreign` is necessary because transactions are free this collection of signatures on `foreign` is necessary because transactions are free
for authorities on `foreign`, since they are the authorities of `foreign`, but not free on `home`. for authorities on `foreign`, since they are the authorities of `foreign`, but not free on `home`.
once `ForeignBridge.requiredSignatures` signatures by distinct authorities are collected once `ForeignBridge.requiredSignatures` signatures by distinct authorities are collected
a `ForeignBridge.CollectedSignatures(authorityThatSubmittedLastSignature, messageHash)` event is emitted. a `ForeignBridge.CollectedSignatures(authorityThatSubmittedLastSignature, messageHash)` event is emitted.
everyone (usually `authorityThatSubmittedLastSignature`) can then call `ForeignBridge.message(messageHash)` and everyone (usually `authorityThatSubmittedLastSignature`) can then call `ForeignBridge.message(messageHash)` and
`ForeignBridge.signature(messageHash, 0..requiredSignatures)` `ForeignBridge.signature(messageHash, 0..requiredSignatures)`
to look up the message and signatures and execute `HomeBridge.withdraw(vs, rs, ss, message)` to look up the message and signatures and execute `HomeBridge.withdraw(vs, rs, ss, message)`
and complete the withdraw. and complete the withdraw.
### transfer on `foreign`
`sender` executes `ForeignBridge.transferLocal(recipient, value)`
which checks and reduces `ForeignBridge.balances(sender)` and increases `ForeignBridge.balances(recipient)`
by `value`.
### build ### build
requires `solc` to be in `$PATH`. [installation instructions](https://solidity.readthedocs.io/en/develop/installing-solidity.html) requires `solc` to be in `$PATH`. [installation instructions](https://solidity.readthedocs.io/en/develop/installing-solidity.html)