Name: parity-bridge
Owner: Parity Technologies
Description: Bridge between any two ethereum-based networks
Created: 2017-08-13 17:38:20.0
Updated: 2018-05-17 08:40:14.0
Pushed: 2018-05-24 06:10:37.0
Size: 862
Language: Rust
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
DISCLAIMER: we recommend not using the bridge in “production” (to bridge significant amounts) just yet. it's missing a code audit and should still be considered alpha. we can't rule out that there are bugs that might result in loss of the bridged amounts. we'll update this disclaimer once that changes
parity-bridge is currently an ERC20 token contract on one ethereum-based blockchain that is backed by ether on another ethereum-based blockchain.
eventually parity-bridge will be able to pass arbitrary messages between two ethereum-based blockchains. in the future you'll be able to build the current ether-ERC20 bridge and any other cross-chain application on top of the message passing bridge.
currently users can convert ether on one chain into the same amount of ERC20 tokens on the other and back. the bridge securely relays these conversions.
the bridge can mitigate scaling issues: by deploying a proof-of-authority network and bridging it to the Ethereum Foundation network ('mainnet') users can convert their mainnet ether into ERC20 tokens on the PoA chain and there transfer them with much lower transaction fees, faster block times and unaffected by mainnet congestion.
the users can withdraw their tokens worth of ether on the mainnet at any point.
parity is using the bridge project to prototype the system that will eventually connect ethereum and other non-parachains to polkadot.
the bridge connects two chains home
and foreign
.
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, homeGasPrice)
.
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
.
sender
deposits value
into HomeBridge
.
the HomeBridge
fallback function emits Deposit(sender, value)
.
for each Deposit
event on HomeBridge
every authority executes
ForeignBridge.deposit(sender, value, transactionHash)
.
once there are ForeignBridge.requiredSignatures
such transactions
with identical arguments and from distinct authorities then
ForeignBridge.balanceOf(sender)
is increased by value
.
sender
executes ForeignBridge.transferHomeViaRelay(recipient, value, homeGasPrice)
which checks and reduces ForeignBridge.balances(sender)
by value
and emits ForeignBridge.Withdraw(recipient, value, homeGasPrice)
.
for every ForeignBridge.Withdraw
, every bridge authority creates a message containing
value
, recipient
and the transactionHash
of the transaction referenced by the ForeignBridge.Withdraw
event;
signs that message and executes ForeignBridge.submitSignature(signature, message)
.
this collection of signatures is on foreign
because transactions are free for the authorities on foreign
,
but not free on home
.
once ForeignBridge.requiredSignatures
signatures by distinct authorities are collected
a ForeignBridge.CollectedSignatures(authorityThatSubmittedLastSignature, messageHash)
event is emitted.
everyone (usually authorityThatSubmittedLastSignature
) can then call ForeignBridge.message(messageHash)
and
ForeignBridge.signature(messageHash, 0..requiredSignatures)
to look up the message and signatures and execute HomeBridge.withdraw(vs, rs, ss, message)
and complete the withdraw.
HomeBridge.withdraw(vs, rs, ss, message)
recovers the addresses from the signatures,
checks that enough authorities in its authority list have signed and
finally transfers value
ether (minus the relay gas costs)
to recipient
.
requires yarn
to be $PATH
. installation instructions
ruffle
test
requires rust
and cargo
: installation instructions.
requires solc
: installation instructions.
assuming you've cloned the bridge (git clone git@github.com:paritytech/parity-bridge.git
)
and are in the project directory (cd parity-bridge
) run:
o build -p parity-bridge --release
to install copy target/release/parity-bridge
into a folder that's in your $PATH
.
RUST_LOG=info parity-bridge --config config.toml --database db.toml
--config
- location of the configuration file. configuration file must exist--database
- location of the database file.
if there is no file at specified location, new bridge contracts will be deployed
and new database will be createdthe bridge is configured through a configuration file.
here's an example configuration file: integration-tests/bridge_config.toml
following is a detailed explanation of all config options. all fields are required unless marked with optional.
estimated_gas_cost_of_withdraw
- an upper bound on the gas a transaction to HomeBridge.withdraw
consumes"200000"
toml
crate can't parse numbers greater max i64max_total_home_contract_balance
- reject deposits that would increase HomeBridge.balance
beyond this value"0"
to disable."10000000000000000000"
toml
crate can't parse numbers greater max i64
and this value frequently is greatermax_single_deposit_value
- reject deposits whose msg.value
is higher than this value"1000000000000000000"
toml
crate can't parse numbers greater max i64
and this value frequently is greaterhome.account
- address of this bridge authority on home
chainhome.ipc
- path to the ipc socket of a parity node that has home.account
unlockedhome.contract.bin
- path to the compiled HomeBridge
contractcompiled_contracts
compiled_contracts/HomeBridge.bin
home.required_confirmations
- number of confirmations required to consider transaction final on home.ipc
home.poll_interval
- specify how frequently (seconds) home.ipc
should be polled for changeshome.request_timeout
- how many seconds to wait for responses from home.ipc
before timing outforeign.account
- address of this bridge authority on home
chainhome.account
foreign.ipc
- path to the ipc socket of a parity node that has foreign.account
unlockedforeign.contract.bin
- path to the compiled ForeignBridge
contractcompiled_contracts
compiled_contracts/ForeignBridge.bin
foreign.required_confirmations
- number of confirmations required to consider transaction final on foreign.ipc
foreign.poll_interval
- specify how frequently (seconds) foreign.ipc
should be polled for changesforeign.request_timeout
- how many seconds to wait for responses from foreign.ipc
before timing outauthorities.account
- array of addresses of authoritiesauthorities.required_signatures
- number of authorities signatures required to consider action finalgas
and gas_price
to use for the specific transactions.
these are all optional and default to 0
.
look into the [transactions]
section in integration-tests/bridge_config.toml
for recommendations on provided gas
.
home
:transaction.home_deploy.gas
transaction.home_deploy.gas_price
transaction.withdraw_relay.gas
transaction.withdraw_relay.gas_price
foreign
:transaction.foreign_deploy.gas
transaction.foreign_deploy.gas_price
transaction.deposit_relay.gas
transaction.deposit_relay.gas_price
transaction.withdraw_confirm.gas
transaction.withdraw_confirm.gas_price
_contract_address = "0x49edf201c1e139282643d5e7c6fb0c7219ad1db7"
ign_contract_address = "0x49edf201c1e139282643d5e7c6fb0c7219ad1db8"
_deploy = 100
ign_deploy = 101
ked_deposit_relay = 120
ked_withdraw_relay = 121
ked_withdraw_confirm = 121
all fields are required
home_contract_address
- address of the bridge contract on home chainforeign_contract_address
- address of the bridge contract on foreign chainhome_deploy
- block number at which home contract has been deployedforeign_deploy
- block number at which foreign contract has been deployedchecked_deposit_relay
- number of the last block for which an authority has relayed deposits to the foreignchecked_withdraw_relay
- number of the last block for which an authority has relayed withdraws to the homechecked_withdraw_confirm
- number of the last block for which an authority has confirmed withdrawrget/release/bridge --config examples/config.toml --database db.toml
examples/parity_start.sh
home
, whereas the other as foreign
this is sparta
- 0x006e27b6a72e1f34c626762f3c4761547aff1421
a bridge authority
has to pay for gas (cost
) to execute HomeBridge.withdraw
when
withdrawing value
from foreign
chain to home
chain.
value - cost
is transferred to the recipient
. cost
is transferred to the authority
executing HomeBridge.withdraw
.
the recipient
pays the relaying authority
for the execution of the transaction.
that shuts down an attack that enabled exhaustion of authorities funds on home
.
read on for a more thorough explanation.
parity-bridge connects a value-bearing ethereum blockchain home
(initially the ethereum foundation chain)
to a non-value-bearing PoA ethereum blockchain foreign
(initially the kovan testnet).
value-bearing means that the ether on that chain has usable value in the sense that in order to obtain it one has to either mine it (trade in electricity) or trade in another currency. non-value-bearing means that one can easily obtain a large amount of ether on that chain for free. through a faucet in the case of testnets for example.
the bridge authorities are also the validators of the foreign
PoA chain.
transactions by the authorities are therefore free (gas price = 0) on foreign
.
to execute a transaction on home
a bridge authority has to spend ether to
pay for the gas.
this opened up an attack where a malicious user could
deposit a very small amount of wei on HomeBridge
, get it relayed to ForeignBridge
,
then spam ForeignBridge.transferHomeViaRelay
with 1
wei withdraws.
it would cost the attacker very little home
chain wei and essentially
free foreign
testnet wei to cause the authorities to spend orders of magnitude more wei
to relay the withdraw to home
by executing HomeBridge.withdraw
.
an attacker was able to exhaust bridge authorities funds on home
.
to shut down this attack HomeBridge.withdraw
was modified so
value - cost
is transferred to the recipient
and cost
is transferred to the authority
doing the relay.
this way the recipient
pays the relaying authority
for the execution of the withdraw
transaction.
relayers can set the gas price for HomeBridge.withdraw
.
they could set a very high gas price resulting in a very high cost
through which they could burn large portions of value
.
to shut down this attack the homeGasPrice
param was added to ForeignBridge.transferHomeViaRelay
.
end users have control over the cost/latency tradeoff of their relay transaction through the homeGasPrice
.
relayers have to set gas price to homeGasPrice
when calling HomeBridge.withdraw
.
the recipient
for value
is the exception and can freely choose any gas price.
see https://github.com/paritytech/parity-bridge/issues/112 for more details.
HomeBridge.withdraw
is currently the only transaction bridge authorities execute on home
.
care must be taken to secure future functions that bridge authorities will execute
on home
in similar ways.