Introduction to System Namespace

The System namespace is a fundamental part of the GridScript++ standard namespaces, providing essential functions and getters that facilitate interactions with the GRIDNET OS decentralized operating system. This namespace includes methods that allow you to retrieve crucial information about the system’s state at any given time, which is key for developing and managing dApps on the GRIDNET platform.

Specifically, the System namespace includes functions to retrieve the hash of the current ‘Perspective,’ which is a fingerprint of the momentary global state of the GRIDNET OS, and the file path of the executing GRIDNET Core dApp. These functionalities are critical for developers and users to interact with the GRIDNET OS, monitor its state, and execute dApps efficiently.

As the foundational layer of the System API, the System namespace acts as the entry point to more specialized functionalities available in the System.user and System.assets sub-namespaces. Utilizing the functionalities provided by the System namespace is essential for leveraging the full potential of the GRIDNET OS and the GridScript++ programming environment.

system.codePath

Description

The system.codePath is a property that returns the path to the current GRIDNET Core application ( a smart-contract). This implies the executable containing instructions currently being executed. With this property an application can be more self-aware.

Return Value

This property returns a string representing the path to the current dApp. Note that the function is context aware, meaning that if GridScript++ code is evaluated from the command line (through the evalGPP command) – en empty string would be returned. When value returned, the path is a an absolute path, meaning it contains a fully qualified State Domain name.

Example Usage:

var path = system.codePath;

In this example, the system.codePath property is used to retrieve the path of the current dApp and store it in the path variable.

system.perspective

Description

The system.perspective is a property that creates a binding with the GridScript ‘perspective’ construct. In other words, the result returned would correspond to what would be returned when executing the ‘perspective’ command from the Terminal (SSH / Terminal UI dApp) of GRIDNET OS. The returned value represents a fingerprint (or an image if you will) of the root of the Merkle-Patricia Trie representing the current state of the decentralized operating system. If any of the persistent sub-states of the system gets changed, the value would change as well. In other words, this value accounts for changes to all of the State Domains, since the overall state of the decentralized operating system is composed of the cumulative states of all of the system’s State Domains. These state domains may be user owned ‘accounts’ or ones owned by GRIDNET Core applications (smart-contracts). To bring things more into a perspective, if a single value transfer is made – the perspective would change. Then, if a user creates a file or alters its contents, or reassigns ownership of a file, or establishes a poll on the folder, or a vote within a poll is issued – it holds the some – the ‘perspective’ – it would change.

Return Value

This property returns an ArrayBuffer object representing the ‘perspective’ construct in GridScript.

Example Usage:

var perspectiveArrayBuffer = system.perspective;

In this example, the system.perspective property is used to retrieve the ‘perspective’ construct as an ArrayBuffer object and store it in the perspectiveArrayBuffer variable.

system.height

Description

The system.height is a property that retrieves the current height of the blockchain. The function can be thus used to keep track of time. Notice that this function returns the current total number of blockchain blocks (including key-blocks) plus one, since counting starts at 0-index. Make sure you understand the difference between key-blocks and data-blocks. Key-blocks contain proof-of-work while data-blocks encapsulate the actual code bundles.

Return Value

This property returns the current height of the blockchain as a number. If the blockchain manager or the script engine is not available, it will return 0.

Example Usage:

var blockchainHeight = system.height;

In this example, the system.height property is used to retrieve the current height of the blockchain and store it in the blockchainHeight variable.

system.keyHeight

Description

The system.keyHeight is a property that retrieves the current key height of the blockchain. Recall that current leader is elected through proof-of-work. Once elected, the leader can append many data blocks containing the actual code bundles. Key-height represents the current number of key blocks plus one – since counting starts at 0-index.

Return Value

This property returns the current key height of the blockchain as a number. If the blockchain manager or the script engine is not available, it will return 0.

Example Usage:

var blockchainKeyHeight = system.keyHeight;

In this example, the system.keyHeight property is used to retrieve the current key height of the blockchain and store it in the blockchainKeyHeight variable.

Introduction to System.user Namespace

