JavaScript APIs

Introduction

In this section, we will explore the intricacies of interacting with the Circular Network using our JavaScript library. We will delve into how to integrate and leverage the various methods provided by our JavaScript SDK. A fundamental concept to understand is that communication within the network is not directed at individual nodes. Instead, the entire network is accessible through Network Access Gateways (NAGs). These NAGs play a pivotal role in optimizing the workload distribution across the network's nodes, ensuring efficient transaction processing.

Furthermore, NAGs are responsible for intelligently routing transactions across different shards, simplifying communication while maintaining complete transparency regarding the underlying network topology.

Including Javascript Library

There are two primary methods for including JavaScript in your projects. The first method is to embed it directly within the body of your webpage using a script tag:

SetNAGKey & SetNAGURL

GetWallet

    var Result = Circular.GetWallet(Blockchain,
                                    Wallet_Address
                                    );

{
	"Address" : [Wallet Address],
	"Assets" : 
	[
		{
			"Address" : [Asset Owner Address],
			"Amount" : [Asset Amount],
			"EnableSwap" : 0,
			"Name" : "Circular Coin",
			"Price" : 1,
			"Symbol" : "CIRX",
			"Type" : "C_TYPE_COIN",
			"URL" : "",
			"URLType" : ""
		},
		...
	],
	"DateCreation" : "2023:07:22-17:55:39",
	"Nonce" : 30,
	"PublicKey" : [Public Key],
	"Version" : "1.0.1"
}

RegisterWallet

To register a new wallet, you must initiate a new transaction. This registration process ensures that the wallet becomes known to all nodes processing a specific blockchain where the wallet resides. It's important to note that this registration transaction is completely free of charge, with no associated transaction fees.

Circular.RegisterWallet(Blockchain,
                        PrivateKey
                        );

GetAsset

This method is designed to return the content of an asset file in JSON format. The asset will be searched by its exact name, so it must be spelled correctly for the query to succeed.

Asset = Circular.GetAsset(Blockchain,
                          Asset_Name
                          );

Asset = {
        "Address" : [Address],
        "Amount" : [Amount],
        "Blockchain" : [Blockchain],
        "EnableSwap" : [0,1],
        "Name" : [Name],
        "Price" : [Price],
        "Symbol" : [Symbol],
        "Type" : [Asset Type],
        "URL" : [Reference URL],
        "URLType" : [URL COntent Type],
        }

GetAssetSupply

The GetAssetSupply method is utilized to determine both the total supply and circulating supply of an asset. The total supply is retrieved from the asset descriptor, while the circulating supply is calculated by subtracting the available supply in the asset owner's wallet from the total supply.

Response = { 
            "Total" : [total supply],  
            "Circulating" : [Circulating]  
            }

GetBlock

The retrieval of a blockchain block is not a transaction, but just a request that is executed by a single node. In some cases it could be required to send the same request multiple times in order to have a copy of the same block from different sources. Any kind of optimization is executed by the application side, depending from the level of certainity required. In order to request a block it is important to specify the blockchain address (that identifies from which blockchain the block is being pulled) and the number of the block required. For this kind of request there is a specific network method:

var Block = Circular.GetBlock(
                             Blockchain,
                             BlockNumber,
                             );

Block = {
          "Block":{
          "BlockID":123,
          "Blockchain":"8a20baa40c45...dc5ad72b2",
          "Nonce":3289,
          "Node":"02fc8b01bf...2ad78e7e077ea32",
          "PreviousBlockHash":"000cfc03c8ddc3...91be128d6302",
          "TimeStamp":"2023-05-27 03:33:27:31",

          "Payload":{

                    "Transactions":[
                    {
                    "ID":"bb5bdf8a8...91c7d15711a",
                    "From":"6c0f8fc21...7e75aba672916c45d",
                    "To":"e9ac19baf2afb...11755442fe2b8",
                    "Timestamp":"2023:05:26-23:23:44:153",
                    "Type":"C_TYPE_TOKEN",
                    "Payload":"...",
                    "OSignature":"30450221...c953949de12d99c",
                    "NodeID":"7bb5bd50729...70a452d1abe1c4",
                    "TransactionFee":"0.001000",
                    "GasFee":"0.200000"
                    },
                    ...
                    ]
               }
          },
          "Hash":"000c4b909d...b8dea8ca426",
          "Signature":"3045022046e...e5e6dfb78ca38d230"
          }

SendTransaction

Requesting the content of a wallet should not be regarded as a transaction. This distinction arises from the fact that such a request is handled by a single node and does not impact the global state of the network. Transactions, on the other hand, are actions that do influence the overall network state. When we refer to "affecting the global state of the network," we mean that the requested action results in a change of state and requires the execution of an operation by all nodes in the network or a specific subset of nodes. Transactions are typically employed for various purposes, including altering the contents of a wallet, executing a smart contract, or creating/modifying/destroying assets on the blockchains. Transactions serve as the primary mechanism for performing these diverse operations, and they involve several parameters to achieve the desired outcomes. To submit a new transaction, we use the SendTransaction structured as follows:

bool Circular.SendTransaction(
                              ID,
                              From,
                              To,
                              Timestamp,
                              Payload,
                              Nonce,
                              Signature,
                              PublicKey,
                              Blockchain,
                              Type
                              )

SignMessage

This helper function takes care of signing a transaction using the elliptic curve Secp256k1, which is the default cryptographic method used on Circular. The function is used as follows:

getFormattedTimestamp

This helper function takes care of retrieving a timestamp in the format managed by Circular (YYYY:MM:DD-hh:mm:ss) :

Transferring an Asset

This specific transaction type is intended for transferring a specified amount of an available asset from one sending wallet to a recipient wallet. In this scenario, the transaction body and payload will be structured as follows:

var From = [From];
var To = [To];
var Timestamp = Circular.getFormattedTimestamp();
var "Payload" = '{
                   "Action":"CP_SEND",
                   "Asset":[Name of the Asset],
                   "Amount":[Amount to be transferred],
                   "Fee":[Fee]
                   }';

var ID = "0x" + sha256( From + To + Payload + Timestamp);
var Nonce = [Nonce];
var Signature = Circular.SignMessage(PrivateKey, ID);
var PublicKey = [PublicKey];
var Blockchain = [Blockchain];
var Type = "C_TYPE_TOKEN";