├── .gitignore
├── LICENSE
├── README.md
├── challenge-response-protocol
├── Challenge-response-protocol.md
├── Makefile
├── battle-states-legend.dot
├── battle-states-legend.svg
├── battle-states.dot
├── battle-states.svg
├── superblock-claims.dot
└── superblock-claims.svg
├── design-eth2doge.png
├── design.png
├── superblocks
└── superblocks-white-paper.pdf
└── user-manual.md
/.gitignore:
--------------------------------------------------------------------------------
1 | challenge-response-protocol/*.png
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Coinfabrik & Oscar Guindzberg
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Dogecoin <-> Ethereum bridge docs
2 |
3 | The Dogecoin <-> Ethereum bridge is a system that allows Doges to be moved from the Dogecoin blockchain to the Ethereum blockchain and back.
4 | Read the [intro for non-technical users](https://rnicoll.name/posts/2018-08-07-doge-ethereum-bridge/) by [Ross Nicoll](https://github.com/rnicoll).
5 |
6 | ## Main subprojects
7 | * [Dogethereum contracts](https://github.com/dogethereum/dogethereum-contracts): Ethereum contracts.
8 | * [Dogethereum agents](https://github.com/dogethereum/dogethereum-agents): External agents.
9 | * [Dogethereum tools](https://github.com/dogethereum/dogethereum-tools): CLI tools for Users and operators.
10 | * [Scrypt hash verification](https://github.com/dogethereum/scrypt-interactive): Interactive (i.e. challenge/response) validation of Scrypt hashes.
11 |
12 | ## Doge to Eth
13 |
14 | 
15 |
16 | ## Superblocks
17 |
18 | The Doge -> Eth side uses a new concept we named Superblocks. Read the [white paper](superblocks/superblocks-white-paper.pdf).
19 |
20 |
21 | ## Eth to Doge
22 |
23 | 
24 |
25 | ## Collateralized bridge
26 |
27 | We implemented a "collateralized" solution for the Eth -> Doge side. Here are the core concepts:
28 |
29 | * When a user wants to get doge tokens, she has to send the doges to a "Bridge operator". A bridge operator receives doges from users and holds them while they are locked. The smart contract mints doge tokens for the user.
30 | * When a user burns her doge tokens, a "bridge operator" is requested to send the doges back to the user.
31 | * Anyone can be a bridge operator.
32 | * "Bridge operators" deposit ether (collateral) on a smart contract. If they do anything with the doges but what is expected, they lose their eth deposit.
33 | * Anyone can report to the smart contract a doge tx showing a "bridge operator" misbehaviour.
34 | * There is an oracle for eth/doge price.
35 |
36 |
37 | ## Actors
38 |
39 | This is the list of external actors to the system and what they can do.
40 |
41 | * User
42 | * Lock (Doge -> Eth).
43 | * Transfer doge tokens (Eth -> Eth).
44 | * Unlock (Eth -> Doge).
45 | * Operator
46 | * Register as operator.
47 | * Add/Remove Eth collateral deposit.
48 | * Store locked doges.
49 | * Create, sign & broadcast doge unlock tx.
50 | * Superblock Submitter
51 | * Propose superblocks.
52 | * Defend superblocks.
53 | * Superblock Challenger
54 | * Challenge superblocks.
55 | * Doge/Eth Price Oracle
56 | * Inform Doge/Eth price rate.
57 |
58 |
59 | ## Workflows
60 | * New Superblock
61 | * There is a new block on the doge blockchain, then another one, then another one...
62 | * Once per hour Superblock Submitters create a new Superblock containing the newly created blocks and send a Superblock summary to [SuperblockClaims contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/SuperblockClaims.sol)
63 | * Superblock Challengers will challenge the superblock if they find it invalid. They will request the list of block hashes, the block headers, etc. Superblock Submitters should send that information which is validated onchain by the contract.
64 | * A Superblock Challenger might challenge one of the block's scrypt hashes. In that case [SuperblockClaims contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/SuperblockClaims.sol) uses Truebit's [Scrypt hash verification](https://github.com/dogethereum/scrypt-interactive) to check its correctness.
65 | * If any information provided by the Superblock Submitter is proven wrong or if it fails to answer, the Superblock is discarded.
66 | * If no challenge to the Superblock was done after a contest period (or if the challenges failed) the superblock is considered to be "approved". [SuperblockClaims contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/SuperblockClaims.sol) contract notifies [DogeSuperblocks contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/DogeSuperblocks.sol) which adds the Superblock to its Superblock chain.
67 | * Note: [DogeSuperblocks contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/DogeSuperblocks.sol) uses a checkpoint instead of starting from dogecoin blockchain genesis.
68 |
69 |
70 | * Sending dogecoins to ethereum
71 | * User selects an operator (any operator who has the desired amount of eth collateral).
72 | * User sends a lock doge tx of N doges to the doge network using [Dogethereum tools](https://github.com/dogethereum/dogethereum-tools) `lock` tool.
73 | * The doge tx is included in a doge block and several doge blocks are mined on top of it.
74 | * Once the doge block is included in an approved superblock, the lock tx is ready to be relayed to the eth network.
75 | * A [doge altruistic doge lock tx submitter](https://github.com/dogethereum/dogethereum-agents) finds the doge lock tx (In the future there will be a tool for users to relay their own txs).
76 | * The [doge altruistic doge lock tx submitter](https://github.com/dogethereum/dogethereum-agents) sends an eth tx to [DogeSuperblocks contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/DogeSuperblocks.sol) containing: the doge lock tx, a partial merkle tree proving the doge lock tx was included in a doge block, the doge block header that contains the doge lock tx, another partial merkle tree proving the block was included in a superblock and the superblock id that contains the block.
77 | * [DogeSuperblocks contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/DogeSuperblocks.sol) checks the consistency of the supplied information and relays the doge lock tx to [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol).
78 | * [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol) checks the doge lock tx actually sends funds to the doge address of a registered operator.
79 | * [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol) mints N tokens and assigns them to the User. Dogecoin lock txs don't specify a destination eth address. Dogetokens will be assigned to the eth address controlled by the private key that signed the dogecoin lock tx.
80 |
81 |
82 | * Sending doge tokens back to dogecoin
83 | * User selects an operator (any operator who has the desired amount of locked doges).
84 | * User sends an eth tx to the [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol) invoking the `doUnlock` function. Destination doge address, amount and operator id are supplied as parameters.
85 | * [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol) selects the UTXOs to spend, defines the doge tx fee, change and operator fee.
86 | * The [operator agent](https://github.com/dogethereum/dogethereum-agents) notices the unlock request. It creates, signs & broadcasts a doge unlock tx.
87 | * The user receives the unlocked doges.
88 | * The operator waits the doge tx to be confirmed and included in a superblock and then relays the doge unlock tx to the eth network, so change can be used by [DogeToken contract](https://github.com/dogethereum/dogethereum-contracts/blob/master/contracts/token/DogeToken.sol) for future unlocks.
89 |
90 | ## Incentives
91 |
92 | Some operations require gas to be spent or eth deposit to be frozen. Here are the incentives for doing that.
93 |
94 | * Submitting a Superblock: Superblock submitters will get a fee when the superblock they sent is used to relay a tx.
95 | * Being an operator: Each time a lock/unlock tx is made, operator gets a fee.
96 | * Sending dogecoin txs to DogeToken: Each user will send their own dogecoin lock tx to get doge tokens.
97 | * Superblock challenge: Challengers who find invalid superblocks will get some eth after the challenge/response game finishes.
98 |
99 |
100 | ## Assumptions
101 | * Incentives will guarantee that there is always at least one honest Superblock Submitter and one honest Superblock Challenger online.
102 | * There are no huge reorgs (i.e. 100+ block) in Doge nor in Eth blockchains
103 |
104 | ## Team
105 |
106 | * [Ismael Bejarano](https://github.com/ismaelbej)
107 | * [Catalina Juarros](https://github.com/cat-j)
108 | * [Pablo Yabo](https://github.com/pipaman)
109 | * [Oscar Guindzberg](https://github.com/oscarguindzberg)
110 | * [Sebastian Nale](https://github.com/scnale)
111 |
112 | ## License
113 |
114 | MIT License
115 | Copyright (c) 2021 Coinfabrik & Oscar Guindzberg
116 | [License](LICENSE)
117 |
118 | ## Donations
119 |
120 | BTC: 37gWZJPmEjM8RdgjauLsDUgbkYPe5bRFtt
121 | ETH: 0xFc7E364035f52ecA68D71dcfb63D1E3769413d69
122 | DOGE: D5q6QoN51z1daFpkreNqpbVq6i6oP6S35m
--------------------------------------------------------------------------------
/challenge-response-protocol/Challenge-response-protocol.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | This is a short overview of the challenge-response protocol used to invalidate superblockchain claims.
4 |
5 | ### Notation
6 |
7 | In some diagrams here we use the following notation:
8 | We note `S: proposeSuperblock` as "the superblock submitter sends a transaction calling the `proposeSuperblock` function".
9 |
10 | # Superblock claims
11 |
12 | To propose a superblock, a submitter creates a claim about it. To do so, the submitter needs to make an ether deposit in the `SuperblockClaims` contract. Whenever this submitter proposes a superblock, part of his deposit is staked into the corresponding claim.
13 |
14 | The claim can be challenged by anyone, provided they deposited enough ether into the contract.
15 |
16 | The lifecycle of a claim can be visualized in the following diagram:
17 |
18 | 
19 |
20 | Actors:
21 | - `S`: superblock submitter.
22 | - `C`: claim challenger.
23 | - `B`: `BattleManager` contract.
24 | - `*`: anyone can send this transaction.
25 |
26 | Here we consider `B` as an actor even though it is actually a contract. Normally, `B` is invoked by one of `S` or `C` but we don't distinguish them here.
27 |
28 | A claim can be challenged any number of times but only one battle can occur at a time. See the [battle protocol](#battle-protocol) section to learn more about how challenges resolve.
29 |
30 | Once a claim has matured, i.e. enough time has passed since it was submitted, it can be checked to decide whether to confirm it as part of the canonical superblockchain or to give it a partial approval if it is part of a contested superblockchain.
31 |
32 | Funds staked in a claim are awarded to the submitter if the superblock is added to the canonical superblockchain. If the superblock is invalidated instead, the funds go to the challengers of the superblock.
33 |
34 | # Battle protocol
35 |
36 | In a battle there are only two participants: the superblock submitter and the challenger.
37 |
38 | The protocol for a battle can be visualized in the following diagram:
39 |
40 | 
41 |
42 | Legend:
43 | 
44 |
45 | Actors:
46 | - `S`: superblock submitter.
47 | - `C`: claim challenger.
48 | - `H`: `ScryptClaims` contract.
49 | - `*`: anyone can send this transaction.
50 |
51 | Once again, we consider `H` as an actor even though it is actually a contract. Normally, `H` is invoked by one of `S` or `C` but we don't distinguish them here.
52 |
53 | Every transition here corresponds to a transaction sent successfully by either the submitter, the challenger, or, in some rare cases, anyone.
54 |
55 | Whenever one party advances the battle, it stakes an additional amount of ether from their deposit. This amount is meant to eventually pay for the gas cost of the transaction sent in response by the opponent. If the deposit were to lack sufficient funds, the transaction is reverted and the battle is left unmodified.
56 |
57 | Some nodes describe states where one of the parties can be timed out if they take too long to respond. In such cases, the opponent party wins by default. Anyone can call the timeout function for a battle.
58 |
59 |
60 | # Scrypt claims
61 |
62 | Scrypt hashes are verified through a claim system similar to the one used in superblocks.
63 |
64 | Whenever a scrypt hash verification is necessary, the claim is submitted to a contract and any number of challengers may declare that they doubt the hash. What follows is a series of battles where the submitter and the challengers try to prove each other wrong. There are two possible outcomes:
65 | - All challengers battle the submitter and fail to prove that the hash is invalid.
66 | - One of the challengers proves that the hash is invalid.
67 |
68 | ## Scrypt hash battles
69 |
70 | A scrypt hash battle is rather simple. The challenger must narrow incrementally the interval of steps of the hashing algorithm that contains an error. To do so, they ask for an intermediate state hash and based on the response of the submitter, they decide to discard the upper part of the interval or the lower part; akin to a binary search.
71 |
72 | Eventually, the interval is narrowed down to one step. At this point, the submitter must submit the intermediate state and proof of the legitimacy of this state. These are checked by the contract and based on the results, either the submitter wins or the challenger wins.
73 |
74 | At any point during a battle, one party may issue a timeout and win by default if the other party takes too long to respond.
75 |
76 | ## Claim resolution
77 |
78 | When a claim has withstood against all challenges or failed to verify in a battle, the `DogeBattleManager` contract is notified.
79 |
80 |
81 |
--------------------------------------------------------------------------------
/challenge-response-protocol/Makefile:
--------------------------------------------------------------------------------
1 | all: battle-states.svg battle-states-legend.svg superblock-claims.svg battle-states.png battle-states-legend.png superblock-claims.png
2 |
3 | .PHONY: show-battle-states
4 |
5 | battle-states.png: battle-states.dot
6 | dot -Tpng $< -o $@
7 |
8 | battle-states.svg: battle-states.dot
9 | dot -Tsvg $< -o $@
10 |
11 | battle-states-legend.png: battle-states-legend.dot
12 | dot -Tpng $< -o $@
13 |
14 | battle-states-legend.svg: battle-states-legend.dot
15 | dot -Tsvg $< -o $@
16 |
17 | superblock-claims.png: superblock-claims.dot
18 | dot -Tpng $< -o $@
19 |
20 | superblock-claims.svg: superblock-claims.dot
21 | dot -Tsvg $< -o $@
22 |
23 |
24 | # These rules are shortcuts to rapidly visualize the graphs
25 | # It requires the image viewer sxiv
26 | show-battle-states: battle-states.png battle-states-legend.png
27 | sxiv $^ &
28 |
29 | show-superblock-claims: superblock-claims.png
30 | sxiv $^ &
31 |
--------------------------------------------------------------------------------
/challenge-response-protocol/battle-states-legend.dot:
--------------------------------------------------------------------------------
1 |
2 | digraph Legend {
3 | "Battle running. Timeout possible.";
4 | "Battle paused. No timeouts." [shape=rectangle];
5 | "Battle finished." [shape=doublecircle];
6 | }
--------------------------------------------------------------------------------
/challenge-response-protocol/battle-states-legend.svg:
--------------------------------------------------------------------------------
1 |
2 |
4 |
6 |
7 |
33 |
--------------------------------------------------------------------------------
/challenge-response-protocol/battle-states.dot:
--------------------------------------------------------------------------------
1 | digraph ChallengeStates {
2 |
3 | // All edge labels refer to DogeBattleManager functions
4 | // All node names refer to ChallengeState enum members
5 | // A legend is best provided as a separate file
6 |
7 | // The layout in Graphviz is sensitive to the order in which these nodes are defined.
8 | {
9 | node []
10 | Challenged [label="Battle for claim starts"]
11 | QueryMerkleRootHashes [label="The challenger asked for the block hashes\n in the superblock"]
12 | RespondMerkleRootHashes [label="The submitter responded the block hashes"]
13 | VerifyScryptHash [label="The submitter responded the block header"]
14 | PendingVerification [label="All block headers are valid\n Final superblock integrity verification pending"]
15 | QueryBlockHeader [label="The challenger asked for a particular block header"]
16 | RespondBlockHeader [label="The submitter and challenger\n fully verified the block header"]
17 | }
18 |
19 | {
20 | node [shape=rectangle]
21 | RequestScryptVerification [label="The challenger asked verification of\n the PoW scrypt hash of the header"]
22 | PendingScryptVerification [label="The scrypt hash verification\n occurs in another contract"]
23 | }
24 |
25 | {
26 | node []
27 | SuperblockFailed [label="The battle ends and\n the submitter loses"]
28 | Deleted [label="Result\n notification", shape=doublecircle]
29 | }
30 |
31 |
32 | Challenged -> QueryMerkleRootHashes [label="C: queryMerkleRootHashes"]
33 | QueryMerkleRootHashes -> RespondMerkleRootHashes [label="S: respondMerkleRootHashes"]
34 | VerifyScryptHash -> PendingVerification [label="C: queryBlockHeader\n Scrypt hash challenge is skipped\n No remaining block headers"]
35 | VerifyScryptHash -> QueryBlockHeader [label="C: queryBlockHeader\n Scrypt hash challenge is skipped\n Some block headers remain"]
36 | RespondMerkleRootHashes -> QueryBlockHeader [label="C: queryBlockHeader"]
37 | RespondBlockHeader -> QueryBlockHeader [label="C: queryBlockHeader\n "]
38 | QueryBlockHeader -> VerifyScryptHash [label="S: respondBlockHeader"]
39 | VerifyScryptHash -> RequestScryptVerification [label="C: requestScryptHashValidation"]
40 | RequestScryptVerification -> PendingScryptVerification [label="H: scryptSubmitted"]
41 | PendingScryptVerification -> PendingVerification [label="H: scryptVerified\n No remaining block headers"]
42 | PendingScryptVerification -> RespondBlockHeader [label="H: scryptVerified\n Some block headers remain"]
43 | PendingScryptVerification -> SuperblockFailed [label="H: scryptFailed"]
44 | SuperblockFailed -> Deleted [label="*: verifySuperblock\n The submitter is convicted"]
45 | PendingVerification -> Deleted [label="*: verifySuperblock\n The challenger or the submitter is convicted"]
46 | }
47 |
--------------------------------------------------------------------------------
/challenge-response-protocol/battle-states.svg:
--------------------------------------------------------------------------------
1 |
2 |
4 |
6 |
7 |
195 |
--------------------------------------------------------------------------------
/challenge-response-protocol/superblock-claims.dot:
--------------------------------------------------------------------------------
1 | digraph SuperblockClaims {
2 |
3 | // All edge labels refer to SuperblockClaims functions
4 | // All nodes map loosely to superblock status enum members found in DogeSuperblocks
5 |
6 | {
7 | node []
8 | NewSuperblock [label="New superblock"]
9 | ClaimSubmitted [label="New claim\n Superblock claim in good standing but not approved"]
10 | BattleOverClaim [label="Claim is being challenged"]
11 | GoodSuperblock [label="Claim is in good standing"]
12 | SemiApprovedClaim [label="Claim is part of a superblockchain\n that was challenged at least once\n but remains in good standing"]
13 | ApprovedClaim [label="Claim is approved and the superblock\n is considered part of the canonical superblockchain"]
14 | InvalidatedSuperblock [label="Superblock is invalid"]
15 | }
16 |
17 |
18 |
19 | NewSuperblock -> ClaimSubmitted [label="S: proposeSuperblock"]
20 | ClaimSubmitted -> BattleOverClaim [label="C: challengeSuperblock"]
21 | BattleOverClaim -> InvalidatedSuperblock [label="B: sessionDecided\n The submitter lost the battle"]
22 | BattleOverClaim -> GoodSuperblock [label="B: sessionDecided\n The submitter won the battle\n No pending battles"]
23 | GoodSuperblock -> SemiApprovedClaim [label="*: checkClaimFinished\n The claim is mature"]
24 | GoodSuperblock -> BattleOverClaim [label="C: challengeSuperblock"]
25 | ClaimSubmitted -> ApprovedClaim [label="*: checkClaimFinished\n The claim is mature\n The parent superblock is canonical"]
26 | ClaimSubmitted -> SemiApprovedClaim [label="*: checkClaimFinished\n The claim is mature\n The parent superblock is not approved yet"]
27 | SemiApprovedClaim -> ApprovedClaim [label="*: confirmClaim\n The parent superblock is canonical"]
28 | SemiApprovedClaim -> InvalidatedSuperblock [label="*: rejectClaim\n The superblock is not part of the canonical superblockchain"]
29 | }
30 |
--------------------------------------------------------------------------------
/challenge-response-protocol/superblock-claims.svg:
--------------------------------------------------------------------------------
1 |
2 |
4 |
6 |
7 |
140 |
--------------------------------------------------------------------------------
/design-eth2doge.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/dogethereum/docs/23515f7bc5932cf71a47cc69353667e4570db39b/design-eth2doge.png
--------------------------------------------------------------------------------
/design.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/dogethereum/docs/23515f7bc5932cf71a47cc69353667e4570db39b/design.png
--------------------------------------------------------------------------------
/superblocks/superblocks-white-paper.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/dogethereum/docs/23515f7bc5932cf71a47cc69353667e4570db39b/superblocks/superblocks-white-paper.pdf
--------------------------------------------------------------------------------
/user-manual.md:
--------------------------------------------------------------------------------
1 | # Dogecoin <-> Ethereum bridge - User guide
2 |
3 | **WARNING: THIS IS AN ALPHA RELEASE. SOME FEATURES STILL HAVE TO BE IMPLEMENTED AND THERE MIGHT BE BUGS. JUST USE IT WITH COINS YOU ARE OPEN TO LOSE.**
4 |
5 | To get a general overview of the system, go to: https://github.com/dogethereum/docs
6 |
7 | A "user" of the bridge can do the following operations:
8 | * Lock (Doge -> Eth).
9 | * Transfer doge tokens (Eth -> Eth).
10 | * Unlock (Eth -> Doge).
11 |
12 | The "alpha" bridge uses Dogecoin mainnet and Ethereum Rinkeby testnet.
13 |
14 | The doge token is deployed at address [0xd41d4b54013a622eaec3d6f35072b6a5e827c0ef](https://rinkeby.etherscan.io/token/0xd41d4b54013a622eaec3d6f35072b6a5e827c0ef)
15 |
16 | ## Prerequisites
17 |
18 | In order to use the bridge you will need:
19 |
20 | * An Ethereum node running on rinkeby testnet with its blockchain up to date and rpc interface enabled.
21 |
24 | * Some Rinkeby Eth to pay the network transaction fees. You can get some on the [faucet](https://faucet.rinkeby.io).
25 | * A Dogecoin core node running on mainnet with its blockchain up to date and rpc interface enabled (Other doge wallets won't work).
26 |
29 | * Some mainnet Doges on your Dogecoin-Qt wallet. You can get some on [this faucet](https://freedoge.co.in) or [this other faucet](https://coinpot.co).
30 | * Install [Dogethereum tools](https://github.com/dogethereum/dogethereum-tools) : See [prerequisites](https://github.com/dogethereum/dogethereum-tools#requirements) and [installation instructions](https://github.com/dogethereum/dogethereum-tools#installation).
31 |
32 | ## Converting Dogecoin doges to Ethereum doge tokens.
33 |
34 | Before you start go to the dogethereum tools directory:
35 | ```
36 | cd dogethereum-tools
37 | ```
38 |
39 | **Send 8 doges to ethereum**
40 |
41 |
44 |
45 | The minumum value to lock is 3 doges.
46 |
47 | This will:
48 | * Select an operator that is available to receive 8 doges.
49 | * Create, sign and broadcast a doge tx sending 8 doges to the operator.
50 | * Print your private key. You need to use it later on to get the doge tokens.
51 |
52 | Expected output:
53 |
54 | Lock 8 doges.
55 | Connected to dogecoin node!
56 | Initiating lock...
57 | Locking 8 doges to address OperatorDogeAddress using operator 0xoperatorPublicKeyHash
58 | Sent doge tx ...
59 | User private key : 0xYourPrivateKey
60 | User eth address : 0xYourEthAddress
61 | Total locked 8 doges.
62 | Lock Done.
63 |
64 |
65 | **Import your private key**
66 |
67 | The doge tokens will be assigned to the ethereum address controlled by the private key that signed the 1st input of the dogecoin transaction.
68 | That is the private key that you obtained on the previous step.
69 | In order to use your doge tokens, you need import your private key to ethereum:
70 |
80 |
81 | There are fees you have to pay for doing a lock.
82 | If you sent 8 doges, you will receive 6 doge tokens because the bridge fee is 2% of the locked amount, minimum 2 doges.
83 | On top of that, you will be charged ~1 doge to pay the doge tx fee.
84 |
85 | Congratulations! You converted doges to doge tokens!
86 |
87 |
88 | ## Using the doge tokens
89 |
90 | If you received tokens by locking doges, you may want to use them.
91 | The first thing is to make sure you have some eth balance on the address where you have the doge tokens (you probably don't) to pay eth tx fees.
92 | You can send some eth to that address using your preferred ethereum rinkeby wallet.
93 | In case you don't have one, you can use this command (the sender address should have some rinkeby eth) :
94 |
102 |
103 | If you received tokens from another user:
104 | You can use them in your preferred rinkeby wallet as any other ERC-20 token
105 |
106 |
107 | ## Converting Ethereum doge tokens back to Dogecoin doges.
108 |
109 | To send 5 doge tokens back to doge:
110 |
113 |
114 | The minumum value to unlock is 3 doge tokens.
115 | There are fees you have to pay for doing an unlock.
116 | The bridge fee is 1% of the unlocked amount, minimum 1 doge.
117 | On top of that ~1.5 doge will be deducted to pay the doge tx fee.
118 | If you sent 5 doge tokens you will receive ~2.5 doges.
119 |
120 | After ~2 minutes you will receive a doge tx to yourDogeAddress.
121 |
122 | You can check you received the doges using your Dogecoin wallet or https://dogechain.info
123 |
124 | Congratulations! You converted doge tokens to doges!
125 |
126 | ## Dogethereum tools reference documentation
127 | For a full command reference:
128 | * See [User tools reference](https://github.com/dogethereum/dogethereum-tools#user-tools).
129 | * On the command line: