Skip to content

Commit 0beb81d

Browse files
ezdacezdac
committed
docs: Update API inconsistencies
1 parent 2dc868e commit 0beb81d

File tree

3 files changed

+65
-18
lines changed

3 files changed

+65
-18
lines changed

‎docs/raiden-api-1/api-tutorial/2-open-a-channel.inc.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Find suitable partner nodes
1717
To make payments, you need to be connected to the target node either
1818
directly, or indirectly by having a channel with a well connected that
1919
mediates your payment to the target. If you already know to which node
20-
you want to connect, skip ahead to the `next section <Open a channel>`.
20+
you want to connect, skip ahead to the :ref:`next section <Open a channel>`.
2121

2222
The Path Finding Service (PFS) can suggest partners that are highly
2323
connected. These nodes will be able to mediate your payments to a large
@@ -88,6 +88,7 @@ the following response object:
8888
{
8989
"token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
9090
"channel_identifier": "99",
91+
"network_state": "unknown",
9192
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
9293
"token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
9394
"balance": "1337",
@@ -104,7 +105,7 @@ inside the token network.
104105

105106
You're now ready to start :ref:`making payments <api_tut_make_payment>`.
106107

107-
.. note:: Opening a channel with a partner node is not dependent on whether the partner node holds tokens or not. It will work either way.
108+
.. note:: Opening a channel with a partner node is not dependent on whether the partner node holds tokens or not. It will work either way.
108109

109110
.. _api_tut_channel_state:
110111

‎docs/raiden-api-1/api-tutorial/4-settle-payments-and-close-channels.inc.rst‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ set to ``"closed"``.
3636
{
3737
"token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
3838
"channel_identifier": "99",
39+
"network_state": "unknown",
3940
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
4041
"token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
4142
"balance": "350",
@@ -61,23 +62,31 @@ endpoint with the token address as a path parameter.
6162
http://localhost:5001/api/v1/connections/0x9aBa529db3FF2D8409A1da4C9eB148879b046700 \
6263
-H 'Content-Type: application/json'
6364
64-
Once done, the response will return a list containing the addresses of
65-
all closed channels.
65+
Once done, the response will return a list of channel-state objects of all closed channels.
6666

6767
.. code:: bash
6868
6969
HTTP/1.1 200 OK
7070
Content-Type: application/json
7171
7272
[
73-
"0x41BCBC2fD72a731bcc136Cf6F7442e9C19e9f313",
74-
"0x5A5f458F6c1a034930E45dC9a64B99d7def06D7E",
75-
"0x8942c06FaA74cEBFf7d55B79F9989AdfC85C6b85"
73+
{
74+
"token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
75+
"channel_identifier": "99",
76+
"network_state": "unknown",
77+
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
78+
"token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
79+
"balance": "350",
80+
"total_deposit": "7331",
81+
"total_withdraw": "0",
82+
"state": "closed",
83+
"settle_timeout": "500",
84+
"reveal_timeout": "50"
85+
}
7686
]
7787
7888
.. note::
7989

8090
Please note that leaving a token network will take some time since you need
8191
to wait for the settle timeout to expire for each channel before a settle
82-
can happen.
83-
92+
can happen.

‎docs/rest_api.rst‎

Lines changed: 46 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Channel Object
2525

2626
{
2727
"channel_identifier": "21",
28+
"network_state": "unknown",
2829
"token_network_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226",
2930
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
3031
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
@@ -54,6 +55,11 @@ A channel object consists of a
5455

5556
- ``balance``: string of the amount of the ``token_address`` token we have available for payments.
5657

58+
- ``network_state``: string representing the online/offline status of the partner node for the channel. Possibly values are:
59+
- ``"unknown"``: Network status is not known (**currently this is the only value returned**)
60+
- ``"reachable"``: The node is known to be online and ready to send and receive messages
61+
- ``"unreachable"``: The node is known to be offline and not ready to send and receive messages
62+
5763
- ``total_deposit``: string of the amount of the ``token_address`` token we have deposited into the contract for this channel.
5864

5965
- ``total_withdraw``: string of the amount of the ``token_address`` token we have withdrawn from the channel on-chain.
@@ -145,11 +151,11 @@ Status
145151

146152
.. http:get:: /api/(version)/status
147153
148-
Query the node status. Possible answers are:
154+
Query the node status. The responses ``status`` attribute can be one of:
149155

150156
- ``"ready"``: The node is listening on its API endpoints.
151157

152-
- ``"syncing"``: The node is still in the initial sync. Number of blocks to sync will also be given.
158+
- ``"syncing"``: The node is still in the initial sync. Number of remaining blocks to sync will also be given.
153159

154160
- ``"unavailable"``: The node is unavailable for some other reason.
155161

@@ -415,6 +421,7 @@ The channels endpoints allow you to open channels with other Raiden nodes as wel
415421
{
416422
"token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
417423
"channel_identifier": "20",
424+
"network_state": "unknown",
418425
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
419426
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
420427
"balance": "25000000",
@@ -452,6 +459,7 @@ The channels endpoints allow you to open channels with other Raiden nodes as wel
452459
{
453460
"token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
454461
"channel_identifier": "20",
462+
"network_state": "unknown",
455463
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
456464
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
457465
"balance": "25000000",
@@ -492,6 +500,7 @@ The channels endpoints allow you to open channels with other Raiden nodes as wel
492500
{
493501
"token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
494502
"channel_identifier": "20",
503+
"network_state": "unknown",
495504
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
496505
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
497506
"balance": "25000000",
@@ -551,6 +560,7 @@ The channels endpoints allow you to open channels with other Raiden nodes as wel
551560
{
552561
"token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
553562
"channel_identifier": "20",
563+
"network_state": "unknown",
554564
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
555565
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
556566
"balance": "25000000",
@@ -648,6 +658,7 @@ The channels endpoints allow you to open channels with other Raiden nodes as wel
648658
{
649659
"token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
650660
"channel_identifier": "20",
661+
"network_state": "unknown",
651662
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
652663
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
653664
"balance": "25000000",
@@ -807,6 +818,8 @@ Besides you can query all payments that you sent or received.
807818
:reqjson string amount: Amount to be sent to the target
808819
:reqjson string identifier: Identifier of the payment (optional)
809820
:reqjson string lock_timeout: lock timeout, in blocks, to be used with the payment. Default is 2 * channel's reveal_timeout, Value must be greater than channel's reveal_timeout (optional)
821+
:reqjson string secret: secret for the HTL, if this should not be randomly generated (optional)
822+
:reqjson string secret_hash: The hash of the provided secret (``sha256(secret)``) this feature currently only works if ``secret`` is provided. If ``secret`` is provided, but ``secret_hash`` is omitted the hash will be calculated by the client automatically (optional)
810823
:reqjson string path: static route to the target node (optional)
811824

812825

@@ -868,7 +881,7 @@ This endpoint can be used to deposit to and withdraw from the UDC.
868881
"total_deposit": "200000"
869882
}
870883

871-
:reqjson string total_deposit: The total deposit token amount. Should be the sum of the current value and the desired deposit.
884+
:reqjson string total_deposit: The total deposit token amount. Should be the sum of the current total value and the desired (relative) deposit.
872885

873886
**Example Response**:
874887

@@ -1021,7 +1034,7 @@ The connections endpoints allow you to query details about all joined token netw
10211034
10221035
The request might take some time because it will only return once all blockchain calls for closing and settling a channel have been completed.
10231036

1024-
The response is a list with the addresses of all closed channels.
1037+
The response is a list of all the channel state objects of the channels that have been closed.
10251038

10261039
**Example Request**:
10271040

@@ -1038,11 +1051,35 @@ The connections endpoints allow you to query details about all joined token netw
10381051
HTTP/1.1 200 OK
10391052
Content-Type: application/json
10401053

1041-
[
1042-
"0x41BCBC2fD72a731bcc136Cf6F7442e9C19e9f313",
1043-
"0x5A5f458F6c1a034930E45dC9a64B99d7def06D7E",
1044-
"0x8942c06FaA74cEBFf7d55B79F9989AdfC85C6b85"
1045-
]
1054+
~
1055+
[
1056+
{
1057+
"balance": "0",
1058+
"channel_identifier": "8854",
1059+
"network_state": "unknown",
1060+
"partner_address": "0x4D156A78Ed6dFDfBbF3E569558eAF895b40217D6",
1061+
"reveal_timeout": "50",
1062+
"settle_timeout": "500",
1063+
"state": "closed",
1064+
"token_address": "0x59105441977ecD9d805A4f5b060E34676F50F806",
1065+
"token_network_address": "0x625F82D937ccA0f1fF0097864895ba91635309A3",
1066+
"total_deposit": "100000000000000000",
1067+
"total_withdraw": "100000000000000000"
1068+
},
1069+
{
1070+
"balance": "0",
1071+
"channel_identifier": "81",
1072+
"network_state": "unknown",
1073+
"partner_address": "0xbea332584a468b462100f8bfe5b38b0573ef1e36",
1074+
"reveal_timeout": "50",
1075+
"settle_timeout": "500",
1076+
"state": "closed",
1077+
"token_address": "0x59105441977ecD9d805A4f5b060E34676F50F806",
1078+
"token_network_address": "0x625F82D937ccA0f1fF0097864895ba91635309A3",
1079+
"total_deposit": "2000000000000",
1080+
"total_withdraw": "2000000000000"
1081+
}
1082+
]
10461083

10471084
:statuscode 200: Successfully leaving a token network
10481085
:statuscode 404: The given token address is not a valid EIP55-encoded Ethereum address

0 commit comments

Comments
 (0)