From 7b954c7b903ca93d3bba2b507569ff9b997963ad Mon Sep 17 00:00:00 2001 From: Jacob Stenum Czepluch Date: Wed, 12 Jul 2017 23:31:22 +0200 Subject: [PATCH 1/8] Initial work on updating the Raiden documentation This fixes one small error in Overview-And-Guide.rst It's main focus is to write a user guide for the API endpoints. --- docs/Get-Started-With-API-Walkthough.rst | 116 +++++++++++++++++++++++ docs/Overview-And-Guide.rst | 8 +- 2 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 docs/Get-Started-With-API-Walkthough.rst diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst new file mode 100644 index 0000000000..b586422772 --- /dev/null +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -0,0 +1,116 @@ +Getting started with the Raiden API +################################### + + +Contents: + +.. toctree:: + :maxdepth: 2 + + + +Introduction +************* +Raiden has a Restful API with URL endpoints corresponding to actions that the user can perform with his channels. The endpoints accept and return JSON encoded objects. The api url path always contains the api version in order to differentiate queries to different API versions. All queries start with: ``/api//`` + +In this guide we will walk through the steps neccessary in order to participate in a Raiden Token Network. We will provide some different scenarios such as joining an already existing token network, registering a new token network, together with opening, closing and settling channels. + +Before you get started with below guides, please see :doc:`Overview and Guide <./Overview-And-Guide.rst>`, to make sure that you are connected to Raiden. + +Furthermore, to see all available endpoints, please see :doc:`REST API Endpoints <./Rest-Api.rst>`. + + +Scenarios +********* +Below you'll find a series of different scenarios showing different ways that the Raiden API can be used and interacted with. + +A good way to check that you started Raiden correctly before proceeding is to check that your raiden address is the same address as the ethereum address that you chose, when starting the raiden node:: + + GET /api/1/address + +If this returns your address, you know that your raiden node is connected to the network. + +Adding an unregistered token to Raiden +====================================== +In this scenario we assume that a user holds some ERC20 tokens of a type that has not yet been registered in the Raiden smart contracts. Let's assume that the address of the token is ``0x9aBa529db3FF2D8409A1da4C9eB148879b046700``. + +The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new raiden channels between two parties. + + +Checking if a token is already registered +----------------------------------------- +One way of checking if a token is already registered is to get the list of all registered tokens and check if the address of the token you want to interact with exists in the list:: + + GET /api/1/tokens + +If the address of the token you want to interact with exists in the list, see the :ref:`next scenario `. +If it does not exist in the list, we need to :ref:`register the token `. + + +.. _adding-a-token: +Registering a token +------------------- +In order to register a token all we need is the address of the token. When a new token is registered a Channel Manager contract is deployed, which makes it quite an expensive thing to do in terms of gas usage ``TODO insert estimated gas price``. + +To register a token simply use the endpoint listed below:: + + PUT /api/1/tokens/0x9aBa529db3FF2D8409A1da4C9eB148879b046700 + +If successful this call will return the address of the fresly created Channel Manager like this:: + + {"channel_manager_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226"} + +The token is now registered. However, since we're the ones registering the token, there will be nobody else to connect to right away. This means that we need to bootstrap the network for this specific token. If we know of some other Raiden node that holds some of the tokens we just added or we simply want to transfer some tokens to another Raiden node in a one way channel, we can do this quite easily by simply opening a channel with this node. The way we open a channel with another Raiden node is the same whether the partner already holds some tokens or not. + + +.. _opening-a-channel: +Opening a channel +----------------- +To open a channel with another Raiden node we need four things: the address of the token, the address of the partner node, the amount of tokens we want to deposit, and the settlement timeout period. With these things ready we can open a channel:: + + PUT /api/1/channels + +With the payload:: + + { + "partner_address": "0x61c808d82a3ac53231750dadc13c777b59310bd9", + "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700", + "balance": 1337, + "settle_timeout": 600 + } + +* TODO adjust settle_timeout ? + +At this point we don't worry too much about the `"balance"` field, since we can always :ref:`deposit more tokens ` to a channel if need be. + +Succesfully opening a channel will return the following information:: + + { + "channel_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226", + "partner_address": "0x61c808d82a3ac53231750dadc13c777b59310bd9", + "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700", + "balance": 1337, + "state": "open", + "settle_timeout": 600 + } + +Here it's interesting to notice that a `"channel_address"` has been generated. This means that a :ref:`Netting Channel contract ` has been deployed to the blockchain. Furthermore it also represents the address of the raiden channel between two parties for a specific token. + +.. _depositing-to-a-channel: +Depositing to a channel +----------------------- + + + +* bootstrapping + + +.. _scenario2: +Joining an already existing token network +========================================= + + + +Interacting with the Raiden echo node +===================================== + diff --git a/docs/Overview-And-Guide.rst b/docs/Overview-And-Guide.rst index 51fa4f6f3d..276e5f3ed7 100644 --- a/docs/Overview-And-Guide.rst +++ b/docs/Overview-And-Guide.rst @@ -48,7 +48,8 @@ After you have done that you can proceed to install the dependencies:: pip install --upgrade -r requirements.txt python setup.py develop -You will also need an ethereum client that is connected to the Ropsten testnet. In example, download the parity client:: +You will also need an ethereum client that is connected to the Ropsten testnet. See below for guidelines on how to connect with both Parity and Geth. + Firing it up ------------ @@ -57,7 +58,8 @@ Using geth ~~~~~~~~~~ Run the client and let it sync with the Ropsten testnet:: - geth --testnet --fast --nodiscover console + + geth --testnet --fast --nodiscover console And then when in the console add a few peers by using ``admin.addPeer()`` and the latest peers shown `here `_. @@ -82,5 +84,5 @@ After account creation, launch raiden with the path of your keystore supplied an raiden --keystore-path "~/.local/share/io.parity.ethereum/keys/test" --eth-rpc-endpoint "127.0.0.1:8545" -Select the ethereum account when prompted, and type in the account's password. +Select the ethereum account when prompted, and type in the account's password. From f786a2f2a7908970cc0b1ee8c2fa0fca34471daf Mon Sep 17 00:00:00 2001 From: Jacob Stenum Czepluch Date: Thu, 13 Jul 2017 17:36:12 +0200 Subject: [PATCH 2/8] Finalize draft of first section This commit finalizes the first draft of the section explaining how bootstrap a token network for a not already registered token. Furtermore it fixes a small "bug" in the API doc where the same address is used for a channel and a channel manager --- docs/Get-Started-With-API-Walkthough.rst | 46 ++++++++++++++++++++++-- docs/Rest-Api.rst | 2 +- 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index b586422772..ad8add1112 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -34,7 +34,7 @@ Adding an unregistered token to Raiden ====================================== In this scenario we assume that a user holds some ERC20 tokens of a type that has not yet been registered in the Raiden smart contracts. Let's assume that the address of the token is ``0x9aBa529db3FF2D8409A1da4C9eB148879b046700``. -The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new raiden channels between two parties. +The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new payment channels between two parties. Checking if a token is already registered @@ -58,7 +58,7 @@ To register a token simply use the endpoint listed below:: If successful this call will return the address of the fresly created Channel Manager like this:: - {"channel_manager_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226"} + {"channel_manager_address": "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a"} The token is now registered. However, since we're the ones registering the token, there will be nobody else to connect to right away. This means that we need to bootstrap the network for this specific token. If we know of some other Raiden node that holds some of the tokens we just added or we simply want to transfer some tokens to another Raiden node in a one way channel, we can do this quite easily by simply opening a channel with this node. The way we open a channel with another Raiden node is the same whether the partner already holds some tokens or not. @@ -94,15 +94,47 @@ Succesfully opening a channel will return the following information:: "settle_timeout": 600 } -Here it's interesting to notice that a `"channel_address"` has been generated. This means that a :ref:`Netting Channel contract ` has been deployed to the blockchain. Furthermore it also represents the address of the raiden channel between two parties for a specific token. +Here it's interesting to notice that a `"channel_address"` has been generated. This means that a `Netting Channel contract `_ has been deployed to the blockchain. Furthermore it also represents the address of the payment channel between two parties for a specific token. + .. _depositing-to-a-channel: Depositing to a channel ----------------------- +A payment channel is now open between our own address and ``0x61c808d82a3ac53231750dadc13c777b59310bd9``. However, since only one of the nodes has deposited to the channel, only that node can make transfers at this point in time. Now would be the time to notify our counterparty that we have opened a channel with him/her/it, so that they can also deposit to the channel. All the counterparty needs in order to do this is the address of the payment channel:: + + PATCH /api/1/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226 + +with the payload:: + + {"balance": 7331} + +We can then query the channel for events to see when our counterparty deposits:: + + GET /api/1/events/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226?from_block=1337 + +This will return a list of events that has happened in the specific payment channel. The relevant event we are looking for in this case will be:: + + { + "event_type": "ChannelNewBalance", + "participant": "0x61c808d82a3ac53231750dadc13c777b59310bd9", + "balance": 7331, + "block_number": 54388 + } +If we see above event we know that our partner has deposited to the channel. +It is possible for both parties to query the state of the specific payment channel by calling:: + + GET /api/1/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226 + +This will give you a result similar to those in :ref:`Opening a Channel ` that represents the current state of the payment channel. + +We have now registered a new token resulting in a new token network. We have opened a channel between two Raiden nodes, and both nodes have deposited to the channel. From here on we can start :ref:`transferring tokens ` between the two nodes. + +Above is not how a user would normally join an already existing token network. We will take a closer look at how to join already bootstrapped token networks in :ref:`the next scenario `. Above shows how a user would bootstrap a new token network. This would not be the steps that most users would have to follow, since these steps are only needed when bootstrapping a new token network. * bootstrapping +* TODO should the addresses used in the documentation actually be deployed contracts etc., or is it fine that it's just some random adresses? .. _scenario2: @@ -111,6 +143,14 @@ Joining an already existing token network +.. _transferring-tokens: +Transferring tokens +=================== + + + + + Interacting with the Raiden echo node ===================================== diff --git a/docs/Rest-Api.rst b/docs/Rest-Api.rst index 3b0ad1cd26..39d2f71728 100644 --- a/docs/Rest-Api.rst +++ b/docs/Rest-Api.rst @@ -126,7 +126,7 @@ Example Response And with a 201 response we also get:: - {"channel_manager_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226"} + {"channel_manager_address": "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a"} Querying Information About Channels and Tokens =============================================== From 9c4a95c460c10e7110d967c93d6738523729677f Mon Sep 17 00:00:00 2001 From: Jacob Stenum Czepluch Date: Fri, 14 Jul 2017 15:39:51 +0200 Subject: [PATCH 3/8] adding section on joining existing token network --- docs/Get-Started-With-API-Walkthough.rst | 51 ++++++++++++++++++------ 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index ad8add1112..2720c133d8 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -13,7 +13,7 @@ Introduction ************* Raiden has a Restful API with URL endpoints corresponding to actions that the user can perform with his channels. The endpoints accept and return JSON encoded objects. The api url path always contains the api version in order to differentiate queries to different API versions. All queries start with: ``/api//`` -In this guide we will walk through the steps neccessary in order to participate in a Raiden Token Network. We will provide some different scenarios such as joining an already existing token network, registering a new token network, together with opening, closing and settling channels. +In this guide we will walk through the steps necessary in order to participate in a Raiden Token Network. We will provide some different scenarios such as joining an already existing token network, registering a new token network, together with opening, closing and settling channels. Before you get started with below guides, please see :doc:`Overview and Guide <./Overview-And-Guide.rst>`, to make sure that you are connected to Raiden. @@ -24,17 +24,18 @@ Scenarios ********* Below you'll find a series of different scenarios showing different ways that the Raiden API can be used and interacted with. -A good way to check that you started Raiden correctly before proceeding is to check that your raiden address is the same address as the ethereum address that you chose, when starting the raiden node:: +A good way to check that you started Raiden correctly before proceeding is to check that your Raiden address is the same address as the ethereum address that you chose, when starting the Raiden node:: GET /api/1/address -If this returns your address, you know that your raiden node is connected to the network. +If this returns your address, you know that your Raiden node is connected to the network. -Adding an unregistered token to Raiden -====================================== +.. _bootstrapping-a-token-network: +Bootstrapping a token network +============================= In this scenario we assume that a user holds some ERC20 tokens of a type that has not yet been registered in the Raiden smart contracts. Let's assume that the address of the token is ``0x9aBa529db3FF2D8409A1da4C9eB148879b046700``. -The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new payment channels between two parties. +The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new payment channels between two parties. Checking if a token is already registered @@ -43,7 +44,7 @@ One way of checking if a token is already registered is to get the list of all r GET /api/1/tokens -If the address of the token you want to interact with exists in the list, see the :ref:`next scenario `. +If the address of the token you want to interact with exists in the list, see the :ref:`next scenario `. If it does not exist in the list, we need to :ref:`register the token `. @@ -56,7 +57,7 @@ To register a token simply use the endpoint listed below:: PUT /api/1/tokens/0x9aBa529db3FF2D8409A1da4C9eB148879b046700 -If successful this call will return the address of the fresly created Channel Manager like this:: +If successful this call will return the address of the freshly created Channel Manager like this:: {"channel_manager_address": "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a"} @@ -83,7 +84,7 @@ With the payload:: At this point we don't worry too much about the `"balance"` field, since we can always :ref:`deposit more tokens ` to a channel if need be. -Succesfully opening a channel will return the following information:: +Successfully opening a channel will return the following information:: { "channel_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226", @@ -94,7 +95,7 @@ Succesfully opening a channel will return the following information:: "settle_timeout": 600 } -Here it's interesting to notice that a `"channel_address"` has been generated. This means that a `Netting Channel contract `_ has been deployed to the blockchain. Furthermore it also represents the address of the payment channel between two parties for a specific token. +Here it's interesting to notice that a `"channel_address"` has been generated. This means that a `Netting Channel contract `_ has been deployed to the blockchain. Furthermore it also represents the address of the payment channel between two parties for a specific token. .. _depositing-to-a-channel: @@ -130,18 +131,42 @@ This will give you a result similar to those in :ref:`Opening a Channel ` between the two nodes. -Above is not how a user would normally join an already existing token network. We will take a closer look at how to join already bootstrapped token networks in :ref:`the next scenario `. Above shows how a user would bootstrap a new token network. This would not be the steps that most users would have to follow, since these steps are only needed when bootstrapping a new token network. +Above is not how a user would normally join an already existing token network. We will take a closer look at how to join already bootstrapped token networks in :ref:`the next scenario `. Above shows how a user would bootstrap a new token network. This would not be the steps that most users would have to follow, since these steps are only needed when bootstrapping a new token network. * bootstrapping -* TODO should the addresses used in the documentation actually be deployed contracts etc., or is it fine that it's just some random adresses? +* TODO should the addresses used in the documentation actually be deployed contracts etc., or is it fine that it's just some random addresses? -.. _scenario2: + +.. _joining-existing-token-network: Joining an already existing token network ========================================= +In :ref:`Above scenario ` we saw how to bootstrap a token network for an unregistered token. In this section we will take a look at the most common way of joining a token network. In most cases users don't want to create a new token network, but they want to join an already existing token network for an ERC20 token that they already hold. + +The main focus of this section will be the usage of the ``connect`` and the ``leave`` endpoints. The ``connect`` endpoint allows users to automatically connect to a token network and open channels with other nodes. Furthermore the ``leave`` endpoint allows users to leave a token network by automatically closing and settling all the open payment channels of the user. + +Let's assume that a user holds 2000 of some awesome ERC20 token (AET). The user knows that a Raiden based token network already exists for this token. + +Connecting to an already existing token network is quite simple and all you need, is as mentioned above, the address of the token network you want to join and some of the corresponding tokens:: + + PUT /api/v1/connection/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671 + +With a payload representing the amount of tokens that you want to join the network with:: + + { + "funds": 2000 + } + +This will automatically connect you to and open channels with three random peers in the token network. Furthermore it will leave 40% of the tokens you join the network with as initially unassigned. This will allow new nodes joining the network to open bi-directionally funded payment channels with our node in the same way that we just opened channels with random nodes already in the network. The default values of opening three channels and leaving 40% of the tokens for new nodes to connect with, can be changed by adding ``"initial_channel_target": our_value`` and ``"joinable_funds_target": our_decimal_number`` to the payload. + +We are now connected to the token network for the AET token, and we should have a path to all other nodes that have joined this token network, so that we can transfer tokens to all nodes participating in this network. See the :ref:`Transferring tokens ` section for instructions on how to transfer tokens to other nodes. + +If we at some point want to leave the token network the ``leave`` endpoint is available. This endpoint will take care of closing and settling all open channels in the token network:: + DELETE /api/v1/connection/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671 +This call will take some time to finalize, due to the nature of the way that settlement of payment channels work. For more information on the the nature of settlement see :doc:`TODO ADD DOCUMENT ON RAIDEN PAYMENT CHANNEL NATURE `. .. _transferring-tokens: Transferring tokens From d62a7814a2cf9c8d81e5fc1bd80bd66835014e52 Mon Sep 17 00:00:00 2001 From: Jacob Stenum Czepluch Date: Fri, 14 Jul 2017 19:23:55 +0200 Subject: [PATCH 4/8] add tranfer section and fix small error in api doc --- docs/Get-Started-With-API-Walkthough.rst | 43 +++++++++++++++++++++++- docs/Rest-Api.rst | 4 +-- 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index 2720c133d8..7a7426e3e8 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -148,6 +148,10 @@ The main focus of this section will be the usage of the ``connect`` and the ``le Let's assume that a user holds 2000 of some awesome ERC20 token (AET). The user knows that a Raiden based token network already exists for this token. + +.. _connect: +Connect +------- Connecting to an already existing token network is quite simple and all you need, is as mentioned above, the address of the token network you want to join and some of the corresponding tokens:: PUT /api/v1/connection/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671 @@ -162,16 +166,53 @@ This will automatically connect you to and open channels with three random peers We are now connected to the token network for the AET token, and we should have a path to all other nodes that have joined this token network, so that we can transfer tokens to all nodes participating in this network. See the :ref:`Transferring tokens ` section for instructions on how to transfer tokens to other nodes. + +.. _leave: +Leave +----- If we at some point want to leave the token network the ``leave`` endpoint is available. This endpoint will take care of closing and settling all open channels in the token network:: DELETE /api/v1/connection/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671 -This call will take some time to finalize, due to the nature of the way that settlement of payment channels work. For more information on the the nature of settlement see :doc:`TODO ADD DOCUMENT ON RAIDEN PAYMENT CHANNEL NATURE `. +This call will take some time to finalize, due to the nature of the way that settlement of payment channels work. For more information on the nature of settlement see :doc:`TODO ADD DOCUMENT ON RAIDEN PAYMENT CHANNEL NATURE `. + .. _transferring-tokens: Transferring tokens =================== +So far we know how to bootstrap a token network, how to join an already existing token network, and how to leave a token network. However, we still need to take a look at what Raiden is really all about - transferring tokens from one node to another in off-chain payment channels. Let's assume that we are connected to the token network of the AET token mentioned above. In this case we are connected to five peers, since we used that standard ``connect()`` parameters. + + +.. _transfer: +Transfer +-------- +Transferring tokens to another node is quite easy. We know the address of the token we want to transfer ``0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671``. All we then need to know is the address of the node we want to transfer to. Let's say the address of the node we want to transfer to is ``0x61c808d82a3ac53231750dadc13c777b59310bd9``:: + + POST /api/1/transfers/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671/0x61c808d82a3ac53231750dadc13c777b59310bd9 + +We also need to know the amount that we want to transfer. We add this as the payload:: + + { + "amount": 42, + } + +An ``"identifier": some_integer`` can also be added to the payload, but it's optional. + +If there is a path in the network with enough capacity and the address sending the transfer holds enough tokens to transfer the amount in the payload, the transfer will go through. The receiving node should then be able to see incoming transfers by querying all its open channels. This is done by doing the following for all addresses of open channels:: + + GET /api/1/events/channels/0x000397DFD32aFAAE870E6b5FB44154FD43e43224?from_block=1337 + +Which will return a list of events. All we then need to do is to filter for incoming transfers. + +Please note that one of the most powerful features of Raiden is that we can send transfers to anyone connected to the network as long as there is a path with enough capacity, and not just to the nodes that we are directly connected to. +.. _close: +Close +----- + +.. _settle: +Settle +------ diff --git a/docs/Rest-Api.rst b/docs/Rest-Api.rst index 39d2f71728..74adfd569e 100644 --- a/docs/Rest-Api.rst +++ b/docs/Rest-Api.rst @@ -642,9 +642,9 @@ Example Response :: { - "initiator_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226", + "initiator_address": "0xea674fdde714fd979de3edf0f56aa9716b898ec8", "target_address": "0x61c808d82a3ac53231750dadc13c777b59310bd9", - "token_address": "0xea674fdde714fd979de3edf0f56aa9716b898ec8", + "token_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226", "amount": 200, "identifier": 42 } From 57e4b3372cf5ad147843fb63cc4c30d39f471ca3 Mon Sep 17 00:00:00 2001 From: Jacob Stenum Czepluch Date: Fri, 14 Jul 2017 20:58:31 +0200 Subject: [PATCH 5/8] finalize getting started with API guide --- docs/Get-Started-With-API-Walkthough.rst | 48 +++++++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index 7a7426e3e8..9435b795b1 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -24,7 +24,7 @@ Scenarios ********* Below you'll find a series of different scenarios showing different ways that the Raiden API can be used and interacted with. -A good way to check that you started Raiden correctly before proceeding is to check that your Raiden address is the same address as the ethereum address that you chose, when starting the Raiden node:: +A good way to check that you started Raiden correctly before proceeding is to check that your Raiden address is the same address as the Ethereum address that you chose, when starting the Raiden node:: GET /api/1/address @@ -205,18 +205,62 @@ If there is a path in the network with enough capacity and the address sending t Which will return a list of events. All we then need to do is to filter for incoming transfers. Please note that one of the most powerful features of Raiden is that we can send transfers to anyone connected to the network as long as there is a path with enough capacity, and not just to the nodes that we are directly connected to. + + .. _close: Close ----- +If at any point in time we should want to close a specific channel we can do so with the ``close`` endpoint:: + + PATCH /api/1/channels/0x000397DFD32aFAAE870E6b5FB44154FD43e43224 + +with the payload:: + + { + "state":"closed" + } + +When successful this will give a response with a channel object where the state is set to ``"closed"``:: + + { + "channel_address": "0x000397DFD32aFAAE870E6b5FB44154FD43e43224", + "partner_address": "0x61c808d82a3ac53231750dadc13c777b59310bd9", + "token_address": "0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671", + "balance": 350, + "state": "closed", + "settle_timeout": 600 + } +Notice how the ``state`` is set to ``"closed"`` compared to the channel objects we've seen earlier where it was ``"open"``. .. _settle: Settle ------ +Once ``"close"`` has been called there is a timeout period, where the counterparty of the channel can provide the last received message from our node. When this timeout settlement timeout period is over, we can finally settle the channel:: + PATCH /api/1/channels/0x000397DFD32aFAAE870E6b5FB44154FD43e43224 + +with the payload:: + + { + "state":"settled" + } + +this will trigger the ``settle()`` function in the `NettingChannelContract `_ smart contract. Once settlement is successful a channel object will be returned:: + + { + "channel_address": "0x000397DFD32aFAAE870E6b5FB44154FD43e43224", + "partner_address": "0x61c808d82a3ac53231750dadc13c777b59310bd9", + "token_address": "0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671", + "balance": 0, + "state": "settled", + "settle_timeout": 600 + } + +Here it's interesting to notice that the balance of the channel is now ``0`` and that the state is set to ``"settled"``. This means that netted balance that we are owed from our counterparty has now been transferred to us on the blockchain and that the life cycle of the payment channel is ended. Interacting with the Raiden echo node ===================================== - +TODO once the echo node is ready From f9f12af5f8b13ac6ae76a94d856c9b0f1f868548 Mon Sep 17 00:00:00 2001 From: Lefteris Karapetsas Date: Sun, 16 Jul 2017 11:28:36 +0200 Subject: [PATCH 6/8] Doc fixes in Get Started Guide --- docs/Get-Started-With-API-Walkthough.rst | 38 ++++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index 9435b795b1..027232098b 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -11,7 +11,7 @@ Contents: Introduction ************* -Raiden has a Restful API with URL endpoints corresponding to actions that the user can perform with his channels. The endpoints accept and return JSON encoded objects. The api url path always contains the api version in order to differentiate queries to different API versions. All queries start with: ``/api//`` +Raiden has a Restful API with URL endpoints corresponding to actions that the user can perform with his channels. The endpoints accept and return JSON encoded objects. The api url path always contains the api version in order to differentiate queries to different API versions. All queries start with: ``/api//`` where ```` is an integer representing the current API version. In this guide we will walk through the steps necessary in order to participate in a Raiden Token Network. We will provide some different scenarios such as joining an already existing token network, registering a new token network, together with opening, closing and settling channels. @@ -28,14 +28,14 @@ A good way to check that you started Raiden correctly before proceeding is to ch GET /api/1/address -If this returns your address, you know that your Raiden node is connected to the network. +If this returns your address, you know that your Raiden node has the API up and running. .. _bootstrapping-a-token-network: Bootstrapping a token network ============================= In this scenario we assume that a user holds some ERC20 tokens of a type that has not yet been registered in the Raiden smart contracts. Let's assume that the address of the token is ``0x9aBa529db3FF2D8409A1da4C9eB148879b046700``. -The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new payment channels between two parties. +The user wants to register the token, which will create a `Channel Manager `_. For each registered token there is a channel manager. Channel managers are responsible of opening new payment channels between two parties. Checking if a token is already registered @@ -51,7 +51,7 @@ If it does not exist in the list, we need to :ref:`register the token `_ has been deployed to the blockchain. Furthermore it also represents the address of the payment channel between two parties for a specific token. +Here it's interesting to notice that a `"channel_address"` has been generated. This means that a `Netting Channel contract `_ has been deployed to the blockchain. Furthermore it also represents the address of the payment channel between two parties for a specific token. .. _depositing-to-a-channel: Depositing to a channel ----------------------- -A payment channel is now open between our own address and ``0x61c808d82a3ac53231750dadc13c777b59310bd9``. However, since only one of the nodes has deposited to the channel, only that node can make transfers at this point in time. Now would be the time to notify our counterparty that we have opened a channel with him/her/it, so that they can also deposit to the channel. All the counterparty needs in order to do this is the address of the payment channel:: +A payment channel is now open between our own address and ``0x61c808d82a3ac53231750dadc13c777b59310bd9``. However, since only one of the nodes has deposited to the channel, only that node can make transfers at this point in time. Now would be the time to notify our counterparty that we have opened a channel with them, so that they can also deposit to the channel. All the counterparty needs in order to do this is the address of the payment channel and a call like the following:: PATCH /api/1/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226 @@ -109,7 +109,7 @@ with the payload:: {"balance": 7331} -We can then query the channel for events to see when our counterparty deposits:: +If we want to see when the counterparty deposited token, we can then query the channel for the corresponding event:: GET /api/1/events/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226?from_block=1337 @@ -122,7 +122,7 @@ This will return a list of events that has happened in the specific payment chan "block_number": 54388 } -If we see above event we know that our partner has deposited to the channel. +If we see the above event we know that our partner has deposited to the channel. It is possible for both parties to query the state of the specific payment channel by calling:: GET /api/1/channels/0x2a65aca4d5fc5b5c859090a6c34d164135398226 @@ -131,12 +131,12 @@ This will give you a result similar to those in :ref:`Opening a Channel ` between the two nodes. -Above is not how a user would normally join an already existing token network. We will take a closer look at how to join already bootstrapped token networks in :ref:`the next scenario `. Above shows how a user would bootstrap a new token network. This would not be the steps that most users would have to follow, since these steps are only needed when bootstrapping a new token network. +The above is not how a user would normally join an already existing token network. It is the manual way to show how you it works under the hood. +We will take a closer look at how to join already bootstrapped token networks in :ref:`the next scenario `. -* bootstrapping -* TODO should the addresses used in the documentation actually be deployed contracts etc., or is it fine that it's just some random addresses? +* bootstrapping .. _joining-existing-token-network: @@ -144,7 +144,7 @@ Joining an already existing token network ========================================= In :ref:`Above scenario ` we saw how to bootstrap a token network for an unregistered token. In this section we will take a look at the most common way of joining a token network. In most cases users don't want to create a new token network, but they want to join an already existing token network for an ERC20 token that they already hold. -The main focus of this section will be the usage of the ``connect`` and the ``leave`` endpoints. The ``connect`` endpoint allows users to automatically connect to a token network and open channels with other nodes. Furthermore the ``leave`` endpoint allows users to leave a token network by automatically closing and settling all the open payment channels of the user. +The main focus of this section will be the usage of the ``connect`` and the ``leave`` endpoints. The ``connect`` endpoint allows users to automatically connect to a token network and open channels with other nodes. Furthermore the ``leave`` endpoint allows users to leave a token network by automatically closing and settling all of their open channels. Let's assume that a user holds 2000 of some awesome ERC20 token (AET). The user knows that a Raiden based token network already exists for this token. @@ -152,7 +152,7 @@ Let's assume that a user holds 2000 of some awesome ERC20 token (AET). The user .. _connect: Connect ------- -Connecting to an already existing token network is quite simple and all you need, is as mentioned above, the address of the token network you want to join and some of the corresponding tokens:: +Connecting to an already existing token network is quite simple and all you need, is as mentioned above, the address of the token network you want to join and how much of the corresponding token you are willing to use for depositing in channels:: PUT /api/v1/connection/0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671 @@ -180,7 +180,7 @@ This call will take some time to finalize, due to the nature of the way that set .. _transferring-tokens: Transferring tokens =================== -So far we know how to bootstrap a token network, how to join an already existing token network, and how to leave a token network. However, we still need to take a look at what Raiden is really all about - transferring tokens from one node to another in off-chain payment channels. Let's assume that we are connected to the token network of the AET token mentioned above. In this case we are connected to five peers, since we used that standard ``connect()`` parameters. +So far we know how to bootstrap a token network, how to join an already existing token network, and how to leave a token network. However, we still need to take a look at what Raiden is really all about - transferring tokens from one node to another in off-chain payment channels. Let's assume that we are connected to the token network of the AET token mentioned above. In this case we are connected to five peers, since we used the standard ``connect()`` parameters. .. _transfer: @@ -196,7 +196,7 @@ We also need to know the amount that we want to transfer. We add this as the pay "amount": 42, } -An ``"identifier": some_integer`` can also be added to the payload, but it's optional. +An ``"identifier": some_integer`` can also be added to the payload, but it's optional. The identifier's purpose is solely for the benefit of the apps built on top of Raiden in order to provide a way to tag transfers. If there is a path in the network with enough capacity and the address sending the transfer holds enough tokens to transfer the amount in the payload, the transfer will go through. The receiving node should then be able to see incoming transfers by querying all its open channels. This is done by doing the following for all addresses of open channels:: @@ -204,7 +204,7 @@ If there is a path in the network with enough capacity and the address sending t Which will return a list of events. All we then need to do is to filter for incoming transfers. -Please note that one of the most powerful features of Raiden is that we can send transfers to anyone connected to the network as long as there is a path with enough capacity, and not just to the nodes that we are directly connected to. +Please note that one of the most powerful features of Raiden is that we can send transfers to anyone connected to the network as long as there is a path to them with enough capacity, and not just to the nodes that we are directly connected to. .. _close: @@ -236,7 +236,7 @@ Notice how the ``state`` is set to ``"closed"`` compared to the channel objects .. _settle: Settle ------ -Once ``"close"`` has been called there is a timeout period, where the counterparty of the channel can provide the last received message from our node. When this timeout settlement timeout period is over, we can finally settle the channel:: +Once ``"close"`` has been called then start the settle timeout period, where the counterparty of the channel can provide the last received message from our node. When this timeout settlement timeout period is over, we can finally settle the channel by doing:: PATCH /api/1/channels/0x000397DFD32aFAAE870E6b5FB44154FD43e43224 @@ -246,7 +246,7 @@ with the payload:: "state":"settled" } -this will trigger the ``settle()`` function in the `NettingChannelContract `_ smart contract. Once settlement is successful a channel object will be returned:: +this will trigger the ``settle()`` function in the `NettingChannelContract `_ smart contract. Once settlement is successful a channel object will be returned:: { "channel_address": "0x000397DFD32aFAAE870E6b5FB44154FD43e43224", @@ -257,7 +257,7 @@ this will trigger the ``settle()`` function in the `NettingChannelContract Date: Sun, 16 Jul 2017 11:37:56 +0200 Subject: [PATCH 7/8] index.rst should be lowercase for makefile to work --- docs/{Index.rst => index.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{Index.rst => index.rst} (100%) diff --git a/docs/Index.rst b/docs/index.rst similarity index 100% rename from docs/Index.rst rename to docs/index.rst From 3859fb944b1b0757d52387ebd2704a721dbbe2c1 Mon Sep 17 00:00:00 2001 From: Lefteris Karapetsas Date: Sun, 16 Jul 2017 11:38:16 +0200 Subject: [PATCH 8/8] Fix links in Get Started Walkthrough --- docs/Get-Started-With-API-Walkthough.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/Get-Started-With-API-Walkthough.rst b/docs/Get-Started-With-API-Walkthough.rst index 027232098b..827bc95db5 100644 --- a/docs/Get-Started-With-API-Walkthough.rst +++ b/docs/Get-Started-With-API-Walkthough.rst @@ -15,9 +15,9 @@ Raiden has a Restful API with URL endpoints corresponding to actions that the us In this guide we will walk through the steps necessary in order to participate in a Raiden Token Network. We will provide some different scenarios such as joining an already existing token network, registering a new token network, together with opening, closing and settling channels. -Before you get started with below guides, please see :doc:`Overview and Guide <./Overview-And-Guide.rst>`, to make sure that you are connected to Raiden. +Before you get started with below guides, please see :doc:`Overview and Guide `, to make sure that you are connected to Raiden. -Furthermore, to see all available endpoints, please see :doc:`REST API Endpoints <./Rest-Api.rst>`. +Furthermore, to see all available endpoints, please see :doc:`REST API Endpoints `. Scenarios @@ -31,6 +31,7 @@ A good way to check that you started Raiden correctly before proceeding is to ch If this returns your address, you know that your Raiden node has the API up and running. .. _bootstrapping-a-token-network: + Bootstrapping a token network ============================= In this scenario we assume that a user holds some ERC20 tokens of a type that has not yet been registered in the Raiden smart contracts. Let's assume that the address of the token is ``0x9aBa529db3FF2D8409A1da4C9eB148879b046700``. @@ -49,6 +50,7 @@ If it does not exist in the list, we need to :ref:`register the token `. - +``TODO`` * bootstrapping .. _joining-existing-token-network: + Joining an already existing token network ========================================= In :ref:`Above scenario ` we saw how to bootstrap a token network for an unregistered token. In this section we will take a look at the most common way of joining a token network. In most cases users don't want to create a new token network, but they want to join an already existing token network for an ERC20 token that they already hold. @@ -150,6 +155,7 @@ Let's assume that a user holds 2000 of some awesome ERC20 token (AET). The user .. _connect: + Connect ------- Connecting to an already existing token network is quite simple and all you need, is as mentioned above, the address of the token network you want to join and how much of the corresponding token you are willing to use for depositing in channels:: @@ -168,6 +174,7 @@ We are now connected to the token network for the AET token, and we should have .. _leave: + Leave ----- If we at some point want to leave the token network the ``leave`` endpoint is available. This endpoint will take care of closing and settling all open channels in the token network:: @@ -178,12 +185,14 @@ This call will take some time to finalize, due to the nature of the way that set .. _transferring-tokens: + Transferring tokens =================== So far we know how to bootstrap a token network, how to join an already existing token network, and how to leave a token network. However, we still need to take a look at what Raiden is really all about - transferring tokens from one node to another in off-chain payment channels. Let's assume that we are connected to the token network of the AET token mentioned above. In this case we are connected to five peers, since we used the standard ``connect()`` parameters. .. _transfer: + Transfer -------- Transferring tokens to another node is quite easy. We know the address of the token we want to transfer ``0xc9d55C7bbd80C0c2AEd865e9CA13D015096ce671``. All we then need to know is the address of the node we want to transfer to. Let's say the address of the node we want to transfer to is ``0x61c808d82a3ac53231750dadc13c777b59310bd9``:: @@ -208,6 +217,7 @@ Please note that one of the most powerful features of Raiden is that we can send .. _close: + Close ----- If at any point in time we should want to close a specific channel we can do so with the ``close`` endpoint:: @@ -234,6 +244,7 @@ When successful this will give a response with a channel object where the state Notice how the ``state`` is set to ``"closed"`` compared to the channel objects we've seen earlier where it was ``"open"``. .. _settle: + Settle ------ Once ``"close"`` has been called then start the settle timeout period, where the counterparty of the channel can provide the last received message from our node. When this timeout settlement timeout period is over, we can finally settle the channel by doing::