Skip to content

Commit cad1b53

Browse files
author
Chris Hatch
committed
update protocol docs:
- fix timelocks - preimage revealer locktime should be longer then the other party (so have time to claim) - change tx spec's to use parseable format (yaml) - expand the overviews at the top - various fixes and changes
1 parent bc8ebca commit cad1b53

File tree

2 files changed

+292
-168
lines changed

2 files changed

+292
-168
lines changed

Diff for: ‎docs/protocol_stellar_asset_to_ethereum_erc20.md

+128-77
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,152 @@
1-
# Stellar Assets to Ethereum ERC20 Token Swaps
1+
# Stellar Assets to Ethereum ERC20 Cross-chain Trades
22

3-
** DRAFT v0.0.2**
3+
Version: 0.1.3
44

5-
This protocol supports atomic trades/swaps between the tokens on the Stellar and Ethereum networks.
5+
This protocol supports atomic cross-chain trades between any
6+
[Stellar Asset](https://www.stellar.org/developers/guides/concepts/assets.html)
7+
and any
8+
[Ethereum ERC20 token](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20-token-standard.md).
9+
It is a variation of the
10+
[Stellar XLM to Ethereum ETH Cross-chain Trades protocol](./protocol_stellar_xlm_to_ethereum_eth.md).
611

7-
Two scenarios are described below. Scenario 1 is initiated from Stellar and Scenario 2 is initiated from Ethereum.
812

9-
NOTE:
10-
* examples trade between a Stellar CNY Asset and an Ethereum OMG token but the goal is to support any combination
11-
* uses the [HashedTimelockERC20](https://github.com/chatch/hashed-timelock-contract-ethereum/blob/ERC20_HTLC/contracts/HashedTimelockERC20.sol) smart contract to lock up tokens on Ethereum
12-
* no consideration given to authorized flag assets yet. the holding account would need auth before continuing the trade OR some other mechanism would be required handle these.
13-
* support for tokens that implement ERC223 could be added later (advantage being no approve step required - tokens sent in the same transaction as the newContract call transaction)
13+
A list of Stellar Assets can be found [here](https://stellar.expert/explorer/asset)
14+
and a list of Ethereum tokens [here](https://etherscan.io/tokens).
15+
Trades between any pair should be possible with this protocol.
1416

15-
## Scenario 1 (S1): Swap initiated by Stellar Asset holder
17+
18+
Two scenarios are described below:
19+
* Scenario 1 is initiated from Stellar.
20+
* Scenario 2 is initiated from Ethereum.
21+
22+
### Note
23+
24+
* all hashes are SHA-2 SHA-256 hashes
25+
* HashedTimelockERC20 refers to [this Ethereum smart contract](https://github.com/chatch/hashed-timelock-contract-ethereum/blob/master/contracts/HashedTimelockERC20.sol)
26+
* 'Preimage' and 'x' are used interchangeably to refer to the generated secret preimage, the hash of which is used as the hashlock
27+
* 'HTLC' refers to Hashed Timelock Contracts
28+
* no consideration yet given to Stellar assets with the authorized flag set to true.
29+
the holding account would need auth before continuing the trade so that would
30+
need to be established at the beginning.
31+
* ERC223 token support could be added (the advantage being no approve()
32+
step would be required)
33+
34+
## Scenario 1 (S1): Trade initiated by Stellar CNY Asset holder
1635

1736
### Summary
18-
* Alice initiates the setup process on Stellar side
19-
* Alice sells CNY to Bob
20-
* Bob sells OMG to Alice
37+
38+
* Alice is selling CNY to Bob (CNY is a Chinese Renminbi Asset on Stellar)
39+
* Bob is selling OMG to Alice (OMG is the OmiseGo ERC20 token)
40+
* Alice initiates the setup process creating the secret preimage x
41+
* Alice creates a holding account on Stellar to hold the CNY Asset
42+
* Bob creates a new HTLC on the Ethereum HashedTimelockERC20 contract to hold the ETH
43+
* Alice claims OMG revealing x to the HTLC contract on Ethereum
44+
* Bob takes the revealed x and claims CNY from the Stellar holding account
2145

2246
### Sequence Diagram
47+
2348
![sequence Diagram - TODO](uml/protocol-tokens-scenario1.png)
2449

2550
### Protocol
2651

2752
1. Agreement
28-
1. Agree to asset types and amounts over some channel (telegram, phone call, whatever ..)
29-
2. Exchange Stellar and Ethereum public addresses. Each user must have 1 account on each network
30-
3. Define this in a trade.json file [JSON schema](https://github.com/chatch/xcat/blob/master/src/schema/trade.json)
31-
4. Ensure Bob already has a trustline to the Stellar Asset before proceeding.
53+
1. Agree to asset types and amounts over some channel (telegram, phone call, whatever ..).
54+
2. Exchange Stellar and Ethereum public addresses. Each user must have 1 account on each network.
55+
3. Define trade details in a trade.json file that conforms to the [JSON schema](https://github.com/chatch/xcat/blob/master/src/schema/trade.json)
3256
2. Setup
33-
1. Alice generates secret x
34-
2. [Stellar] Alice submits Tx:
35-
```
36-
Operation: Create Account
37-
Destination: hold acc
38-
Balance: 50 (includes +10 for hash(x) signer, +10 for Bob signer, +10 for CNY trustline)
39-
Operation: Change Trust:
40-
Source: hold acc
41-
Line: CNY / CNY Issuer
42-
Limit: agreed amount
43-
Operation: Set Options:
44-
Source: hold acc
45-
Signers: Bob w/ weight 1
46-
Operation: Set Options:
47-
Source: hold acc
48-
Master Weight: 0
49-
Threshold(ALL Levels): 2
50-
Signers: hash(x) w/ weight 1
51-
Signatures: Alice, hold account
52-
```
53-
54-
3. [Stellar] Bob creates and signs tx envelope for a refund tx for Alice and sends it to her:
55-
```
56-
Source: holding account
57-
Time bound: 6h from now
58-
Sequence: holding account current sequence
59-
Operation: Account Merge
60-
Destination: Alice
61-
Signatures: Bob
62-
```
63-
64-
4. [Stellar] Alice submits TX moving agreed CNY amount into the holding account:
65-
```
66-
Source: Alice
67-
Operation: Payment to Holding Account
68-
Amount: agreed amount of CNY
69-
```
70-
71-
5. [Ethereum] Bob calls newContract() on HashedTimelockERC20 Ethereum contract:
72-
```
73-
receiver = Alices Ethereum address
74-
hashLock = hash(x)
75-
timelock = 6h from now
76-
token = OMG token contract address
77-
amount = agreed OMG amount
78-
```
79-
3. Exchange
80-
1. [Ethereum] Alice calls withdraw() on the contract revealing x
81-
calls transfer on the OMG token contract transfering change ownership for 'amount' tokens to Alice
82-
83-
2. [Stellar] Bob now knows x and submits a TX to Stellar to get funds:
84-
```
85-
Source: Holding Account
86-
Operation: Account Merge
87-
Destination: Bob
88-
Signatures: bob, x
89-
```
57+
1. Alice generates secret x
58+
2. [Stellar] Alice generates a new address for the holding account
59+
3. [Stellar] Alice creates the holding account submitting this transaction:
60+
```yaml
61+
source: Alice
62+
sequence: Alice account sequence
63+
operations:
64+
- type: createAccount
65+
destination: holdingAccount
66+
balance: 5 * base_reserve # 5 = 2 + signer hashx + signer bob + asset trustline
67+
- type: changeTrust
68+
source: holdingAccount
69+
asset: CNY Asset
70+
limit: agreed amount
71+
- type: setOptions
72+
source: holdingAccount
73+
signer:
74+
- ed25519PublicKey: Bob
75+
- weight: 1
76+
- type: setOptions
77+
source: holdingAccount
78+
masterWeight: 0
79+
lowThreshold: 2
80+
medThreshold: 2
81+
highThreshold: 2
82+
signer:
83+
- sha256Hash: hash(x)
84+
- weight: 1
85+
sign: Alice
86+
sign: holdingAccount
87+
```
88+
89+
4. [Stellar] Bob creates a refund transaction, signs the envelope and sends it to Alice:
90+
```yaml
91+
source: holdingAccount
92+
sequence: holdingAccount sequence
93+
timebounds:
94+
- minTime: N minutes
95+
- maxTime: 0
96+
operations:
97+
- type: accountMerge
98+
destination: Alice
99+
sign: Bob
100+
```
101+
102+
5. [Stellar] Alice submits TX moving agreed CNY amount into the holding account:
103+
```yaml
104+
source: Alice
105+
sequence: Alice's sequence
106+
operations:
107+
- type: payment
108+
destination: holdingAccount
109+
asset: CNY Asset
110+
amount: agreed amount
111+
sign: Alice
112+
```
113+
114+
6. [Ethereum] Bob calls newContract() on HashedTimelockERC20 Ethereum contract:
115+
```yaml
116+
newContract:
117+
- _receiver: Alice's address (Ethereum)
118+
_hashlock: hash(x)
119+
_timelock: N / 2 minutes # N from 4. above
120+
_token: OMGTokenContractAddress
121+
_amount: agreed amount
122+
```
123+
124+
3. Trade
125+
1. [Ethereum] Alice calls withdraw() on the HTLC revealing x
126+
The HTLC then calls transfer() on the OMG token contract transferring
127+
ownership of the tokens to Alice.
128+
2. [Stellar] Bob now knows x and submits a TX to Stellar to get funds:
129+
```yaml
130+
source: holdingAccount
131+
sequence: holdingAccount sequence
132+
operations:
133+
- type: accountMerge
134+
destination: Bob
135+
sign: Bob
136+
signHashX: x
137+
```
90138
91139
NOTES:
92-
1. If nothing happens after 2.4 Alice can get a refund after 'Time Bound' time has passed by adding a signature x to the transaction Bob gave here in 2.3
93-
2. If nothing happens after 2.5 Bob can get a refund after timelock time has passed by calling refund() on the Ethereum smart contract
94140
141+
1. If nothing happens after 2.4 Alice can get a refund after 'Time Bound' time
142+
has passed by adding a signature x to the transaction Bob gave here in 2.3.
143+
2. If nothing happens after 2.5 Bob can get a refund after timelock time has
144+
passed by calling refund() on the Ethereum smart contract.
95145
96-
## Scenario 2 (S2): Swap initiated by OMG holder on Ethereum
146+
## Scenario 2 (S2): Trade initiated by OMG holder on Ethereum
97147
98148
### Summary
149+
99150
* Bob initiates the setup process on Ethereum side
100151
* Alice sells CNY to Bob
101152
* Bob sells OMG to Alice

0 commit comments

Comments
 (0)