![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/blockchain-architecture-diagram.svg\")
![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.23.15.png\")
<\/a><\/p>\nKey Architectural Points:<\/strong><\/p>\n\n- Decentralized Nature:<\/strong> Unlike traditional client-server models, requests are processed by the distributed network of GRIDNET Core nodes.
CVMContext<\/code> handles selecting appropriate nodes (based on proximity or randomness) and managing the connection (typically WebSocket).<\/li>\n- CVMContext:<\/strong> This singleton JavaScript object is the main entry point for all interactions with the GRIDNET OS backend, including the Blockchain Explorer API.<\/li>\n
- GridScript:<\/strong> Under the hood, most Blockchain Explorer API calls are translated into specific
#GridScript<\/code> commands (e.g., context -c getBlockDetails ...<\/code>). These commands are sent to a Core node for execution within a secure, sandboxed environment.<\/li>\n- Decentralized Processing Threads:<\/strong> GRIDNET OS utilizes the concept of decentralized threads. API calls can optionally target specific threads (
threadID<\/code>). If not specified, they often default to system-managed threads (like the main data thread).<\/li>\n- Asynchronous Communication:<\/strong> Communication between the UI dApp and Core nodes is inherently asynchronous. The API provides both non-async (returning a Request ID immediately) and async (
A<\/code> suffix, returning a Promise) methods.<\/li>\n- Event-Driven Responses:<\/strong> Results from API calls are typically delivered back to the UI dApp via events. The dApp registers specific listeners (e.g.,
addNewBlockDetailsListener<\/code>) with CVMContext<\/code> to receive and process these responses.<\/li>\n- BER Encoding & Meta Data Protocol:<\/strong> Data exchanged between the browser and Core nodes (especially complex data like block or transaction details) uses the GRIDNET Meta Data Protocol, which is BER (Basic Encoding Rules) encoded for efficient and standardized data representation.
CVMContext<\/code> handles the encoding\/decoding internally.<\/li>\n- Security:<\/strong> Communication can be secured using end-to-end encryption and authentication mechanisms managed by
CVMContext<\/code> based on session state and configuration.<\/li>\n<\/ol>\n![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.24.23.png\")
<\/p>\n
Simplified Flow:<\/strong><\/p>\n[UI<\/span> dApp] --(JS<\/span> API Call)--> [CVMContext<\/span>] --(GridScript\/BER<\/span>)--> [WebSocket<\/span>] --> [GRIDNET<\/span> Core Node(s<\/span>)]\r\n^ |\r\n| (BER\/Event<\/span>) |\r\n+------------------------------------------------------------------------------------+\r\n<\/pre>\nUnder the Hood: GridScript Execution and the Decentralized Paradigm<\/span><\/strong><\/h2>\nBeneath the familiar JavaScript interface of the Blockchain Explorer API lies a fundamentally decentralized execution model powered by\u00a0<\/span>#GridScript<\/span><\/strong>. When a UI dApp calls an API method like\u00a0<\/span>CVMContext.getBlockDetailsA()<\/span>,\u00a0<\/span>CVMContext<\/span>\u00a0doesn’t query a local database or send a request to a traditional centralized backend. Instead, it\u00a0<\/span>seamlessly translates<\/span><\/strong>\u00a0the JavaScript call and its parameters into a specific\u00a0<\/span>#GridScript<\/span>\u00a0command string (e.g.,\u00a0<\/span>context -c getBlockDetails -search “<blockID>” -tx<\/span>). This GridScript command, representing the data request, is then packaged using the GRIDNET OS’s BER-encoded\u00a0<\/span>VM Meta Data exchange protocol<\/span><\/strong>\u00a0and dispatched via WebSocket to a connected GRIDNET Core node. The Core node routes this command to an appropriate\u00a0<\/span>Decentralized Processing Thread (DPT)<\/span><\/strong>, which hosts its own sandboxed GridScript virtual machine instance. This VM executes the received command, interacting directly with the node’s local view of the decentralized blockchain state machine to retrieve the requested block details.
\n![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.32.03.png\")
<\/span><\/p>\nThe results are then packaged back into a BER-encoded VM Meta Data response, sent back through the network to the originating\u00a0CVMContext<\/span>, which decodes it and delivers the structured data (like a\u00a0<\/span>CBlockDesc<\/span>\u00a0object) back to the UI dApp, either by resolving the corresponding Promise or triggering a registered event listener. This entire process represents a\u00a0<\/span>paradigm shift from traditional Service-Oriented Architectures (SOA)<\/span><\/strong>; requests are not handled by a centralized server running PHP or .NET against a central database, but are executed decentrally across the network by capable Core nodes running GridScript. This architecture inherently supports a future where such computational or data retrieval tasks performed by nodes could be incentivized, potentially through mechanisms like off-chain cryptocurrency micropayments, truly decentralizing not just data storage but also application logic execution.
\n![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.37.33.png\")
<\/span><\/p>\nLet’s take a look at how the execution environment is structured:<\/p>\n
![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.38.15.png\")
<\/p>\n
Now let’s better understand involvement of BER encoding as it’s involved:<\/p>\n
![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.38.38.png\")
<\/p>\n
Now, let’s go with a complete Blockchain Explorer API execution Cycle:
\n![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.39.05.png\")
\n3. Core Concepts<\/p>\n
3.1 Synchronous vs. Asynchronous API Methods<\/h3>\n
The API offers two styles for many methods:<\/p>\n
\n- Non-Async (Synchronous-like Invocation):<\/strong> Methods like
getBlockDetails(...)<\/code> execute the request immediately and return a unique request identifier<\/code> (a number > 0) if the request was successfully sent<\/em>. The actual result arrives later via an event. The UI dApp needs to register a corresponding listener (e.g., addNewBlockDetailsListener<\/code>) to handle the response, matching it using the reqID<\/code> field in the event argument.<\/li>\n- Async (Promise-based):<\/strong> Methods ending with
A<\/code> (e.g., getBlockDetailsA(...)<\/code>) return a JavaScript Promise<\/code>. This Promise resolves with the result data when the response is received from the network or rejects if an error or timeout occurs. This simplifies handling asynchronous operations compared to managing request IDs and listeners manually.<\/li>\n<\/ul>\nRecommendation:<\/strong> Use the asynchronous (A<\/code> suffix) methods whenever possible for cleaner code structure using async\/await<\/code> or .then()\/.catch()<\/code>.<\/p>\n3.2 Event-Driven Architecture<\/h3>\n
![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.25.56.png\")
<\/p>\n
Responses to API calls and real-time blockchain updates are delivered through events. UI dApps must register listener functions with CVMContext<\/code> using specific add...Listener<\/code> methods.<\/p>\n\n- Listeners:<\/strong> Functions provided by the UI dApp to handle specific types of data (e.g., block details, search results).<\/li>\n
- Notifiers:<\/strong> Internal
CVMContext<\/code> methods (notify...<\/code>) that trigger the registered listeners when relevant data arrives.<\/li>\n- Event Arguments:<\/strong> Listener functions receive an argument object, typically containing:\n
\nreqID<\/code>: The original request identifier (if applicable).<\/li>\ndata<\/code> or specific properties: The payload, often an instance of a data object class (e.g., CBlockDesc<\/code>).<\/li>\n- Other contextual information (e.g.,
processID<\/code>, source<\/code>).<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n3.3 Request\/Response Flow & IDs<\/h3>\n\n- API Call:<\/strong> The UI dApp calls an API method (e.g.,
CVMContext.getTransactionDetails(...)<\/code>).<\/li>\n- Request ID Generation:<\/strong>
CVMContext<\/code> generates a unique request identifier<\/code> (reqID<\/code>).<\/li>\n- GridScript Formulation:<\/strong> The API method formats the corresponding
#GridScript<\/code> command.<\/li>\n- Dispatch:<\/strong>
CVMContext<\/code> (via processGridScriptKM<\/code>) sends the command (encapsulated in Meta Data) over the network. The non-async method returns the reqID<\/code> immediately. The async method registers the Promise internally using this reqID<\/code>.<\/li>\n- Network Processing:<\/strong> GRIDNET Core nodes process the request.<\/li>\n
- Response Delivery:<\/strong> The result is sent back via WebSocket, BER-encoded within the Meta Data protocol.<\/li>\n
- Response Processing:<\/strong>
CVMContext<\/code> receives the message, decrypts\/authenticates if necessary, parses the Meta Data, and identifies the relevant data and original reqID<\/code>.<\/li>\n- Notification\/Resolution:<\/strong>\n
\nCVMContext<\/code> triggers the appropriate notifier function (e.g., notifyNewTransactionDetails<\/code>).<\/li>\n- The notifier function iterates through registered listeners, calling their callback functions with the response data and
reqID<\/code>.<\/li>\n- If the request was made using an async (
A<\/code>) method, CVMContext<\/code> finds the corresponding pending Promise using the reqID<\/code> and resolves it with the data (via resolvePendingRequest<\/code>).<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n![\"\"](\"https:\/\/gridnet.org\/wpp\/wp-content\/uploads\/2025\/04\/Screenshot-2025-04-16-at-09.25.09.png\")
<\/p>\n
3.4 Decentralized Processing Threads (threadID<\/code>)<\/h3>\nGRIDNET OS allows operations to be executed within specific decentralized processing threads. Most Blockchain Explorer API methods accept an optional threadID<\/code> (as an ArrayBuffer<\/code>).<\/p>\n\n- If provided, the operation targets that specific thread.<\/li>\n
- If omitted or an empty
ArrayBuffer<\/code> is provided, it usually defaults to a system-managed thread (often the main Data Thread<\/em>, accessible via CVMContext.getDataThreadID<\/code>).<\/li>\n- The main System Thread<\/em> (
CVMContext.getSystemThreadID<\/code>) handles core system operations.<\/li>\n<\/ul>\n3.5 Process Handles (processHandle<\/code>)<\/h3>\nMany API methods require a processHandle<\/code>. This is typically the instance of the UI dApp’s main class (which usually extends CWindow<\/code>). It’s used for:<\/p>\n\n- Authorization:<\/strong> Ensuring that API calls originate from a registered, valid UI dApp process. Anonymous calls are often disallowed.<\/li>\n
- Context:<\/strong> Linking the API request to the specific application making the call.<\/li>\n
- Resource Management:<\/strong> Potentially used by the system to manage resources associated with the dApp’s requests.<\/li>\n<\/ul>\n
3.6 Execution Modes (mode<\/code>)<\/h3>\nThe mode<\/code> parameter (using the eVMMetaCodeExecutionMode<\/code> enum) specifies how the underlying GridScript command should be executed and how results should be returned. For the Blockchain Explorer API:<\/p>\n\neVMMetaCodeExecutionMode.RAW<\/code>: Typically used. Returns raw, structured data objects (like CBlockDesc<\/code>) suitable for programmatic use.<\/li>\neVMMetaCodeExecutionMode.GUI<\/code>: Might return data formatted for direct display in a terminal-like UI (less common for this API).<\/li>\n<\/ul>\n3.7 Data Objects<\/h3>\n
The API uses specific classes to represent blockchain entities:<\/p>\n
\nCBlockDesc<\/code>: Block details.<\/li>\nCTransactionDesc<\/code>: Transaction details.<\/li>\nCDomainDesc<\/code>: Domain\/account details.<\/li>\nCSearchResults<\/code>: Container for search results, holding multiple items of the above types.<\/li>\nCSearchFilter<\/code>: Used to define complex search criteria.<\/li>\n<\/ul>\nThese objects provide methods for accessing properties and often include serialization (getPackedData<\/code>) and deserialization (instantiate<\/code>) methods for BER encoding.<\/p>\n
\n4. API Reference<\/h2>\n
This section details the public methods provided by CVMContext<\/code> for the Blockchain Explorer API.<\/p>\n4.1 Data Retrieval Methods<\/h3>\ngetRecentTransactions(size, page, includeMem, threadID, processHandle, mode, reqID)<\/code><\/h4>\nRetrieves a list of recent transactions from the blockchain.<\/p>\n
\n- Parameters:<\/strong>\n
\nsize<\/code> {number<\/code>} [Optional, Default: 10] – Number of transactions per page.<\/li>\npage<\/code> {number<\/code>} [Optional, Default: 1] – Page number to retrieve (1-based).<\/li>\nincludeMem<\/code> {boolean<\/code>} [Optional, Default: false] – If true, includes transactions from the memory pool (unconfirmed).<\/li>\nthreadID<\/code> {ArrayBuffer<\/code>} [Optional, Default: Data Thread] – The target decentralized thread ID.<\/li>\nprocessHandle<\/code> {Object<\/code>} [Optional, Default: null] – Handle of the calling UI dApp process (required for user-mode calls).<\/li>\nmode<\/code> {eVMMetaCodeExecutionMode<\/code>} [Optional, Default: RAW<\/code>] – Execution mode.<\/li>\nreqID<\/code> {number<\/code>} [Optional, Default: 0] – Specific request ID to use (0 generates a new one).<\/li>\n<\/ul>\n<\/li>\n- Returns:<\/strong> {
number<\/code>} – A request identifier (reqID > 0<\/code>) if the request was sent successfully, otherwise 0.<\/li>\n- Underlying GridScript:<\/strong>
context -c getRecentTransactions -size <size> -page <page> [-mem]<\/code><\/li>\n- Response Event:<\/strong>