Welcome to Insolar documentation for the MainNet JSON RPC 2.0 API.

The API allows to manage members (Insolar users) and their transactions.

Insolar is being developed to provide interoperability between enterprises.

From a business perspective:

• Any enterprise is regarded as an entity with a corresponding identity — a member object stored in the blockchain.
• Any member has its own account to/from which the member can transfer funds.

From a technical perspective:

• Every member object is identified by a reference in the blockchain.
• The reference is effectively the member's address.

Therefore, an entity wishing to transfer funds to/from its account from/to a particular address, in Insolar's terms, is a member object identified by its reference wishing to transfer funds to some other member identified by the corresponding reference.

Insolar uses these terms in method and parameter names.

Insolar has two types of requests that have the same base structure in accordance with the JSON RPC 2.0 specification:

• Information requests that do not require a seed.
• Contract requests that do. These requests are described in Member and Migration sections.

Seed is a unique piece of information generated by a node. The seed:

• has a short lifespan—10 minutes.
• expires upon first use.
• protects from request duplicates.

The seed must be validated by the same node that generated it. Therefore, each subsequent contract request containing the seed must be sent to that node.

To call a smart contract method, go through the following steps:

1. Send a getSeed information request and receive the seed.

   For example, the getSeed request:

   {
       "jsonrpc": "2.0",
       "id": 1,
       "method": "node.getSeed"
   }

   And the response to it:

   {
     "jsonrpc": "2.0",
     "id": 1,
     "result": {
     "seed": "<seed>"
     }
   }

2. Form and sign a contract request with the acquired seed. For example, member.create.

   Every contract request must contain the Digest and Signature HTTP headers. For example:

   POST /<endpoint> HTTP/1.1
   Host: <Host>
   Date: Tue, 07 Jun 2019 20:51:35 GMT
   Content-Type: application/json
   Digest: SHA-256=<hashString>
   Signature: keyId="public-key", algorithm="ecdsa", headers="digest", signature=<signatureString>
   
   { <payload> }

   And the contract request's <payload> with the seed. For example:

   {
     "jsonprc": "2.0",
     "id": 2,
     "method": "contract.call",
     "params": {
       "seed": "<seed>",
       "callSite": "member.create",
       "callParams": {},
       "publicKey": "<pubicKey>"
     }
   }

   In this example:

   • Digest HTTP header contains the Base64-encoded <hashString> with the SHA-256 hash of the payload's bytes.

   • Signature HTTP header contains the Base64-encoded <signatureString> with the ECDSA (Elliptic Curve Digital Signature Algorithm) signature in the ASN.1 DER format. Signed are the bytes of the hash from the Digest header.

   • <pubicKey> contains a Base64-encoded string with the ECDSA public key in PEM format.

   • <seed> contains the seed acquired in the previous getSeed request.

   • "method": "contract.call" designates a call to a contract method.

   • callSite is the contract method call point. In this case, member.create.

   • callParams are the contract method parameters.

3. Send the formed and signed contract request to the node that generated the seed.

   Insolar responds to contract requests with:

   {
     "jsonrpc": "2.0",
     "id": 2,
     "result": {
     "callResult": {
        "reference": <referenceString>
        },
     "requestReference": <requestReferenceString>,
     "traceID": <traceIDString>
     }
   }

   Where "callResult" contains the result of the contract method execution. In this case, it is a reference to a newly created member object since the "callSite" of the request is "member.create".

Insolar follows the JSON RPC API conventions on error codes, with values -31000--31999 reserved for the Insolar network.

Below is the list of Insolar MainNet errors.

API changes in particular Insolar releases and uses the SemVer 2.0 versioning system.

API versions do not have to tally with Insolar MainNet versions.