Explore use cases

In short, to integrate with Insolar MainNet, do the following:

  1. Create an Insolar wallet to keep the users’ XNS coins. See the use cases: Create a Wallet and Get the Wallet’s Balance.

  2. Let the users deposit XNS coins to your wallet—provide them with the wallet address. See the use cases: Deposit Funds to Exchange and Deposit Coins to Exchange.

  3. Let the users withdraw XNS coins. They must create their own wallets on the MainNet and provide you with addresses of these wallets. See the use cases: Create a Wallet and Withdraw Coins from Exchange.

  4. Transfer XNS coins between wallets on the MainNet. See the use case: Transfer Coins.

  5. Get information on transactions on the MainNet. See the corresponding API request.

To invoke APIs correctly, familiarize yourself with:

  • General API invocation sequence.

  • List of API integration use cases. Each use case describes a sequence of steps and a list of corresponding API requests used in those steps.

The requests themselves are described in detail in the Insolar’s API specifications — MainNet API and Observer API.

To simplify testing, Insolar can provide a testing environment on demand.

General API invocation sequence

The general API invocation sequence is as follows:

@startuml
skinparam componentStyle uml2
skinparam shadowing false

title Invoking Insolar API

actor "Exchange" as E
control "insolar-api\nEndpoint" as Ins
control "insolar-observer-api\nEndpoint" as Obs

group insolar-api\n(wallet creation, transfers)
     E -> Ins : RPC API POST\n\t<b>node.getSeed</b>()
     activate Ins
     return <color:blue><b>seed</b></color>\n\t(used to identify individual RPC API request)

     E -> Ins : RPC API POST\n\t<b>contract.call</b>(\n\t\t<color:blue><b>seed</b></color>,\n\t\tother params\n\t)
     activate Ins
     Ins -> Ins : handling\nAPI request
     return result
end

group insolar-observer-api\n(reading wallet balance and other info)
     E -> Obs: REST GET\n\t<b>endpoint</b>/{params}
     activate Obs
     Obs -> Obs : handling\nAPI request
     return result
end

@enduml

Integration use cases

Below is the list of integration use cases.

Use case: Create a wallet

To create a wallet:

  1. Generate a private/public key pair.

  2. Invoke Insolar’s API:

    1. Provide the public key.

    2. Receive a reference to the new member—address on the Insolar network.

The wallet creation sequence is as follows:

@startuml
skinparam componentStyle uml2
skinparam shadowing false

title Wallet Creation

actor "User" as U
control "insolar-api\nEndpoint" as RPC
entity "Insolar" as Ins

activate U
U -> U : generate new private/public key pair\n\t(<b>publicKey</b> used later\n\tto create & identify Insolar user)

U -> RPC : RPC API POST\n\tnode.getSeed()
activate RPC
return <b>seed</b>
U -> RPC : RPC API POST\n\tmember.create(\n\t\tsignature,\n\t\t<b>seed</b>,\n\t\t<b>publicKey</b>\n\t)
activate RPC
RPC -> Ins : invoke the MainNet
activate Ins
Ins -> Ins : create new \n\tuser & wallet
return
return <b>memberReference</b>\n\t(used later to identify\n\tInsolar member & wallet)
deactivate U

@enduml

API requests used:

  • node.getSeed

  • member.create

Use case: Get the wallet balance

To view the balance, a user (exchange service or any other user) can either:

  • Use their Insolar Wallet web interface.

  • Or invoke the API using their Insolar’s credentials (memberReference or publicKey).

The viewing sequence is as follows:

@startuml
skinparam componentStyle uml2
skinparam shadowing false

title Get Balance

actor "Exchange" as E
control "insolar-api\nEndpoint" as RPC
control "insolar-observer-api\nEndpoint" as REST
entity "Insolar" as Ins