The System.user namespace is a specialized sub-namespace of the System namespace in GridScript++. It contains essential functions and getters that allow you to interact with and manage user-related functionalities of the GRIDNET OS decentralized operating system. This includes retrieving the identity of the currently logged-in user, which is fundamental for managing user sessions and securing user interactions with dApps on the GRIDNET platform.

Notice that the values returned largely depend on the execution context. The code may be running as part of a GRIDNET Core application (smart-contract), the code may be being evaluated anonymously from a command line (user not logged in and not in the scope of any State Domain), the code may be being evaluated from a command line not from the scope of any State Domain but user has logged in (either by scanning the QR code in UI session, or by invoking the logmein command explicitly from the command line.

Utilizing the functionalities provided by the System.user namespace is critical for managing user sessions, securing user data, and enabling personalized interactions with the GRIDNET OS and dApps. As a crucial part of the System API, the System.user namespace is fundamental for leveraging the user management capabilities of the GRIDNET OS and the GridScript++ programming environment. The API can be used for security critical operations such as lookinn-up the caller of a dApp. When executing in kernel-mode (not evaluated from a Terminal or UI) the returned values are guaranteed to have been authenticated through a secure Elliptic Curve signature.

system.user.id

The system.user.id is a getter that retrieves the full user ID of the current context. Note that this may not reflect the security context in which the code is executing. For that, use System.authID.

Return Value

This getter returns the fully qualified user ID as an ArrayBuffer. If the script engine, State Domain manager, or user ID cannot be retrieved for any reason, it will return an empty ArrayBuffer.

Example Usage:

var currentUserID = system.user.id;

In this example, the system.user.id getter is used to retrieve the fully qualified user ID of the current context and store it in the currentUserID variable.

system.user.nickname

Description

The system.user.nickname getter retrieves the nickname associated with the current user. The logic behind this operation depends on the execution context (whether the code is being run within a contract or in an ephemeral thread). In any case, the system retrieves the Identity Token of the current user and returns the Friendly Identifier present within of it. If the identity in whose name the current code is executing has no Identity Token registered then this getter would return an empty string.

Return Value

This getter returns a string representing the user’s nickname. If the script engine, State Domain manager, or nickname cannot be retrieved for any reason, it will return an empty string.

Example Usage:

var userNickname = system.user.nickname;

In this example, the system.user.nickname getter is used to retrieve the nickname of the current user and store it in the variable userNickname.

system.user.stake

Description

The system.user.stake getter retrieves the stake associated with the current user. The logic behind this operation depends on the execution context (whether the code is being run within a contract or in an ephemeral thread). The system would retrieve Identity Token of an identity in whose name the current code is executing. If no identity is registered with the current identity, the system would return 0.

Return Value

This getter returns a string representing the user’s stake. If the script engine, State Domain manager, or stake information cannot be retrieved for any reason, it will return an empty string.

Example Usage:

var userStake = system.user.stake;

In this example, the system.user.stake getter is used to retrieve the stake of the current user and store it in the variable userStake.

Introduction to System.assets Namespace

The System.assets namespace is another specialized sub-namespace of the System namespace in GridScript++. It contains essential functions and getters that allow you to interact with and manage asset-related functionalities of the GRIDNET OS decentralized operating system. This includes retrieving the identity of the entity issuing an ingress value transfer, and checking whether the caller of a dApp delivered any assets. Furthermore, this namespace provides functionalities for dApps to issue assets back to the caller, enabling efficient asset transactions within the GRIDNET platform.

Utilizing the functionalities provided by the System.assets namespace is critical for managing asset transactions, enabling secure and efficient interactions with the GRIDNET OS and dApps. As a vital part of the System API, the System.assets namespace is fundamental for leveraging the asset management capabilities of the GRIDNET OS and the GridScript++ programming environment. When executing in kernel-mode (not evaluated from a Terminal or UI, but as part of an already deployed GRIDNET Core application) the returned values are guaranteed to have been authenticated through a secure Elliptic Curve signature.

system.assets.balance

Description

The system.assets.balance() function retrieves the balance of the current State Domain in GNC (GRIDNET Coins). Optionally, you can specify an explicit State Domain ID as an argument to check its balance. The results depend on the context of execution and provided (optional) arguments.

Parameters

• stateDomainID (Optional): The ID of the State Domain whose balance you want to retrieve. This can be either a string or an ArrayBuffer.

Return Value

Returns a number representing the balance in GNC. If the GridScript engine or the specified State Domain is not available, an error will be thrown. In kernel-mode and if no arguments provided, the value returned always corresponds to the identity who signed the executable code package. In ephemeral mode and if no arguments provided, the value returned corresponds to 1) the logged in identity if user is logged in 2) the current State Domain if in terminal and executing code from scope of a State Domain 3) otherwise the value returned would be 0.

