This document assumes that the reader has basic knowledge of smart contracts, multisig contracts and Ethereum testnet chains.
The bridge has 3 parts: A contract on the Ethereum Mainnet, a contract on the Rinkeby Testnet, and an off-chain service that connects these two contracts. The off-chain service listens for events from these contracts and relays commands from one contract to the other.
The Giveth Bridge contract on mainnet is simply a vault contract with 1 extra security measure and a few modifications to make it function as a bridge. Payments are only paid out under certain conditions. Every bridge payment has a standard 48-hour time lockout before payment can occur.
During this time, the Security Guard has the ability to delay a payment further than the standard 48 hours - up to 30 days. This allows time to determine whether or not a payment needs to be cancelled. No payments can be issued without a check-in from the Security Guard happening XX minutes after the payment was requested. This check-in will happen daily so as not to delay authorized payments.
There is also an
escapeHatch that can be called by an
escapeHatchCaller to send the funds in the bridge to the funding multisig during the 48 hour delay, or any additional delay generated by the Security Guard.
This funding multisig will for some time also hold funds to diversify risk between the Bridge contract and the Consensus Multisig contract, when the bridge is holding too much value the funding multisig will
escapeFunds() out of the bridge and when the bridge is getting low, the funding multisig will manually top it off.
Donations and withdrawals will happen directly out of the bridge. When a donation is made to the bridge, a token is created by the TokenFactory (at 1:1 ETH) and sent to LiquidPledging, where the decisions are made about spending. When a payment is called for, tokens are sent from Liquid Pledging and burned by the ForeignGivethBridge, at which point the command is issued back across the Ghetto Bridge using the Bridge Key to the Giveth Bridge to issue a payment.
In case for some reason the bridge goes down, the listener service will issue alarms to notify of a service interruption. The listener service will also create an alarm if tokens are created without a corresponding donation, or if tokens are not created at the time of a donation.
This is the Giveth multisig that can issue control commands to the bridge. They can cancel any payment and can boot the Security Guard or remove the approved spender (bridge key).
This multisig is used to both send funds to the Mainnet Bridge (Vault) and act as the destination for the EscapeHatch Call.
Keeps watch over all requested payments, checks in each day, and delays suspicious payments.
This is a 1 of x multisig that can trigger the vault to dump its funds to a predetermined wallet. We have people that are scattered across the world, multiple points of contacts that can do this.
These addresses are a whitelist who can issue a payment request to the bridge contract. In the application the bridge key is the only Allowed Spender.
The bridge key.
This multisig controls updates and has total access to control the ForeignGivethBridge. It also acts as the
escapeHatchDestination for the ForeignGivethBridge and Liquid Pledging.
This is a 1 of x multisig that can trigger the ForeignGivethBridge and Liquid Pledging contracts to dump their tokens to a predetermined wallet.
Bridge Key is compromised: A hacker could use bridge key to create transactions sending ETH to their own address to force transactions through. The Security Guard can delay these payments long enough for the owner multisig to cancel the payment and remove the compromised key on Mainnet.
They could also create GivETH tokens as the token controller on the rinkeby side. The listener service would catch this though and sound the alarm any time GivETH tokens are generated without a corresponding Ether donation. (also sounds an alarm if the bridge key service decided to take a nap and doesn’t create GivETH tokens when a donation is received.)
Owner multisig has a bug and is able to be taken over (like the parity hack) or 6 keys out of 11 of the keys are compromised: This is highly unlikely but if this happens there will be no loss of funds. This multisig doesn't hold any funds, it only controls the bridge. Tt could reduce the 48 hour delay to 25 hours, the Security Guard can still delay any payments but the Security Guard can be replaced by the owner. Funds could be escaped within the 25 hours in this scenario.
EscapeHatchCaller keys get compromised: In this case the worst thing that can happen is that the flow of the DApp on Rinkeby can be disrupted. This can be repaired however, by removing the compromised key on the EscapeHatch 1 of x multisig, and DAppGod. Once that is done then simply sending the giveth tokens back to the address from which they came, a similar scenario is possible on Mainnet. The EscapeHatch Caller can only move money to an escape destination, and nowhere else. If a key is compromised the worst thing they can do is to remove all owners and themselves from the EscapeHatch multisig, but the owner 6 of 11 multisig on main net can still call the EscapeHatch and can replace the EscapeHatch caller and the 3 of 5 multisig on rinkeby can as well.
Funding multisig has a bug and is able to be taken over (like the parity hack) or 4 keys out of 7 of the keys are compromised: This is extremely unlikely but if this happens there will be a loss of funds. The loss however, would not be catastrophic as funds are split between the bridge and the multisig.
Bridge on mainnet has a bug that lets someone else take over as owner: The 48 hour delay can be only be reduced to 25 hours Security Guard can still delay any payments but the Security Guard can be replaced by the owner. Funds could be escaped within 25 hours in this scenario.
DAppGod Multisig on the testnet decides to take over: If this were to occur, the EscapeHatch from the bridge would prevent any loss of funds, and the testnet set up could be manually redeployed.
What if the Security Guard’s key and Bridge Key Controller both get compromised (or their holders collude to steal funds): The Owner multisig can cancel payments and extend the time delay to longer than 48 hours. In this scenario though they probably wouldn't have to because the bridge funds can be escaped to the funding multisig. This is the only scenario that could be a serious risk to the funds in the bridge vault. This could be averted within 48 hours of the event starting because of the default delay and that funds can be escaped during that period.
Finally, what if the Event Listener falls off-line just previous to any of the aforementioned attacks that trigger alarms on compromise? The Security Guard should see any suspicious transactions and be able to delay payments until they are dealt with.