== Identifying a User (if memberReference not provided) ==
E -> RPC : RPC API POST\n\tnode.getSeed()
activate RPC
return <b>seed</b>
E -> RPC : RPC API POST\n\t<b>member.get</b>(\n\t\tsignature,\n\t\t<b>seed</b>,\n\t\t<b>publicKey</b>\n\t)
activate RPC
RPC -> Ins
activate Ins
Ins -> Ins : identify the user
return
return memberReference


== Getting Wallet Info ==
Ins <--> REST : stay in sync
activate Ins
activate REST
deactivate REST
deactivate Ins
E -> REST: REST GET\n\t<b>member</b>/{<b>memberReference</b>}
activate E
activate REST
return {\n\tbalance,\n\tdeposits\n}
E -> REST: REST GET\n\t<b>balance</b>/{<b>memberReference</b>}
activate E
activate REST
return balance
deactivate E

@enduml

API requests used:

  • node.getSeed

  • member.get

API endpoints used:

  • GET <observer_URL>/member/{memberReference}

  • GET <observer_URL>/member/{memberReference}/balance

Use case: Transfer coins

To transfer XNS coins to another user, a user (exchange or any other) can either:

  • Use their Insolar Wallet.

  • Or invoke the API.

To transfer coins via API, provide:

  1. Sender’s memberReference, so Insolar can identify the sender.

  2. toMemberReference—recipient’s reference.

  3. An amount of XNS coins to transfer.

Note

To retrieve the memberReference, invoke the relevant API and provide a public key.

The transfer sequence is as follows:

@startuml
skinparam componentStyle uml2
skinparam shadowing false

title Coin Transfer

actor "Exchange" as E
control "insolar-api\nEndpoint" as RPC
entity "Insolar" as Ins

== Identifying a User (if memberReference not provided) ==
E -> RPC : RPC API POST\n\tnode.getSeed()
activate RPC
return <b>seed</b>
E -> RPC : RPC API POST\n\t<b>member.get</b>(\n\t\tsignature,\n\t\t<b>seed</b>,\n\t\t<b>publicKey</b>\n\t)
activate RPC
RPC -> Ins
activate Ins
Ins -> Ins : identify the user
return
return memberReference

== Performing Transfer ==
E -> RPC : RPC API POST\n\tnode.getSeed()
activate RPC
return <b>seed</b>
E -> RPC : RPC API POST\n\t<b>member.transfer</b>(\n\t\tsignature,\n\t\t<b>seed</b>,\n\t\tpublicKey,\t\t\t\t// user performing the transfer\n\t\tmemberReference,\t// user performing the transfer\n\t\t<b>amount</b>,\n\t\t<b>toMemberReference</b>\t// the recipient\n\t)
activate RPC
RPC -> Ins
activate Ins
Ins -> Ins : perform transfer
return
return {\n\tfee,\t// transfer's fee value\n\trequestReference\n}

@enduml

API requests used:

  • node.getSeed

  • (optional) member.get

  • member.transfer

Use case: Deposit funds to an exchange

When a user deposits funds to the exchange and immediately converts them to XNS, an accompanying transfer between wallets should be performed.

This case is similar to coin transfer, where:

  • memberReference is the reference to the owner of the wallet the coins are withdrawn from.

  • toMemberReference is the reference to the exchange’s wallet.

Use case: Deposit coins to an exchange

When a user deposits XNS coins to the exchange, an accompanying transfer between wallets should be performed.

This case is similar to coin transfer, where:

  • memberReference is the reference to the owner of the wallet the coins are withdrawn from.

  • toMemberReference is the reference to the exchange’s wallet.

Use case: Withdraw coins from an exchange

Prerequisite: the recipient must have an Insolar’s wallet created as described in wallet creation.

This case is similar to coin transfer, where:

  • memberReference is the reference to the owner of the wallet the coins are withdrawn from.

    Note

    This can be either a wallet opened by the exchange for the user, or the exchange’s wallet.

  • toMemberReference is the reference to the recipient.