Errors

• If more than one argument is passed, a TypeError will be thrown.
• If the argument is neither a string nor an ArrayBuffer, a TypeError will be thrown.

Example Usage:

// Retrieving the balance of the current State Domain
var myBalance = system.assets.balance();
// Retrieving the balance of a specific State Domain
var specificBalance = system.assets.balance("someStateDomainID");

In these examples, the system.assets.balance getter is used to retrieve the balance of the current State Domain and store it in the variable myBalance. The balance of a specific State Domain is stored in the variable specificBalance.

system.assets.receivedGNCFrom

Description

The system.assets.receivedGNCFrom getter retrieves the State Domain identifier of the entity that issued an ingress value transfer. Recall that a value transfer can be issued to a GRIDNET Core application through the callTransfer GridScript command. See in-terminal MAN-page of this command for more information.

Syntax

// Get the State Domain identifier of the entity that issued an ingress value transfer
system.assets.receivedGNCFrom;

Parameters

No parameters required.

Return Value

Returns a string representing the State Domain identifier of the entity that issued an ingress value transfer. If the GridScript engine is not available, it will throw an error “VM is not available.”

Errors

Throws an error if the GridScript engine is not available.

Example Usage:

// Retrieving the State Domain identifier of the entity that issued an ingress value transfer
var senderID = system.assets.receivedGNCFrom;

In this example, the system.assets.receivedGNCFrom getter is used to retrieve the State Domain identifier of the entity that issued an ingress value transfer and store it in the variable senderID.

system.assets.sendGNCFloat

Description

The sendGNCFloat function sends a specified amount of GNC (Grid Net Coin) to a given destination. The amount is expressed as a floating-point number and is internally converted to a BigFloat representation before being processed.

syntax

system.assets.sendGNCFloat(destination, value);

Parameters

• destination (String): The State Domain identifier or friendly ID of the destination.
• value (Double): The amount of GNC to be sent.

Returns:
Boolean: true if the command was successfully processed.

Errors
An error will be thrown if:

• The number of arguments is not exactly two.
• The destination argument is not a string or is an empty string.
• The value argument is not a number or is too large (causing an overflow when multiplied by 1e18).
• The GridScript engine is no longer available.
• The value argument is too large.
• The function fails to send GNC.

Example Usage:

// Sending 123.456 GNC to 'Alpacalypse'
system.assets.sendGNCFloat("Alpacalypse", 123.456);

In this example, the sendGNCFloat function is used to send 123.456 GNC to ‘Alpacalypse’.

Note

Under the hood, the function performs the following actions:

1. Retrieves and validates the input arguments.
2. Retrieves the GridScript engine, all the processing would be taken care of by the latter.
3. Converts the double amount to BigFloat, scales it by 1e18 (conversion to Atto units), and converts the result to a string.
4. Constructs the GridScript command “send [destination] [value]” and sends it to the script engine for processing, thus resulting in a value transfer dominated in GNC due to the a-priori converstion.

The function performs extensive error checking and will throw appropriate errors in case of invalid input or if an error occurs during the operation.

Warning

The destination string must not be empty, and the value must not be so large that it could cause an overflow when multiplied by 1e18 (the person holding such an amount of value would need to have more assets then envision by Tokenomics thus the problem from a practical perspective does not exist). Also, under the hood, the underlying BigInt / BigFloat containers can store values up to 256 bits in double floating point precision. That precision needs to suffice for representation of value in Atto-denomination.