- Top
- Introduction
- URL and Body Structure
- Get Wallet Content
- Submit a new Transaction
- Registering a new Wallet
- Transferring an Asset
- Retrieving a Block
- Retrieving the Block Height
- Retrieving an Asset
- Retrieving Asset Supply
- Deployment of a Hyper Program
- Hyper Program Request
- Wallet Code Deployment
- Back
INDEX
Network APIs
Introduction
In this section, we will delve into the details of communicating with the Circular Network. We'll learn how to structure various URLs for interaction with the distinct blockchains within the network. A fundamental concept to grasp is that communication does not occur directly with individual nodes; instead, the entire network is accessible via Network Access Gateways (NAGs). These NAGs play a pivotal role in optimizing the workload across the network's nodes, ensuring that they can efficiently process transactions. Furthermore, NAGs are responsible for intelligently routing transactions through the various shards, simplifying communication while remaining entirely transparent to the underlying network topology's intricacies.
URL and Body Structure
The typical URL and body structure adheres to the following formats:
Body = {
"NAGKEY":[NAG KEY],
"TBody":[Transaction body]
}
It's important to note that each NAG has its own unique URL. The remaining data is conveyed as a payload using a POST HTTPS request with a JSON content type. The Payload contains the Body that will be by the NAG to the blockchain Network. All endpoints will answer with Result equal to 200 when successfully executed and the field Response will provide the data required or the error details in Json format.
Get Wallet Content
To retrieve the contents of a wallet, you must utilize the "Circular_GetWallet_" endpoint and specify the the blockchain where the wallet is registered and the wallet address as parameters, excluding the "0x" hexadecimal identifiers.
URL = [NAG URL]Circular_GetWallet_ Body = { "NAGKEY":[NAG KEY], "TBody" :{ "Blockchain" : [Blockchain Address], "Address" : [Wallet Address] } }
If the request is correctly received and the wallet is found, the response will be as follow:
{
"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"
}
Address
This field indicates the wallet's address. It's worth noting that a wallet can exist on multiple blockchains, and each instance may contain different contents. A wallet is considered to be present on a specific blockchain only if it has been registered on that blockchain. NO "0x" hexadecimal identifiers.
Assets
This section comprises an array listing the digital assets contained within the wallet on the specified blockchain. NO "0x" hexadecimal identifiers.
DateCreation
The DateCreation field represents the registration date of the wallet within the selected blockchain. Different instances on various blockchains may have distinct creation dates.
Nonce
Nonce refers to the incremental transaction index used for the next transaction.
PublicKey
This field holds the public key associated with the current wallet. It remains the same across all instances on different blockchains.
Version
The Wallet Version indicates the specific version of the wallet. Newer wallet versions may also include wallet endpoints, which are equivalent to smart contract endpoints.
By presenting the information in this organized manner, it becomes easier for readers to understand the different attributes and their significance within the context of the wallet and blockchain.
Submit a new Transaction
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, the URL is structured as follows:
URL = [NAG URL]Circular_AddTransaction_ TBody = { "ID" : ID, "From" : From, "To" : To, "Timestamp" : Timestamp, "Payload" : Payload, "Nonce" : Nonce, "Signature" : Signature, "PublicKey" : PublicKey, "Blockchain" : Blockchain, "Type" : Type }
ID
Represents the hash of the transaction. TYpically it is calcuated as:
where From, To and Payload are in hexadecimal representation without the "0x" identifier.
The ID will contain the "0x" hexadecimal identifier.
From
This field represents the wallet address of the entity submitting the transaction, excluding the "0x" hexadecimal identifier. It's important to note that the wallet address must be previously registered on the selected blockchain. Additionally, the wallet is required to maintain a sufficient balance of CIRX coins to cover the transaction fees associated with the specific transaction in question. These transaction fees ensure the smooth processing and execution of the requested transaction.
To
This field represents the wallet address of the entity receiving the transaction, excluding the "0x" hexadecimal identifier. If the specific transaction does not require a recipient address, then this field can be equal to the submitting address.
Timestamp
Transaction timestamp in format YYYY:MM:DD-hh:mm:ss in UDT timezone
Payload
String in hexadecimal format without the "0x" hexadecimal identifier (base64 is also accepted).
Nonce
Nonce value for the current transaction. Before submitting a new transaction, it is important to retrieve the current Nonce value from the submitting wallet and use it in the transaction. Please, refer to the Get Wallet Nonce section.
Signature
Signature of the transaction ID in hexadecimal format, without the "0x" identifier. The signature is obtained using Elliptic curve algorithm Secp256k1 (more cryptos will be available soon).
PublicKey
The public key of the "From" Wallet is included in the transaction to expedite the initial transaction pre-validation process. This inclusion eliminates the necessity to access wallet files to retrieve the public key during this phase, streamlining the transaction's efficiency.
Blockchain
Blockchain Address where the transaction is sent, without the hexadecimal identifier.
Type
Types of transaction:
C_TYPE_COIN
Transaction in native coins (CIRX) without the use of Hyper Code (Smart Contract).
C_TYPE_TOKEN
Transaction in specified tokens without the use of Hyper Code.
C_TYPE_ASSET
Transaction involving generic digital asset that is not represented by a token.
C_TYPE_CERTIFICATE
Tranasction where the payload doesn't require any processing and it is just a generic string.
C_TYPE_REGISTERWALLET
Transaction used to register a new wallet on a specified blockchain.
C_TYPE_HC_DEPLOYMENT
Transaction to deploy a new Hyper Code Program.
C_TYPE_HC_REQUEST
Transaction to call a specified endpoint of a Hyper Program.
C_TYPE_USERDEF
Unspecified type, tha is defined by the user (not available yet).
Registering a new Wallet
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.
The key change lies in the type of transaction, which will follow this format:
URL = [NAG URL]Circular_AddTransaction_ TBody = { "ID" : [ID], "From" : [From],> "To" : [From], "Timestamp" : [Timestamp], "Payload" : "", "Nonce" : [Nonce], "Signature" : [Signature], "PublicKey" : [PublicKey], "Blockchain" : [Blockchain], "Type" : "C_TYPE_REGISTERWALLET" }
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:
TBody = {
"ID" : [ID],
"From" : [From],
"To" : [To],<
"Timestamp" : [Timestamp],
"Payload" : {
"Action":"CP_SEND",
"Asset":[Name of the Asset],
"Amount":[Amount to be transferred],
"Fee":[Fee]
},
"Nonce" : [Nonce],
"Signature" : [Signature],
"PublicKey" : [PublicKey],
"Blockchain" : [Blockchain],
"Type" : "C_TYPE_TOKEN"
}
For this specific transaction type, the Payload undergoes parsing and processing to execute the intended operation. In this case, the operation is a CP_SEND transfer, where the asset specified by name is moved to the "To" wallet. If the asset being transferred is the native coin "CIRX," the transaction type is labeled as C_TYPE_COIN. For all other tokens, it is identified as C_TYPE_TOKEN. For CIRX coins the Asset name will be "Circular Coin". The amount to be transferred is represented as a floating-point number with double precision, signifying the quantity of the asset destined for the recipient wallet.
The "fee" field allows the sender to include an optional fee, indicating their willingness to pay to expedite the transaction's inclusion in the next block. If the fee is set to zero, a nominal fee is applied, granting the transaction the lowest priority in block inclusion. Please note that even with an additional fee, there is no guarantee of immediate inclusion in the next block. Subsequently, the payload is converted into a string format and must be encoded in Hex without the "0x" hexadecimal identifier.
Retrieving a Block
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 endpoint:
URL = [NAG URL]Circular_GetBlock_ "TBody" :{ "Blockchain" : [Blockchain Address], "BlockNumber" : [Block Number] }
If the call is successful and the block is found, the returned data will resemble the example below:
{
"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"
}
BlockID
Represents the block's height or block index within the blockchain, where the genesis block has a height of 0.
Blockchain
This is the address of the blockchain containing the block.
Nonce
Represents the number of iterations required to calculate the block hash with the assigned difficulty, which is determined by the number of consecutive zeros at the left end of the hash.
Hash
Block hash calculated using the SHA-256 hashing function.
PreviousBlockHash
The previous block hash is calculated using the SHA-256 hashing function.
Node
The node that has successfully mined or minted the block.
Signature
The signature of the node that has successfully mined or minted the block.
TimeStamp
The timestamp indicating when the block was successfully mined or minted.
Payload
The block payload, also known as transactions, refers to the data or information included in a blockchain block. It typically consists of a collection of transactions that record various activities on the blockchain, such as transfers of digital assets or smart contract executions.
Transactions
The list of transactions contained in a block represents all the individual transactions that have been included in that specific block on a blockchain.
Retrieving the Block Height
This endpoint is designed to provide information about the number of blocks within the selected blockchain, including details about the last block or its height. Upon specifying the blockchain address, this endpoint will return the index of the last block if the operation is successful.
URL = [NAG URL]Circular_GetBlockHeight_ "TBody" :{ "Blockchain" : [Blockchain Address] }
The blockchain address will need to be provided without the "0x" hexadecimal identifier.
"Response" :{
"BlockHeight" : [Block height]
}
The block height will be returned as a non-negative integer.
Retrieving an Asset
This endpoint 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.
URL = [NAG URL]Circular_GetAsset_ "TBody" :{ "Blockchain" : [Blockchain Address], "AssetName" : [Asset Name] }
If the request is executed successfully, the response will resemble the following:
"Response" :{
"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],
}
Where the meanings of all the different fields are:
Blockchain
The blockchain hosting the digital asset.
Name
The unique name assigned to the digital asset.
Symbol
A symbol or ticker used to uniquely identify the digital asset.
Address
The wallet address of the asset owner, which was used to create the digital asset.
Amount
The total supply of the digital asset.
Type
The category or type of digital asset.
URL
The URL linking to metadata or additional information about the digital asset.
URLType
The type of data or content found at the provided URL.
Price
The price of the digital asset, denominated in CIRX.
EnableSwap
A Boolean indicator that determines whether third parties can initiate swaps involving this asset with other digital assets.
Retrieving Asset Supply
This endpoint is designed to return the total supply and circulating supply of an existing asset:
URL = [NAG URL]Circular_GetAssetSupply_
TBody = { "Blockchain" : [Blockchain], "AssetName" : [AssetName] }
If the request is successfully executed, the response will be as follow:
URL = [NAG URL]?cep=Circular_GetAssetSupply_
Response = { "Total" : [Total Supply], "Circulating" : [Circulating Supply] }
Total
Total Supply for the selected asset.
Circulating
Circulating Supply for the selected asset.
Deployment of a Hyper Program
Coming Soon...
Hyper Program Request
Coming Soon...
Wallet Code Deployment
Coming Soon...
