Skip to content

Commit 9d8f80f

Browse files
anyxemanyxem
committed
feat: add docs for bridge endpoints
1 parent 8ce0e24 commit 9d8f80f

2 files changed

Lines changed: 289 additions & 0 deletions

File tree

‎docs/bridge/_category_.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Bridge",
3+
"position": 40,
4+
"link": {
5+
"type": "generated-index"
6+
}
7+
}

‎docs/bridge/index.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
---
2+
title: Bridge API
3+
sidebar_label: Bridge API
4+
---
5+
6+
# Mintlayer-ERC20 bridge
7+
8+
The purpose of the bridge is to transfer fungible tokens between Mintlayer and Ethereum chains.
9+
10+
# API server endpoints
11+
12+
* `api/v1/bridge-request` - submit a bridge request.
13+
14+
E.g. (e2m):
15+
```
16+
curl -H 'Content-type: application/json' \
17+
--data '{
18+
"source_chain":"Ethereum-XYZ",
19+
"destination_chain":"Mintlayer",
20+
"asset":"FOO",
21+
"amount":"100.00",
22+
"receiver_address":"tmt1q94w2g3vwvw74swj3gx4kaf5qelapmdhyyyxe3ef",
23+
"deposit_transactions":[{
24+
"raw_transaction":"02f9...bd03"
25+
}]
26+
}' \
27+
-X POST https://SERVER_URL/api/v1/bridge-request
28+
```
29+
Or (m2e):
30+
```
31+
curl -H 'Content-type: application/json' \
32+
--data '{
33+
"source_chain":"Mintlayer",
34+
"destination_chain":"Ethereum-XYZ",
35+
"asset":"FOO",
36+
"amount":"100.00",
37+
"receiver_address":"0x6CFF507AeA2FE77a508E13DD4C2dF495780871D5",
38+
"deposit_transactions":[{
39+
"intent":"e901...a9be",
40+
"raw_transaction":"0100...5250"
41+
}]
42+
}' \
43+
-X POST https://SERVER_URL/api/v1/bridge-request
44+
```
45+
46+
Alternatively, instead of passing the complete deposit transaction you can specify its hash.
47+
48+
E.g. (e2m):
49+
```
50+
curl -H 'Content-type: application/json' \
51+
--data '{
52+
"source_chain":"Ethereum-XYZ",
53+
"destination_chain":"Mintlayer",
54+
"asset":"FOO",
55+
"amount":"100.00",
56+
"receiver_address":"tmt1q94w2g3vwvw74swj3gx4kaf5qelapmdhyyyxe3ef",
57+
"deposit_transactions":[{
58+
"transaction_hash":"a76b...cb84"
59+
}]
60+
}' \
61+
-X POST https://SERVER_URL/api/v1/bridge-request
62+
```
63+
Same for m2e.
64+
65+
Example response:
66+
```
67+
{
68+
"bridge_request_uuid": "aac4d30d-91c7-4e2e-94d9-00bb3709771e",
69+
"deposit_transaction_uuids": ["25c43ed1-d2eb-4a1a-b546-16c67d6303af"]
70+
}
71+
```
72+
73+
Note: `deposit_transaction_uuids` will have the same order as `deposit_transactions` in the request.
74+
75+
* `api/v1/fees` - return the contents of the `fees` table.
76+
77+
E.g.:
78+
```
79+
curl -X GET https://SERVER_URL/api/v1/fees
80+
```
81+
82+
Example response: `{"bar":{"fixed_fee":"5","percentage_fee":"0.1%"},"foo":{"fixed_fee":"10","percentage_fee":"1%"}}`.
83+
84+
* `api/v1/subscribe` - open a websocket to receive notifications about status changes of bridge requests as well as deposit and withdrawal transactions.
85+
86+
Example messages for a successful bridge request:
87+
```
88+
{"event_name":"bridge_request_status_updated","uuid":"93bc6941-ebc5-4eae-8226-de7a606defcf","status":"pending"}
89+
{"event_name":"deposit_transaction_status_updated","uuid":"8d6f7745-6133-4bc6-a230-dc577d1ab626","status":"not_yet_submitted"}
90+
{"event_name":"deposit_transaction_status_updated","uuid":"8d6f7745-6133-4bc6-a230-dc577d1ab626","status":"submitted"}
91+
{"event_name":"deposit_transaction_status_updated","uuid":"8d6f7745-6133-4bc6-a230-dc577d1ab626","status":"confirmed_by_network"}
92+
{"event_name":"withdrawal_transaction_status_updated","uuid":"a78113ac-5984-47fb-9405-785dc38e6aae","status":"master_signed"}
93+
{"event_name":"bridge_request_status_updated","uuid":"93bc6941-ebc5-4eae-8226-de7a606defcf","status":"processed_by_master"}
94+
{"event_name":"withdrawal_transaction_status_updated","uuid":"a78113ac-5984-47fb-9405-785dc38e6aae","status":"submitted_to_network"}
95+
{"event_name":"withdrawal_transaction_status_updated","uuid":"a78113ac-5984-47fb-9405-785dc38e6aae","status":"confirmed_by_network"}
96+
{"event_name":"bridge_request_status_updated","uuid":"93bc6941-ebc5-4eae-8226-de7a606defcf","status":"completed"}
97+
```
98+
Note: deposit transaction status change to "submitted" won't happen if the transaction has been submitted to the network by other means
99+
(i.e. outside the bridge); in this case the status will go from "not_yet_submitted" directly to "confirmed_by_network".
100+
101+
Other possible statuses are:
102+
- for bridge requests: "failed" - the request has failed, "manual" - the request requires manual handling;
103+
- for deposit transactions: "confirmation_failed" - the transaction could not be confirmed, "invalid" - the transaction is invalid;
104+
- for withdrawal transactions: "failed_revalidation" - the cosigner determined that the withdrawal transaction is invalid
105+
(note that this is not a normal situation), "failed_submission" - the cosigner failed to submit the withdrawal transaction
106+
to the network.
107+
108+
* `api/v1/bridge-request/{uuid}` - obtain some information about a bridge request given its uuid.
109+
110+
E.g.:
111+
```
112+
curl https://SERVER_URL/api/v1/bridge-request/034d5ce2-70f4-4089-a330-97d8d8f23775
113+
```
114+
115+
Example response:
116+
```
117+
{
118+
"uuid":"034d5ce2-70f4-4089-a330-97d8d8f23775",
119+
"source_chain":"mintlayer",
120+
"destination_chain":"ethereum-xyz",
121+
"asset":"foo",
122+
"amount":"100",
123+
"amount_after_fees":"89.1",
124+
"sender_addresses":[
125+
"tmt1q94w2g3vwvw74swj3gx4kaf5qelapmdhyyyxe3ef"
126+
],
127+
"receiver_address":"0x6CFF507AeA2FE77a508E13DD4C2dF495780871D5",
128+
"status":"completed",
129+
"created_at":"2025-03-10 16:28:58.753664 +00:00:00",
130+
"updated_at":"2025-03-10 16:33:43.879247 +00:00:00",
131+
"deposit_transactions":[
132+
{
133+
"uuid":"1bcea941-2761-4655-a875-fe01c00120c6",
134+
"transaction_hash":"ef366c9129f6d36b7b8a7adde13a061351ea20d16b857bacab28a0ed6f8ead2d",
135+
"status":"confirmed_by_network",
136+
"created_at":"2025-03-10 16:28:58.753664 +00:00:00",
137+
"updated_at":"2025-03-10 16:29:10.875763 +00:00:00"
138+
}
139+
],
140+
"withdrawal_transaction":{
141+
"uuid":"52d4bfdf-8a7c-4ea2-af54-5f287f747ffc",
142+
"destination_chain":"ethereum-xyz",
143+
"transaction_hash":"98267a71c2f40911da3aa71ee9beb7764729159d1c70510c42fa604c05dc2894",
144+
"status":"confirmed_by_network",
145+
"created_at":"2025-03-10 16:29:11.023903 +00:00:00",
146+
"updated_at":"2025-03-10 16:33:43.879247 +00:00:00",
147+
"bridge_request_uuids":[
148+
"034d5ce2-70f4-4089-a330-97d8d8f23775"
149+
]
150+
}
151+
}
152+
```
153+
154+
Note:
155+
- The order of deposit transactions is unspecified in this case.
156+
- `amount_after_fees` and `withdrawal_transaction` will be `null` and `sender_addresses`
157+
will be empty if the request has not been handled by the master yet.
158+
- The returned data contains the full info about the withdrawal transaction that handles the
159+
bridge request (if any) instead of just a uuid. Though this is somewhat redundant (e.g. the uuid
160+
of the bridge request is also present in the `bridge_request_uuids` field of `withdrawal_transaction`),
161+
it's supposed to help reduce the number of requests that the UI has to make.
162+
163+
* `api/v1/deposit-transaction/{uuid}` - obtain some information about a deposit transaction given its uuid.
164+
165+
E.g.:
166+
```
167+
curl https://SERVER_URL/api/v1/deposit-transaction/1bcea941-2761-4655-a875-fe01c00120c6
168+
```
169+
170+
Example response:
171+
```
172+
{
173+
"uuid":"1bcea941-2761-4655-a875-fe01c00120c6",
174+
"transaction_hash":"ef366c9129f6d36b7b8a7adde13a061351ea20d16b857bacab28a0ed6f8ead2d",
175+
"status":"confirmed_by_network",
176+
"created_at":"2025-03-10 16:28:58.753664 +00:00:00",
177+
"updated_at":"2025-03-10 16:29:10.875763 +00:00:00"
178+
}
179+
```
180+
181+
* `api/v1/withdrawal-transaction/{uuid}` - obtain some information about a withdrawal transaction given its uuid.
182+
183+
E.g.:
184+
```
185+
curl https://SERVER_URL/api/v1/withdrawal-transaction/52d4bfdf-8a7c-4ea2-af54-5f287f747ffc
186+
```
187+
188+
Example response:
189+
```
190+
{
191+
"uuid":"52d4bfdf-8a7c-4ea2-af54-5f287f747ffc",
192+
"destination_chain":"ethereum-xyz",
193+
"transaction_hash":"98267a71c2f40911da3aa71ee9beb7764729159d1c70510c42fa604c05dc2894",
194+
"status":"confirmed_by_network",
195+
"created_at":"2025-03-10 16:29:11.023903 +00:00:00",
196+
"updated_at":"2025-03-10 16:33:43.879247 +00:00:00",
197+
"bridge_request_uuids":[
198+
"034d5ce2-70f4-4089-a330-97d8d8f23775"
199+
]
200+
}
201+
```
202+
203+
Note: in m2e the actual withdrawal transaction (i.e. the one that is sent to the network) is created by the cosigner.
204+
So, the returned `transaction_hash` will be null if the withdrawal transaction has not been handled by the cosigner yet.\
205+
In e2m, on the other hand, the actual transaction is created by the master, so in this case `transaction_hash` will be
206+
known right away.
207+
208+
* `api/v1/agents-config` - obtain agents' configuration values.
209+
210+
E.g.:
211+
```
212+
curl https://SERVER_URL/api/v1/agents-config
213+
```
214+
215+
Example response:
216+
```
217+
{
218+
"network_type":"testnet",
219+
"ml_tokens":{
220+
"bar":"tmltk1lht3lwdzkdydwr7qk2j6zudqssh0lunfnhua7jrczdyjuk97edaswt2fpj",
221+
"foo":"tmltk1e7egscactagl7e3met67658hpl4vf9ux0ralaculjvnzhtc4qmsqv9y857"
222+
},
223+
"eth_flavor_specific_config":{
224+
"":{
225+
"token_config":{
226+
"bar":{
227+
"address":"0x7f6dae09b819f918314d86466a9af4564d3ed805",
228+
"max_amount_per_request":null
229+
},
230+
"foo":{
231+
"address":"0xb87a9b1cafb3b42ea7e2cb3a72b20c5695994a53",
232+
"max_amount_per_request":"1000.5"
233+
}
234+
},
235+
"infura_rpc_url":"https://sepolia.infura.io/v3/1c4fd1ef43ca40deb35e81bc47838b3f",
236+
"bridge_contract_address":"0x0b3c26e254ab5e8c9d84ccdcf1957bed0890322c",
237+
"e2m":null,
238+
"m2e":{
239+
"deposit_tx_required_confirmations":1,
240+
"deposit_tx_destination":"tmt1q94w2g3vwvw74swj3gx4kaf5qelapmdhyyyxe3ef",
241+
"deposit_tx_max_blocks_to_wait":10,
242+
"withdrawal_tx_required_confirmations":1,
243+
"resend_withdrawal_tx_after_block_count":2,
244+
"multisend_contract_address":"0x38869bf66a61cf6bdb996a6ae40d5853fd43b526",
245+
"gnosis_safe_address":"0xb0b61e0aaf88bc40065739112cd2347fcde3f906"
246+
}
247+
},
248+
"xyz":{
249+
"token_config":{
250+
"bar":{
251+
"address":"0xc00f017fbd014a4daa7898b20781508c388253a8",
252+
"max_amount_per_request":null
253+
},
254+
"foo":{
255+
"address":"0x4ef442684ef3d050c6bd54a25d4ea95d688a74e5",
256+
"max_amount_per_request":"1000.5"
257+
}
258+
},
259+
"infura_rpc_url":"https://something-else.infura.io/v3/1c4fd1ef43ca40deb35e81bc47838b3f",
260+
"bridge_contract_address":"0x80285cc9ccb49456709242c18f50e60195b371be",
261+
"e2m":{
262+
"deposit_tx_required_confirmations":1,
263+
"ml_token_owner_address":"tmtc1qnw7qgm87l0a0vhegyrw5szrgqlldkt8rczqzpc2",
264+
"tx_fee_change_address":"tmt1q9pfchtsepyy6n8hx3w74e7tm3pcv5y6ncjtjysg",
265+
"bridge_contract_deposit_log_record_topic":"0x2dc24880b34b2026fb1cd0231e65ef42ca1c78e4efdd9711b7629740206bfa46",
266+
"deposit_tx_max_blocks_to_wait":10,
267+
"withdrawal_tx_required_confirmations":1,
268+
"resend_withdrawal_tx_after_block_count":2
269+
},
270+
"m2e":{
271+
"deposit_tx_required_confirmations":1,
272+
"deposit_tx_destination":"tmt1qxm8pnvpu5886kun0vv9dqzp3nxvhawgqugprcv3",
273+
"deposit_tx_max_blocks_to_wait":10,
274+
"withdrawal_tx_required_confirmations":1,
275+
"resend_withdrawal_tx_after_block_count":2,
276+
"multisend_contract_address":"0x38869bf66a61cf6bdb996a6ae40d5853fd43b526",
277+
"gnosis_safe_address":"0x9f7ed25b653dfedf775b55077f0025722abd7c9f"
278+
}
279+
}
280+
}
281+
}
282+
```

0 commit comments

Comments
 (0)