{"id":835498,"date":"2026-02-18T18:57:02","date_gmt":"2026-02-18T18:57:02","guid":{"rendered":"https:\/\/gridnet.org\/wpp\/?p=835498"},"modified":"2026-02-20T07:57:36","modified_gmt":"2026-02-20T07:57:36","slug":"anatomy-of-a-ui-dapp-architecture-that-protects-you","status":"publish","type":"post","link":"https:\/\/mag.gridnet.org\/index.php\/2026\/02\/18\/anatomy-of-a-ui-dapp-architecture-that-protects-you\/","title":{"rendered":"The Anatomy of a UI dApp \u2014 Architecture That Protects You"},"content":{"rendered":"
Every application you have ever built on the traditional web sits naked in a shared environment. Your JavaScript runs in the same global scope as third-party analytics. Your CSS bleeds into neighboring widgets. Your DOM is one document.querySelector<\/code> away from being read \u2014 or rewritten \u2014 by code you never wrote and never audited. You accepted this because you had no choice.GRIDNET OS gives you a choice.This article disassembles the architecture of a GRIDNET OS UI dApp down to its bolts. By the end, you will understand every layer \u2014 from the Shadow DOM fortress that isolates your interface, through the BER-encoded protocol that connects your browser to a decentralized virtual machine, to the lifecycle hooks that let you build applications as robust as the Wallet, Terminal, and Messenger that ship with the platform. This is not a tutorial. This is a blueprint.<\/p>\n
I. The Shadow DOM Fortress \u2014 Why Isolation Matters<\/h2>\nEach dApp lives inside its own Shadow DOM boundary \u2014 an impenetrable membrane that prevents CSS bleed, DOM manipulation, and cross-application interference.<\/figcaption><\/figure>\nWhen you build a UI dApp for GRIDNET OS, your application does not live in the main document. It lives inside a Shadow DOM \u2014 a browser-native isolation boundary that creates a miniature, self-contained document within the larger page. Shadow DOM is opt-in: the CWindow<\/code> constructor accepts a useShadowDOM<\/code> parameter that controls whether your dApp gets a shadow root or a regular DOM container. The Wallet enables it for full CSS encapsulation; the Terminal disables it because xterm.js manages its own rendering. For most dApps with custom CSS, Shadow DOM is the recommended default.<\/p>\n
How the Shadow DOM is Created<\/h3>\nEvery UI dApp extends the CWindow<\/code> base class. When a window is constructed, the platform creates a DOM element for the window frame, then attaches your application’s HTML into either a Shadow DOM or a regular DOM container, depending on the useShadowDOM<\/code> constructor parameter:<\/p>\n
\n\/\/ From window.js \u2014 the moment of isolation\nif (this.getUseShadowDOM) {\n    let shadow = innerBody.attachShadow({ mode: 'open' });\n\n    let shadowContainer = $('<div\/>', {\n        html: \"<input type='hidden' id='windowIDField' value=\" + this.mID + \"> \"\n              + this.mInnerBodyHTML,\n        \"class\": \"shadowContainer idContainer\",\n        \"style\": \"width: 100%; height: 100%;\"\n    })[0];\n\n    shadow.appendChild(shadowContainer);\n} else {\n    $(innerBody).html(this.mInnerBodyHTML);\n}\n<\/pre>\nThat call to attachShadow({ mode: 'open' })<\/code> is where the fortress walls go up. From this moment forward:CSS isolation is absolute.<\/strong> Styles defined inside your Shadow DOM cannot leak out to affect other dApps. Styles defined outside \u2014 including those from other dApps or the platform shell \u2014 cannot reach in. Your .btn<\/code> class will never collide with another dApp’s .btn<\/code> class. This is not achieved through naming conventions or CSS modules; it is enforced by the browser engine itself.DOM queries are scoped.<\/strong> A call to document.querySelector('.wallet-panel')<\/code> from outside your dApp will return null<\/code>, even if your dApp contains elements with that class. The only way to reach elements inside a Shadow DOM is through the shadow root reference, which the platform controls.Event propagation is re-targeted.<\/strong> Events that originate inside your Shadow DOM are re-targeted when they cross the shadow boundary, making the shadow host appear as the event target rather than the actual internal element. This prevents other code from deducing your internal DOM structure by listening to events.<\/p>\n
What It Protects Against<\/h3>\nThe Shadow DOM protects against an entire category of problems that plague traditional web applications:Cross-dApp CSS pollution.<\/strong> On a traditional page, if two widgets both define .container { padding: 20px }<\/code>, one wins and the other breaks. In GRIDNET OS, each dApp’s styles are invisible to every other dApp.DOM manipulation attacks.<\/strong> A malicious or buggy dApp cannot reach into your Shadow DOM to read form values, inject elements, or modify your interface. The browser enforces this boundary at the engine level.Global namespace collisions.<\/strong> Each Shadow DOM is its own document fragment. IDs that must be unique within a document only need to be unique within your shadow tree. You can safely use id=\"terminal\"<\/code> without worrying that the Terminal dApp already claimed that ID.XSS cross-contamination.<\/strong> Even if another dApp on the same page suffers an XSS vulnerability, the attacker’s injected script cannot traverse Shadow DOM boundaries to reach your application’s internals.<\/p>\n
Querying Inside the Shadow DOM<\/h3>\nBecause standard document.querySelector<\/code> cannot penetrate Shadow DOM boundaries, the CWindow<\/code> base class provides helper methods:<\/p>\n
\n\/\/ Query a single element inside your Shadow DOM\nshadowQuery(selector) {\n    return this.getBody.querySelector(selector);\n}\n\n\/\/ Query all matching elements\nshadowQueryAll(selector) {\n    return this.getBody.querySelectorAll(selector);\n}\n<\/pre>\nThe getBody<\/code> property returns your dApp’s content root. When Shadow DOM is enabled, it returns the .shadowContainer<\/code> element inside the shadow root. When Shadow DOM is disabled, it returns the #windowBody<\/code> element directly. All DOM operations within your dApp should use these methods (or this.getBody.querySelector<\/code> directly) rather than document.querySelector<\/code>.In practice, the most common DOM access pattern is the getControl(controlID)<\/code> method, which uses jQuery’s .find()<\/code> internally to locate elements by ID within your window’s scope:<\/p>\n
\ngetControl(controlID) {\n    if (controlID == null) return null;\n    if (this.isElement(controlID)) return controlID;\n    let results = $(this.getBody).find('#' + controlID);\n    if (results.length == 0) return null;\n    return results[0];\n}\n<\/pre>\nThe Wallet dApp uses getControl()<\/code> extensively. Both approaches \u2014 shadowQuery()<\/code> and getControl()<\/code> \u2014 respect isolation boundaries.<\/p>\n
The Mutation Observer \u2014 Your Watchdog<\/h3>\nThe platform attaches a MutationObserver<\/code> to every window’s body element:<\/p>\n
\n\/\/ From window.js \u2014 the observer that watches for DOM changes\nconst targetNode = this.getBody;\nconst config = { attributes: false, childList: true, subtree: true };\n\nthis.mObserver = new MutationObserver(this.observerCallback.bind(this));\nthis.mObserver.observe(targetNode, config);\n<\/pre>\nThis observer monitors DOM mutations within your dApp. If the mutation rate exceeds a configured threshold (mCurtainThreshold<\/code>), the platform automatically shows a “curtain” overlay \u2014 a loading screen that prevents users from interacting with a partially-rendered interface. This protects against janky UI during heavy DOM operations (like loading hundreds of transaction rows) and automatically hides once the UI stabilizes.<\/p>\n
II. The dApp Lifecycle \u2014 From Birth to Graceful Death<\/h2>\nA dApp progresses through distinct lifecycle phases: construction, listener registration, CVMContext binding, active operation, and cleanup on close.<\/figcaption><\/figure>\nA UI dApp in GRIDNET OS is not simply HTML that gets inserted into a page. It is a managed process with a defined lifecycle that the platform orchestrates. Understanding this lifecycle is essential to building dApps that initialize correctly, communicate with the blockchain, and clean up after themselves without leaking resources.<\/p>\n
Phase 1: Construction \u2014 The CWindow Base<\/h3>\nEvery dApp extends CWindow<\/code>. The constructor is where everything begins:<\/p>\n
\nclass CTerminal extends CWindow {\n    constructor(positionX, positionY, width, height) {\n        super(positionX, positionY, width, height,\n              terminalBody,        \/\/ Your HTML template\n              \"Terminal\",           \/\/ Window title\n              CTerminal.getIcon(), \/\/ Base64-encoded icon\n              false                \/\/ useShadowDOM flag\n              \/\/ Additional optional params: data, dataType, filePath, thread\n        );\n        \/\/ Your initialization code follows...\n    }\n}\n<\/pre>\nThe CWindow<\/code> constructor performs a remarkable amount of work on your behalf:<\/p>\n
\nProcess registration.<\/strong> Calls CVMContext.getInstance().getNewProcessID()<\/code> to obtain a unique process ID. This ID is your dApp’s identity within the platform.<\/li>\n
DOM creation.<\/strong> Builds the window frame (title bar, resize handles, min\/max\/close buttons) and injects your HTML template into the body area.<\/li>\n
Shadow DOM attachment.<\/strong> If useShadowDOM<\/code> is true, creates an isolated shadow root (as described above).<\/li>\n
Mutation observer setup.<\/strong> Attaches the MutationObserver to detect DOM churn.<\/li>\n
Settings integration.<\/strong> Connects to CSettingsManager<\/code> for persisting user preferences.<\/li>\n
Request tracking initialization.<\/strong> Sets up internal maps for tracking network requests, DFS operations, and VM metadata exchanges.<\/li>\n<\/ol>\nPhase 2: Listener Registration \u2014 Subscribing to the Decentralized World<\/h3>\nAfter the super()<\/code> call completes, your dApp registers for the events it cares about. This is the most critical phase for connecting to blockchain state. Here is how the Terminal dApp does it:<\/p>\n
\n\/\/ From Terminal.js \u2014 registering for platform events\nCVMContext.getInstance().addVMMetaDataListener(\n    this.newVMMetaDataCallback.bind(this), this.mID\n);\nCVMContext.getInstance().addNewDFSMsgListener(\n    this.newDFSMsgCallback.bind(this), this.mID\n);\nCVMContext.getInstance().addNewGridScriptResultListener(\n    this.newGridScriptResultCallback.bind(this), this.mID\n);\nCVMContext.getInstance().addNewTerminalDataListener(\n    this.newTerminalDataCallback.bind(this), this.mID\n);\nCVMContext.getInstance().addVMStateChangedListener(\n    this.VMStateChangedCallback.bind(this), this.mID\n);\n<\/pre>\nEvery listener registration follows the same pattern:<\/p>\n
\nCVMContext.getInstance().addXxxListener(callback, appID);\n<\/pre>\nThe appID<\/code> parameter (typically this.mID<\/code>, which is \"window_\" + processID<\/code>) is crucial. It ties the listener to your dApp instance. When your window closes, the platform uses this ID to automatically unregister all your listeners \u2014 preventing memory leaks and ghost callbacks.Here is how the platform stores these listeners internally:<\/p>\n
\n\/\/ From VMContext.js \u2014 listener registration pattern\naddVMMetaDataListener(eventListener, appID = 0) {\n    const id = ++this.mCallbackHandlerSeqNr;\n    this.mNewVMMetaDataListeners.push({\n        eventListener,  \/\/ Your callback function\n        appID,          \/\/ Your window ID for cleanup\n        id              \/\/ Unique listener ID for selective removal\n    });\n    return id;\n}\n<\/pre>\nThe returned id<\/code> can be used for selective removal via unregisterEventListenerByID(id)<\/code>, but in most cases the automatic cleanup on window close handles this.<\/p>\n
Available Listener Types<\/h3>\nThe CVMContext<\/code> singleton offers a comprehensive set of event subscriptions:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nListener Method<\/th>\n When It Fires<\/th>\n<\/tr>\n
addVMMetaDataListener<\/code><\/td>\n VM Meta Data arrives from Core (arbitrary bidirectional communication)<\/td>\n<\/tr>\n
addNewGridScriptResultListener<\/code><\/td>\n GridScript command execution results are returned<\/td>\n<\/tr>\n
addNewTerminalDataListener<\/code><\/td>\n Terminal output data arrives from a decentralized thread<\/td>\n<\/tr>\n
addNewDFSMsgListener<\/code><\/td>\n Decentralized File System messages (commit results, etc.)<\/td>\n<\/tr>\n
addVMStateChangedListener<\/code><\/td>\n The decentralized VM transitions to a new state<\/td>\n<\/tr>\n
addConnectionStatusChangedListener<\/code><\/td>\n WebSocket connection state changes (connected, disconnected, etc.)<\/td>\n<\/tr>\n
addNewKeyBlockListener<\/code><\/td>\n A new Key Block is appended to the chain (PoW leader election)<\/td>\n<\/tr>\n
addNewDataBlockListener<\/code><\/td>\n A new Data Block is appended (transactions confirmed)<\/td>\n<\/tr>\n
addUserActionRequestListener<\/code><\/td>\n The platform needs user interaction (password prompt, confirmation, etc.)<\/td>\n<\/tr>\n
addUserLogonListener<\/code><\/td>\n A user session is established (login completed)<\/td>\n<\/tr>\n
addNewConsensusActionListener<\/code><\/td>\n Thread updates and consensus notifications<\/td>\n<\/tr>\n
addSessionKeyAvailableListener<\/code><\/td>\n Encrypted session key is established with the full node<\/td>\n<\/tr>\n
addVMCommitStateChangedListener<\/code><\/td>\n Commit state transitions (prePending, pending, success, aborted)<\/td>\n<\/tr>\n
addOperationStatusListener<\/code><\/td>\n Generic operation status updates<\/td>\n<\/tr>\n<\/table>\nPhase 3: Thread Binding \u2014 Connecting to a Decentralized Thread<\/h3>\nMany dApps need a dedicated decentralized thread \u2014 a live execution context on a GRIDNET Core full node. The Terminal dApp, for example, sets its thread ID early:<\/p>\n
\nthis.setThreadID = 'XTERM_THREAD_' + this.getProcessID;\n<\/pre>\nThe CWindow<\/code> base class manages thread ownership through mMainThreadID<\/code>. If your dApp owns a thread (mInstanceOwnsThread = true<\/code>), closing the window will automatically free the thread via CVMContext.freeThread()<\/code>. If multiple dApps share a thread, the reference-counting system in CProcess<\/code>\/CThread<\/code> ensures the thread is only freed when the last consumer disconnects.<\/p>\n
Phase 4: Active Operation<\/h3>\nOnce initialized, your dApp receives events through the registered listeners and communicates with GRIDNET Core by sending VM Meta Data messages. This active phase continues until the user closes the window.During this phase, your dApp may:<\/p>\n
\nSend GridScript commands to be executed on the blockchain VM<\/li>\n
Submit pre-compiled transactions for processing<\/li>\n
Query blockchain state (balances, domains, transactions)<\/li>\n
Respond to user action requests from the platform<\/li>\n
Create local JS threads for periodic background tasks<\/li>\n<\/ul>\nPhase 5: Cleanup \u2014 closeWindow and destroyWindow<\/h3>\nWhen the user clicks the close button, the platform calls closeWindow()<\/code>:<\/p>\n
\n\/\/ From window.js \u2014 the cleanup sequence\ncloseWindow(shutdownThreads = true, forceShutdownThreads = false) {\n    \/\/ 1. Disconnect the mutation observer\n    this.mObserver.disconnect();\n\n    \/\/ 2. Stop any local JS processing threads\n    if (this.mProcessingQueue > 0)\n        CVMContext.getInstance().stopJSThread(this.mProcessingQueue);\n\n    \/\/ 3. Play close sound and animate window out\n    this.mVMContext.playSound(eSound.close);\n    \/\/ ... animation code ...\n\n    \/\/ 4. Schedule DOM destruction\n    setTimeout(this.destroyWindow.bind(this), 400);\n\n    \/\/ 5. Free the main decentralized thread if owned\n    if (this.getThreadID.byteLength && shutdownThreads && this.mInstanceOwnsThread) {\n        let thread = this.getThreadByID(this.getThreadID);\n        if (thread && (!thread.mHasDataCommitPending || forceShutdownThreads)) {\n            this.mVMContext.freeThread(this.getThreadID, this.getProcessID);\n        }\n    }\n\n    \/\/ 6. Free additional threads\n    for (let i = 0; i < threads.length && shutdownThreads; i++) {\n        \/\/ ... reference counting and conditional free ...\n    }\n}\n<\/pre>\nThen destroyWindow()<\/code> completes the cleanup:<\/p>\n
\ndestroyWindow() {\n    this.mDiv.style.display = \"none\";\n    let windowHandle = this.mDiv;\n\n    \/\/ Unregister from WebRTC swarms\n    this.mVMContext.getSwarmsManager.unregisterProcessFromSwarms(this.getProcessID);\n\n    \/\/ Remove ALL event listeners registered by this dApp\n    this.mVMContext.unregisterEventListenersByAppID(this.mID);\n\n    \/\/ Unregister from the window manager\n    gWindowManager.unregisterWindow(this);\n\n    \/\/ Update visibility state\n    this.mVisibilityState = eWindowVisibilityState.closed;\n\n    \/\/ Remove DOM element\n    windowHandle.remove();\n\n    \/\/ Clean up mouse event listeners\n    window.removeEventListener('mousemove', this.mMouseCallback1);\n    window.removeEventListener('mouseup', this.mMouseCallback2);\n\n    \/\/ Notify window manager of destruction\n    gWindowManager.onWindowDestroyed(this);\n}\n<\/pre>\nThe key method is unregisterEventListenersByAppID(this.mID)<\/code>. It iterates through every notification listener array and removes entries whose appID<\/code> matches your window ID:<\/p>\n
\n\/\/ From VMContext.js \u2014 automatic listener cleanup\nunregisterEventListenersByAppID(appID) {\n    this.mSwarmManager.unregisterEventListenersByAppID(appID);\n\n    for (var i = 0; i < this.mNotificationListeners.length; i++) {\n        for (var a = 0; a < this.mNotificationListeners[i].length; a++) {\n            if (this.mNotificationListeners[i][a].appID == appID) {\n                this.mNotificationListeners[i].splice(a, 1); \/\/ Remove exactly one element\n                a--; \/\/ Adjust index after removal\n            }\n        }\n    }\n}\n\/\/ Note: The sibling method unregisterEventListenerByID() follows the same\n\/\/ pattern and correctly uses splice(a, 1) to remove a single element.\n<\/pre>\nThis is why passing this.mID<\/code> as the appID<\/code> during listener registration is not optional \u2014 it enables automatic garbage collection of your callbacks.<\/p>\n
III. Communication Patterns \u2014 How the Browser Talks to the Blockchain<\/h2>\nThe VM Meta Data Protocol enables structured, BER-encoded bidirectional communication between your browser-based dApp and the GRIDNET Core full node.<\/figcaption><\/figure>\nThe most fundamental question for any dApp developer is: “How does my JavaScript in the browser communicate with the decentralized virtual machine running on GRIDNET Core?” The answer involves three layers: WebSocket transport, BER encoding, and the VM Meta Data Protocol.<\/p>\n
Layer 1: WebSocket Transport<\/h3>\nGRIDNET Core exposes a WebSocket endpoint that the browser connects to. The CVMContext<\/code> singleton manages this connection:<\/p>\n
\n\/\/ From VMContext.js \u2014 establishing the WebSocket connection\nthis.mWebSocket = new WebSocket(nodeURI);\nthis.mWebSocket.binaryType = \"arraybuffer\";\n\nthis.mWebSocket.onopen = this.mOnSocketOpenBoundEvent;\nthis.mWebSocket.onclose = this.mOnSocketCloseBoundEvent;\nthis.mWebSocket.onmessage = this.mOnMessageBoundEvent;\nthis.mWebSocket.onerror = this.mOnErrorBoundEvent;\n<\/pre>\nKey details:<\/p>\n
\nBinary mode.<\/strong> The socket uses binaryType = \"arraybuffer\"<\/code> \u2014 all communication is binary, not text. This is essential because the protocol uses BER encoding.<\/li>\n
Automatic reconnection.<\/strong> CVMContext<\/code> has a controller routine that monitors connection health and automatically reconnects if the connection drops.<\/li>\n
Session encryption.<\/strong> After the initial handshake, the platform establishes encrypted sessions using X25519 key exchange and ChaCha20 encryption. The mSessionKey<\/code>, mEphKeyPair<\/code>, and AEAD configuration control this.<\/li>\n
Connection state tracking.<\/strong> The platform tracks eConnectionState<\/code> (disconnected, connecting, connected) and notifies all registered ConnectionStatusChangedListeners<\/code> on transitions.<\/li>\n<\/ul>\nLayer 2: BER Encoding \u2014 The Wire Format<\/h3>\nAll data exchanged between browser and Core uses BER (Basic Encoding Rules)<\/strong> from the ASN.1 standard. This is the same encoding used in X.509 certificates, LDAP, and SNMP. GRIDNET chose BER because it provides:<\/p>\n
\nSchema-less flexibility.<\/strong> Unlike Protocol Buffers or Cap’n Proto, BER does not require pre-compiled schemas. This allows the protocol to evolve without breaking compatibility.<\/li>\n
Nested structure.<\/strong> BER naturally supports nested SEQUENCE and SET structures, which map directly to the hierarchical VM Meta Data format.<\/li>\n
Binary efficiency.<\/strong> No JSON overhead, no base64 bloat. Binary values are transmitted as raw bytes.<\/li>\n<\/ul>\nThe platform includes a dedicated BERDecoderProxy<\/code> that offloads expensive ASN.1 parsing to a Web Worker, preventing the main thread from blocking:<\/p>\n
\n\/\/ From BERDecoderProxy.js \u2014 offloading parsing to a Web Worker\nthis.worker = new Worker('\/lib\/BERDecoderWorker.js', { type: 'module' });\n<\/pre>\nThis is a critical performance optimization. BER decoding of complex structures (like search results containing hundreds of transactions) can take significant CPU time. By running it in a Web Worker, your UI remains responsive.<\/p>\n
Layer 3: The VM Meta Data Protocol<\/h3>\nThe VM Meta Data Protocol is the application-level protocol built on top of BER encoding. It organizes communication into Sections<\/strong> and Entries<\/strong>.A Section<\/strong> (CVMMetaSection<\/code>) represents a category of communication:<\/p>\n
\nclass CVMMetaSection {\n    constructor(eType, version = 1) {\n        this.mType = eType;      \/\/ eVMMetaSectionType enum\n        this.mVersion = version;\n        this.mEntries = [];       \/\/ Array of CVMMetaEntry\n        this.mMetaData = new ArrayBuffer();  \/\/ Optional section-level metadata\n    }\n}\n<\/pre>\nSection types include:<\/p>\n
\neVMMetaSectionType.requests<\/code> \u2014 Outgoing requests to the VM (GridScript commands, data queries)<\/li>\n
eVMMetaSectionType.notifications<\/code> \u2014 Bidirectional notifications (terminal data, state changes)<\/li>\n
eVMMetaSectionType.stateLessChannels<\/code> \u2014 Off-chain payment channel operations<\/li>\n<\/ul>\nAn Entry<\/strong> (CVMMetaEntry<\/code>) is a single operation within a section:<\/p>\n
\nclass CVMMetaEntry {\n    constructor(eType, reqID, dataFields = [], processID = 0, vmID = new ArrayBuffer()) {\n        this.mType = eType;          \/\/ eVMMetaEntryType enum\n        this.mReqID = reqID;         \/\/ Unique request identifier\n        this.mProcessID = processID; \/\/ Originating dApp process ID\n        this.mDataFields = dataFields; \/\/ Array of typed data fields\n        this.mVMID = vmID;           \/\/ Target VM\/Thread ID\n    }\n}\n<\/pre>\nEntry types include:<\/p>\n
\neVMMetaEntryType.GridScriptCode<\/code> \u2014 A GridScript command to execute<\/li>\n
eVMMetaEntryType.terminalData<\/code> \u2014 Terminal input\/output\/resize data<\/li>\n
eVMMetaEntryType.dataRequest<\/code> \u2014 A structured data request<\/li>\n
eVMMetaEntryType.dataResponse<\/code> \u2014 Response to a user-action request<\/li>\n
eVMMetaEntryType.preCompiledTransaction<\/code> \u2014 A locally-compiled transaction<\/li>\n<\/ul>\nSending a Command: The Full Flow<\/h3>\nHere is the complete flow when your dApp sends a GridScript command:<\/p>\n
\n\/\/ Step 1: Create a meta generator\nlet metaGen = new CVMMetaGenerator();\n\n\/\/ Step 2: Add a GridScript command\nlet reqID = metaGen.addRAWGridScriptCmd(\n    \"balance GNC\",                    \/\/ The GridScript command\n    eVMMetaCodeExecutionMode.RAW,     \/\/ Execution mode (RAW or GUI)\n    0,                                 \/\/ reqID (0 = auto-generate)\n    0,                                 \/\/ Window ID\n    this.getProcessID,                 \/\/ Process ID\n    this.getSystemThreadID             \/\/ Target thread ID\n);\n\n\/\/ Step 3: Serialize to BER-encoded bytes\nlet bytes = metaGen.getPackedData();\n\n\/\/ Step 4: Wrap in a network message\nlet msg = new CNetMsg(\n    eNetEntType.VMMetaData,   \/\/ Message entity type\n    eNetReqType.process,      \/\/ Request type\n    bytes                     \/\/ BER-encoded payload\n);\n\n\/\/ Step 5: Send over the WebSocket\nCVMContext.getInstance().sendNetMsg(msg);\n<\/pre>\nThe response arrives asynchronously through your registered VMMetaDataListener<\/code> or GridScriptResultListener<\/code>, correlated by the reqID<\/code>.<\/p>\n
CNetMsg \u2014 The Network Message Wrapper<\/h3>\nEvery message sent over the WebSocket is wrapped in a CNetMsg<\/code>:<\/p>\n
\nlet msg = new CNetMsg(eNetEntType.VMMetaData, eNetReqType.process, data);\nmsg.setDestinationType = eEndpointType.VM;  \/\/ Destination is the VM\nmsg.setDestination = threadID;               \/\/ Specific thread to target\n<\/pre>\nThe sendNetMsg()<\/code> method in CVMContext<\/code> handles authentication, encryption (if a session key is established), commit-state checks, and transmission. Internally, the actual WebSocket write is delegated to sendBinary()<\/code>, which performs the connection-state safety checks:<\/p>\n
\n\/\/ From VMContext.js \u2014 the two-method send chain (simplified)\nsendNetMsg(msg, breakCommit = false, UINotifyOnError = false, doPreProcessing = true) {\n    \/\/ 1. Authentication and encryption (if doPreProcessing)\n    \/\/ 2. Commit-state checks (can this message break a pending commit?)\n    \/\/ 3. Serialize and delegate to sendBinary()\n    var serializedNetMsg = msg.getPackedData();\n    return this.sendBinary(serializedNetMsg);\n}\n\nsendBinary(message) {\n    if (!this.mWebSocket) return false;\n    if (this.mWebSocket.readyState !== WebSocket.OPEN) return false;\n    this.mWebSocket.send(message);\n    return true;\n}\n<\/pre>\nPre-Compiled Transactions \u2014 The Local Path<\/h3>\nFor value transfers and smart contract operations, GRIDNET OS supports local transaction compilation<\/strong>. Instead of sending raw GridScript text to the Core for compilation, your dApp can compile transactions locally using the GridScriptCompiler<\/code> and CTransaction<\/code> classes:<\/p>\n
\n\/\/ From MetaData.js \u2014 adding a pre-compiled transaction\naddPreCompiledTransaction(txData, reqID = 0, processID = 0, vmID = new ArrayBuffer()) {\n    let section = new CVMMetaSection(eVMMetaSectionType.requests);\n    let dataFields = [];\n    dataFields.push(gTools.convertToArrayBuffer(txData));\n\n    let entry = new CVMMetaEntry(\n        eVMMetaEntryType.preCompiledTransaction, reqID, dataFields, processID, vmID\n    );\n    section.addEntry(entry);\n    return reqID;\n}\n<\/pre>\nLocal compilation is trustless \u2014 the full node validates the transaction bytecode against the same rules regardless of where it was compiled. The Wallet dApp uses this extensively for value transfers, providing a faster user experience since compilation happens instantly in the browser rather than waiting for a round-trip to the Core.<\/p>\n
IV. State Management \u2014 Tracking the Blockchain<\/h2>\ndApps track blockchain state through subscriptions, cached queries, and event-driven updates \u2014 the platform manages the complexity of keeping your view synchronized with global consensus.<\/figcaption><\/figure>\nBlockchain state is fundamentally different from traditional application state. It is global (shared across all nodes), eventually consistent (blocks take time to propagate), and immutable once confirmed. Your dApp must be designed to handle these realities.<\/p>\n
The Request\/Response Model<\/h3>\nAll blockchain queries follow an asynchronous request\/response pattern mediated by request IDs:<\/p>\n
\n\/\/ 1. Send a query \u2014 get back a request ID\nlet reqID = metaGen.addRAWGridScriptCmd(\"balance GNC\", eVMMetaCodeExecutionMode.RAW);\n\n\/\/ 2. The response arrives later through your listener\nnewGridScriptResultCallback(result) {\n    \/\/ result contains the reqID for correlation\n    if (result.reqID === this.mPendingBalanceRequestID) {\n        this.updateBalanceDisplay(result);\n    }\n}\n<\/pre>\nThis is event-driven architecture at its core. Your dApp sends a request, stores the reqID<\/code>, and matches it when the response arrives. There is no blocking. There are no Promises wrapping synchronous operations. The decentralized world is inherently asynchronous, and the architecture embraces this.<\/p>\n
Blockchain Explorer API \u2014 Structured Queries<\/h3>\nFor common blockchain queries, the CVMContext<\/code> provides a higher-level API with structured request tracking:<\/p>\n
\n\/\/ From VMContext.js \u2014 pending request infrastructure\nthis.mPendingRequests = new Map(); \/\/ Maps request IDs to {resolve, reject, type, timer}\nthis.mCachedHeight = undefined;\nthis.mCachedKeyHeight = undefined;\nthis.mCachedHeightTimestamp = 0;\n<\/pre>\nThe caching layer prevents redundant queries. Block height, for example, is cached with a timestamp and only re-fetched when stale.<\/p>\n
Subscription-Based Updates<\/h3>\nFor data that changes over time (new blocks, transaction confirmations), the platform supports subscription-based updates:<\/p>\n
\n\/\/ From VMContext.js \u2014 subscription infrastructure\nthis.mBlockchainSubscriptionThread = 0;\nthis.mBlockchainSubscriptionActive = false;\nthis.mBlockchainSubscriptions = [];\nthis.mBlockchainUpdateHandlers = [];\n<\/pre>\nWhen you register a NewKeyBlockListener<\/code> or NewDataBlockListener<\/code>, you receive automatic notifications whenever the chain advances. This is how the Wallet dApp keeps its balance display current without polling.<\/p>\n
State Domain Management<\/h3>\nGRIDNET OS organizes blockchain state into State Domains<\/strong> \u2014 analogous to user accounts or namespaces. Each domain has:<\/p>\n
\nA unique identifier (the domain ID)<\/li>\n
A balance (in GNC, the native currency)<\/li>\n
An owner (public key)<\/li>\n
ACL (Access Control Lists) for fine-grained permissions<\/li>\n
A directory structure (like a filesystem) for storing data<\/li>\n<\/ul>\nYour dApp tracks the current state domain through CVMContext<\/code>:<\/p>\n
\n\/\/ Accessing state domain information\nlet domainID = CVMContext.getInstance().mStateDomainID;\n<\/pre>\nDouble-Buffering Pattern<\/h3>\nThe GRIDNET Core uses double-buffering for state management internally \u2014 maintaining both a “committed” state and a “working” state for pending modifications. The CStateDomainManager<\/code> in the Core manages this, and the browser-side reflects it through the commit state machine:<\/p>\n
\n\/\/ Commit states visible to your dApp\n\/\/ eCommitState.none      \u2014 No commit in progress\n\/\/ eCommitState.prePending \u2014 Commit lock acquired, preparing\n\/\/ eCommitState.pending    \u2014 Commit submitted, awaiting consensus\n\/\/ eCommitState.aborted    \u2014 Commit was aborted\n\/\/ eCommitState.success    \u2014 Commit confirmed on-chain\n<\/pre>\nThe commit state automatically resets to none<\/code> after terminal states (aborted\/success), and notifications are dispatched for each transition. Your dApp listens via addVMCommitStateChangedListener<\/code>.<\/p>\n
V. Multi-Instance Architecture \u2014 Running Multiple Copies<\/h2>\nGRIDNET OS supports multiple simultaneous instances of the same dApp, each with its own process ID, listeners, and scoped state \u2014 no globals, no collisions.<\/figcaption><\/figure>\nUnlike traditional web applications where there is one instance of your code in one page, GRIDNET OS allows users to open multiple instances of the same dApp simultaneously. Two Wallet windows. Three Terminal sessions. Each must function independently.<\/p>\n
How It Works: Process IDs<\/h3>\nEvery dApp instance receives a unique process ID from the platform:<\/p>\n
\n\/\/ From CWindow constructor\nthis.mProcessID = this.mVMContext.getNewProcessID();\nthis.mID = (\"window_\" + this.mProcessID);\n<\/pre>\nThe internal counter starts at 1000 and increments before returning, so the first user-mode process ID is 1001. IDs below 1000 are reserved for kernel-mode processes. This ID becomes the namespace for everything the instance owns:<\/p>\n
\nEvent listeners<\/strong> are tagged with this.mID<\/code> (which includes the process ID), enabling per-instance cleanup.<\/li>\n
Thread ownership<\/strong> is tracked per process. Each instance can own its own decentralized thread.<\/li>\n
DOM elements<\/strong> live in isolated Shadow DOMs (or at minimum, scoped by window ID).<\/li>\n
Settings<\/strong> can be per-instance through the CSettingsManager<\/code>.<\/li>\n<\/ul>\nThe No-Globals Rule<\/h3>\nFor multi-instance architecture to work, your dApp must avoid global state. Consider the Terminal dApp’s approach:<\/p>\n
\nclass CTerminal extends CWindow {\n    constructor(...) {\n        super(...);\n        \/\/ ALL state is instance properties \u2014 never module-level variables\n        this.mLastHeightRearangedAt = 0;\n        this.mThreadActive = false;\n        this.mDomainID = \"\";\n        this.mERGBig = 0;\n        this.mBalance = '0';\n        this.mFitAddon = null;\n        \/\/ ...\n    }\n}\n<\/pre>\nEvery piece of state is stored as this.something<\/code> \u2014 an instance property. There are no module-level let<\/code> or var<\/code> declarations holding application state (the terminalBody<\/code> template string is a read-only constant, which is safe to share).The Wallet dApp follows the same pattern across thousands of lines of code \u2014 all mutable state lives on this<\/code>.<\/p>\n
Package IDs \u2014 Static Identity<\/h3>\nWhile process IDs are unique per instance, every dApp class also has a static getPackageID()<\/code> method that identifies the dApp type:<\/p>\n
\nstatic getPackageID() {\n    return \"org.gridnetproject.UIdApps.terminal\";\n}\n<\/pre>\nThis is used for package management, settings namespacing, and identifying which dApp type is running \u2014 not for instance identification.<\/p>\n
Thread Sharing Between Instances<\/h3>\nWhen multiple instances need to interact with the same decentralized thread, the platform’s reference-counting system manages thread lifetime:<\/p>\n
\n\/\/ From closeWindow \u2014 conditional thread release\nif (!thread.getUsedByCount && (!thread.mHasDataCommitPending || forceShutdownThreads)) {\n    this.mVMContext.freeThread(threads[i].getID, this.getProcessID);\n}\n<\/pre>\nA thread is only freed when the last process using it disconnects. This prevents one instance from killing a shared thread that another instance still needs.<\/p>\n
VI. Error Handling Patterns \u2014 What Breaks and How to Recover<\/h2>\nDefensive coding patterns protect your dApp from the unique failure modes of a decentralized environment \u2014 network drops, thread failures, and consensus timeouts.<\/figcaption><\/figure>\nBuilding on a decentralized platform introduces failure modes that do not exist in traditional web development. The full node may disconnect. A GridScript command may run out of ERG (computational gas). A commit may be rejected by consensus. Your dApp must handle all of these gracefully.<\/p>\n
Connection Loss and Recovery<\/h3>\nThe WebSocket connection can drop at any time. The platform handles reconnection automatically, but your dApp must handle the UI implications:<\/p>\n
\n\/\/ Register for connection state changes\nCVMContext.getInstance().addConnectionStatusChangedListener(\n    this.onConnectionChanged.bind(this), this.mID\n);\n\n\/\/ Handle state transitions\nonConnectionChanged(state) {\n    switch(state) {\n        case eConnectionState.disconnected:\n            this.showOfflineIndicator();\n            this.disableTransactionForms();\n            break;\n        case eConnectionState.connecting:\n            this.showReconnectingIndicator();\n            break;\n        case eConnectionState.connected:\n            this.hideOfflineIndicator();\n            this.enableTransactionForms();\n            this.refreshState(); \/\/ Re-query blockchain state\n            break;\n    }\n}\n<\/pre>\nCritical pattern:<\/strong> After reconnection, you must re-query any blockchain state your dApp displays. The world may have changed while you were disconnected. Balances may have shifted. Transactions may have confirmed. Never assume cached state is still valid after a reconnect.<\/p>\n
sendNetMsg Failure Handling<\/h3>\nThe sendNetMsg()<\/code> method returns false<\/code> if the message cannot be sent (WebSocket closed, null reference, etc.):<\/p>\n
\nif (!CVMContext.getInstance().sendNetMsg(msg)) {\n    \/\/ Message was NOT sent \u2014 handle gracefully\n    this.showNotification('error', 'Message delivery failed',\n        'Unable to communicate with the network. Please wait for reconnection.');\n    return;\n}\n<\/pre>\nNever assume sendNetMsg<\/code> succeeds. Always check the return value.<\/p>\n
Request Timeout Pattern<\/h3>\nResponses from the blockchain may never arrive (network partition, node crash). Implement timeout patterns for critical operations:<\/p>\n
\n\/\/ The platform provides built-in timeout support for UI tasks\nCVMContext.getInstance().registerLocalUIResponseCallback(\n    reqID,\n    this.getProcessID,\n    (response) => { \/* success handler *\/ },\n    (error) => { \/* timeout\/cancel handler *\/ },\n    60000  \/\/ 60-second timeout\n);\n<\/pre>\nFor your own request tracking, implement similar patterns:<\/p>\n
\nsendBalanceQuery() {\n    let reqID = \/* ... send the query ... *\/;\n    this.mPendingBalanceReqID = reqID;\n\n    \/\/ Set a timeout\n    this.mBalanceTimeout = setTimeout(() => {\n        if (this.mPendingBalanceReqID === reqID) {\n            this.mPendingBalanceReqID = null;\n            this.showBalanceError('Query timed out');\n        }\n    }, 30000);\n}\n\nonBalanceResult(result) {\n    if (result.reqID === this.mPendingBalanceReqID) {\n        clearTimeout(this.mBalanceTimeout);\n        this.mPendingBalanceReqID = null;\n        this.updateBalance(result);\n    }\n}\n<\/pre>\nCommit State Error Handling<\/h3>\nCommit operations (writing to the blockchain) can fail at multiple stages:<\/p>\n
\nCVMContext.getInstance().addVMCommitStateChangedListener(\n    this.onCommitStateChanged.bind(this), this.mID\n);\n\nonCommitStateChanged(state) {\n    switch(state) {\n        case eCommitState.prePending:\n            this.showCommitProgress('Preparing commit...');\n            break;\n        case eCommitState.pending:\n            this.showCommitProgress('Awaiting consensus...');\n            break;\n        case eCommitState.success:\n            this.showCommitSuccess();\n            this.refreshState();\n            break;\n        case eCommitState.aborted:\n            this.showCommitError('Commit was aborted. The transaction may have been rejected.');\n            break;\n    }\n}\n<\/pre>\nThe Curtain as a Safety Net<\/h3>\nRemember the mutation observer from Section I? It serves as an automatic error recovery mechanism. If your dApp’s DOM gets into a heavy mutation storm (perhaps due to an error in a rendering loop), the curtain activates automatically, preventing the user from interacting with a broken interface:<\/p>\n
\n\/\/ The platform calculates mutation rate\n\/\/ If mutations exceed mCurtainThreshold within mObsTimeWindow:\nthis.showCurtain(true, false, false, 'High mutation rate detected');\n\n\/\/ Once mutations settle, the curtain hides automatically\nawait this.waitTillUIResponsive();\nthis.hideCurtain();\n<\/pre>\nDefensive BigInt Handling<\/h3>\nGRIDNET OS uses BigInt<\/code> extensively for cryptocurrency values (balances, transfer amounts, ERG costs). Common pitfall:<\/p>\n
\n\/\/ WRONG \u2014 will throw TypeError\nlet balance = someValue + 100;\n\n\/\/ RIGHT \u2014 BigInt arithmetic requires BigInt operands\nlet balance = BigInt(someValue) + BigInt(100);\n\n\/\/ Also watch for comparisons\nif (this.mPendingTotalValueTransfer >= BigInt(value)) {\n    this.mPendingTotalValueTransfer -= BigInt(value);\n}\n<\/pre>\nThe platform uses BigInt<\/code> wrappers consistently, as seen in CVMContext<\/code>:<\/p>\n
\nincTotalPendingOutgressTransfer(value) {\n    this.mPendingTotalValueTransfer += BigInt(value);\n}\n<\/pre>\nVII. Security Model \u2014 What the Sandbox Gives You<\/h2>\nMultiple defense layers \u2014 Shadow DOM isolation, encrypted transport, cryptographic authentication, and the GridScript kernel\/user-mode separation \u2014 protect both your dApp and the platform.<\/figcaption><\/figure>\nThe security architecture of GRIDNET OS UI dApps operates at multiple levels. Understanding each level helps you build dApps that are secure by default and hardened by design.<\/p>\n
Layer 1: Shadow DOM Isolation (Browser Level)<\/h3>\nAs covered in Section I, the Shadow DOM provides:<\/p>\n
\nCSS isolation \u2014 no style bleed in or out<\/li>\n
DOM isolation \u2014 no external querySelector access<\/li>\n
Event retargeting \u2014 internal structure not discoverable via events<\/li>\n<\/ul>\nThis is your first line of defense against cross-dApp interference.<\/p>\n
Layer 2: Process Isolation (Platform Level)<\/h3>\nEach dApp instance runs as a separate process with:<\/p>\n
\nA unique process ID<\/li>\n
Scoped event listeners (automatically cleaned up)<\/li>\n
Independent thread ownership<\/li>\n
Separate request tracking<\/li>\n<\/ul>\nThe CProcess<\/code> class in the platform tracks which threads and resources belong to each dApp. When a dApp closes, all its resources are reclaimed.<\/p>\n
Layer 3: Encrypted Transport (Network Level)<\/h3>\nCommunication between browser and Core is encrypted:<\/p>\n
\n\/\/ From VMContext.js constructor \u2014 security configuration\nthis.mUseAEADForAuth = false;\nthis.mUseAEADForSessionKey = false;\nthis.mSignOutgressMsgs = false;\nthis.mAuthenticateHello = true;\nthis.mEncryptionRequired = true;\n<\/pre>\nThe platform uses:<\/p>\n
\nX25519 key exchange<\/strong> for establishing shared secrets<\/li>\n
ChaCha20<\/strong> for session encryption<\/li>\n
AEAD (Authenticated Encryption with Associated Data)<\/strong> optional for authenticated sessions<\/li>\n
Ephemeral key pairs<\/strong> generated fresh each session (mEphKeyPair<\/code>)<\/li>\n<\/ul>\nLayer 4: GridScript Kernel\/User Mode (VM Level)<\/h3>\nGridScript codewords are categorized as kernel-mode or non-kernel-mode. The GridScriptCompiler.js<\/code> explicitly tracks this:<\/p>\n
\n\/\/ From GridScriptCompiler.js \u2014 codeword definitions\n\/\/ Format: [name, allowedInKernelMode, inlineParams, hasBase58, hasBase64]\n['BT', false, 0, false, false],    \/\/ Begin Transaction \u2014 NON-KERNEL\n['CT', false, 0, false, false],    \/\/ Commit Transaction \u2014 NON-KERNEL\n['send', true, 2, false, false],   \/\/ Send value \u2014 KERNEL\n['balance', true, 1, false, false], \/\/ Query balance \u2014 KERNEL\n<\/pre>\nCodewords marked allowedInKernelMode = true<\/code> (like send<\/code> and balance<\/code>) are included in the kernel-mode compiler \u2014 they can execute within the VM’s computational sandbox. Codewords marked false<\/code> (like BT<\/code>\/Begin Transaction and CT<\/code>\/Commit Transaction) are excluded from the kernel-mode compiler and can only be invoked at the full-node administrative level. This separation prevents sandboxed code from directly triggering top-level state-modifying operations without proper authorization.<\/p>\n
Layer 5: Clipboard Isolation<\/h3>\nEven clipboard operations are Shadow DOM-aware. The CWindow<\/code> base class provides isolated clipboard methods:<\/p>\n
\n\/\/ Copy text using the modern Clipboard API or fallback\ncopyTextToClipboard(text) {\n    if (navigator.clipboard && navigator.clipboard.writeText) {\n        navigator.clipboard.writeText(text);\n        return true;\n    }\n    \/\/ Fallback for environments without Clipboard API\n    const textarea = document.createElement(\"textarea\");\n    textarea.value = text;\n    textarea.style.position = \"fixed\";\n    textarea.style.left = \"-9999px\";\n    document.body.appendChild(textarea);\n    textarea.select();\n    const success = document.execCommand(\"copy\");\n    document.body.removeChild(textarea);\n    return success;\n}\n<\/pre>\nAnd for reading content from within Shadow DOM:<\/p>\n
\ncopySelectedTextToClipboard() {\n    if (this.getUseShadowDOM) {\n        const body = this.getBody;\n        if (body && body.shadowRoot) {\n            const selection = body.shadowRoot.getSelection?.() || window.getSelection();\n            \/\/ ...\n        }\n    }\n}\n<\/pre>\nLayer 6: DOMPurify Integration<\/h3>\nThe platform includes the purify.js<\/code> library (DOMPurify) in its standard library. Any user-generated content injected into the DOM should be sanitized:<\/p>\n
\n\/\/ Always sanitize external content before injection\nelement.innerHTML = DOMPurify.sanitize(untrustedContent);\n<\/pre>\nVIII. Real Production Patterns \u2014 Annotated Code from Wallet, Terminal, and Messenger<\/h2>\nThe Wallet, Terminal, and Messenger dApps demonstrate production-grade patterns for building on GRIDNET OS \u2014 from complex state management to real-time bidirectional communication.<\/figcaption><\/figure>\nTheory is necessary but insufficient. Let us examine how three production dApps \u2014 each with different requirements \u2014 implement the patterns described above.<\/p>\n
Pattern 1: The Wallet \u2014 Complex State with Local Transaction Compilation<\/h3>\nThe Wallet (wallet.js<\/code>) is the most complex UI dApp in GRIDNET OS. It demonstrates:Extensive library imports (abbreviated \u2014 the Wallet also imports enums, search filters, GLink handlers, drag\/drop utilities, and more):<\/strong><\/p>\n
\n\/\/ wallet.js imports \u2014 key dependencies\nimport { CConsensusTask } from \"\/lib\/VMContext.js\"\nimport { CVMMetaSection, CVMMetaEntry, CVMMetaGenerator, CVMMetaParser } from '\/lib\/MetaData.js'\nimport { CBlockDesc } from '\/lib\/BlockDesc.js'\nimport { CTransactionDesc } from '\/lib\/TransactionDesc.js'\nimport { CDomainDesc } from '\/lib\/DomainDesc.js'\nimport { CIdentityToken } from '\/lib\/IdentityToken.js'\nimport { CTransaction } from '\/lib\/Transaction.js'\nimport { GridScriptCompiler } from '\/lib\/GridScriptCompiler.js'\nimport { CStateLessChannelsManager, CTokenPoolBank, CTokenPool } from \"\/lib\/StateLessChannels.js\"\nimport { CWindow } from \"\/lib\/window.js\"\nimport { CAppSettings, CSettingsManager } from '\/lib\/SettingsManager.js'\n<\/pre>\nKey patterns:<\/strong><\/p>\n
\nLocal transaction compilation.<\/strong> The Wallet imports GridScriptCompiler<\/code> and CTransaction<\/code> to build and sign transactions entirely in the browser, without sending source code to the full node.<\/li>\n
State-Less Channels.<\/strong> For off-chain micropayments, the Wallet uses CStateLessChannelsManager<\/code> \u2014 a sophisticated protocol for instant, zero-fee token transfers.<\/li>\n
Rich UI with Shadow DOM.<\/strong> The Wallet’s HTML template includes complete CSS (thousands of lines of cyberpunk-styled components), all encapsulated within the Shadow DOM.<\/li>\n
Thumbnail management.<\/strong> During heavy operations (loading transaction history), the Wallet pauses thumbnail generation platform-wide to preserve performance: CWindow.pauseThumbnailGeneration()<\/code>.<\/li>\n<\/ul>\nPattern 2: The Terminal \u2014 Real-Time Bidirectional Streaming<\/h3>\nThe Terminal (Terminal.js<\/code>) demonstrates the leanest dApp pattern \u2014 a real-time, bidirectional text stream with the blockchain VM:<\/p>\n
\nclass CTerminal extends CWindow {\n    constructor(positionX, positionY, width, height) {\n        super(positionX, positionY, width, height,\n              terminalBody, \"Terminal\", CTerminal.getIcon(), false);\n\n        \/\/ Disable vertical scroll (xterm handles its own)\n        this.disableVerticalScroll();\n\n        \/\/ Instance state \u2014 no globals\n        this.mThreadActive = false;\n        this.mDomainID = \"\";\n        this.mBalance = '0';\n        this.mFitAddon = null;\n\n        \/\/ Register for ALL relevant events\n        CVMContext.getInstance().addVMMetaDataListener(\n            this.newVMMetaDataCallback.bind(this), this.mID);\n        CVMContext.getInstance().addNewDFSMsgListener(\n            this.newDFSMsgCallback.bind(this), this.mID);\n        CVMContext.getInstance().addNewGridScriptResultListener(\n            this.newGridScriptResultCallback.bind(this), this.mID);\n        CVMContext.getInstance().addNewTerminalDataListener(\n            this.newTerminalDataCallback.bind(this), this.mID);\n        CVMContext.getInstance().addVMStateChangedListener(\n            this.VMStateChangedCallback.bind(this), this.mID);\n\n        \/\/ Load persisted settings\n        this.loadLocalData();\n\n        \/\/ Key mapping \u2014 JavaScript keycodes to SSH keycodes\n        this.mSpecialKeys = new Array(37, 38, 39, 40, 8, 13, 127);\n        this.JS_ARROW_UP = 38;\n        this.SSH_ARROW_UP = 65;\n        \/\/ ... more key mappings ...\n\n        CTools.getInstance().logEvent(\n            \"\u22ee\u22ee\u22ee Terminal UI dApp launching..\",\n            eLogEntryCategory.dApp, 1, eLogEntryType.notification, this\n        );\n    }\n\n    static getPackageID() {\n        return \"org.gridnetproject.UIdApps.terminal\";\n    }\n}\n<\/pre>\nKey patterns:<\/strong><\/p>\n
\nTerminal data protocol.<\/strong> Uses addNewTerminalDataListener<\/code> for receiving output and CVMMetaGenerator.addTerminalData()<\/code> for sending input \u2014 a dedicated sub-protocol for terminal I\/O with support for window dimension negotiation.<\/li>\n
Key code translation.<\/strong> Maps JavaScript key events to SSH-compatible key codes, demonstrating how dApps bridge browser APIs to the decentralized VM.<\/li>\n
xterm.js integration.<\/strong> Embeds xterm.js with FitAddon for a fully-functional terminal experience within the window frame.<\/li>\n
Minimal HTML template.<\/strong> The Terminal’s body HTML is remarkably simple \u2014 just a <div id=\"terminal\"><\/div><\/code> with styling. All complexity lives in JavaScript.<\/li>\n<\/ul>\nPattern 3: The Messenger \u2014 Extended CWindow with Rich UI<\/h3>\nThe Messenger (Messenger.js<\/code>) is the largest dApp by code volume, demonstrating how to build a full-featured application:<\/p>\n
\nexport class CMessenger extends CWindow {\n    static getIcon() {\n        \/\/ Returns base64-encoded icon\n    }\n    \/\/ ... 28,000+ lines of rich messaging functionality\n}\n<\/pre>\nKey patterns:<\/strong><\/p>\n
\nWebRTC Swarms.<\/strong> Uses the platform’s CSwarmsManager<\/code> for peer-to-peer real-time messaging via WebRTC, with the blockchain serving as the coordination layer.<\/li>\n
GLink support.<\/strong> The Messenger can be launched via GLinks (GRIDNET deep links) to navigate directly to a conversation or action.<\/li>\n
Complex DOM management.<\/strong> With a rich UI including message lists, contact panels, file sharing, and real-time indicators, the Messenger demonstrates how to manage complex Shadow DOM interactions at scale.<\/li>\n<\/ul>\nCommon Patterns Across All Three<\/h3>\nDespite their differences, all three dApps share these foundational patterns:<\/p>\n
\nExtend CWindow.<\/strong> Every dApp starts with class MyApp extends CWindow<\/code>.<\/li>\n
Call super() first.<\/strong> The base constructor handles platform registration.<\/li>\n
Register listeners with this.mID.<\/strong> Always pass your window ID for automatic cleanup.<\/li>\n
Store all state on this.<\/strong> No module-level mutable state.<\/li>\n
Use static getPackageID().<\/strong> Provides a reverse-DNS identifier for the dApp type.<\/li>\n
Use static getIcon().<\/strong> Returns a base64 icon for the taskbar and window frame.<\/li>\n
Handle connection state changes.<\/strong> React to disconnection and reconnection.<\/li>\n
Use CTools.getInstance().logEvent().<\/strong> Structured logging that integrates with the platform’s event system.<\/li>\n<\/ol>\nIX. Complete Architecture Diagram<\/h2>\nThe following diagram shows the full architectural stack of a GRIDNET OS UI dApp, from the user interface layer down to the blockchain:<\/p>\n
X. The dApp Developer’s Checklist<\/h2>\nTo summarize everything in this article into an actionable checklist:Structure:<\/strong><\/p>\n
\n\u2610 Extend CWindow<\/code> \u2014 it is your foundation<\/li>\n
\u2610 Call super()<\/code> with your HTML template, title, icon, and Shadow DOM preference<\/li>\n
\u2610 Implement static getPackageID()<\/code> with a reverse-DNS identifier<\/li>\n
\u2610 Implement static getIcon()<\/code> returning base64-encoded icon data<\/li>\n<\/ul>\nLifecycle:<\/strong><\/p>\n
\n\u2610 Register listeners in the constructor, after super()<\/code><\/li>\n
\u2610 Always pass this.mID<\/code> as the appID parameter to listener registrations<\/li>\n
\u2610 Store all mutable state as instance properties (this.xxx<\/code>), never as module globals<\/li>\n
\u2610 Trust the platform’s automatic cleanup on closeWindow()<\/code><\/li>\n<\/ul>\nCommunication:<\/strong><\/p>\n
\n\u2610 Use CVMMetaGenerator<\/code> to construct outgoing messages<\/li>\n
\u2610 Track request IDs for correlating responses<\/li>\n
\u2610 Always check sendNetMsg()<\/code> return value<\/li>\n
\u2610 Implement timeout patterns for critical requests<\/li>\n<\/ul>\nSecurity:<\/strong><\/p>\n
\n\u2610 Use Shadow DOM (useShadowDOM = true<\/code>) for CSS and DOM isolation<\/li>\n
\u2610 Sanitize any external content with DOMPurify before DOM injection<\/li>\n
\u2610 Use this.shadowQuery()<\/code> instead of document.querySelector()<\/code><\/li>\n
\u2610 Never expose sensitive data in module-level variables<\/li>\n<\/ul>\nResilience:<\/strong><\/p>\n
\n\u2610 Listen for connection state changes and update UI accordingly<\/li>\n
\u2610 Re-query blockchain state after reconnection<\/li>\n
\u2610 Use BigInt<\/code> for all cryptocurrency values<\/li>\n
\u2610 Handle the curtain \u2014 do not fight it, it protects your users<\/li>\n<\/ul>\nThe architecture of a GRIDNET OS UI dApp is not a cage \u2014 it is an exoskeleton. Every constraint exists to protect you. The Shadow DOM protects your interface. The process model protects your resources. The BER protocol protects your data in transit. The lifecycle hooks protect your users from leaked resources and ghost callbacks. Build within this architecture, and you build something that cannot easily be broken \u2014 by bugs, by other dApps, or by the inherent chaos of a decentralized world.This is Part 3 of the GRIDNET OS UI dApp Developer Series. In the next article, we will build a complete dApp from scratch \u2014 applying every pattern documented here to create a working application you can deploy to the GRIDNET OS ecosystem.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"
Every application you have ever built on the traditional web sits naked in a shared environment. Your JavaScript runs in the same…<\/p>\n","protected":false},"author":1,"featured_media":835491,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[162,17,163],"tags":[166,155,164,197,142,214,167,153,152,212,165],"class_list":["post-835498","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development","category-tutorial","category-tutorials","tag-architecture","tag-cvmcontext","tag-dapp","tag-dapps","tag-gridnet-os","tag-sandboxing","tag-security","tag-shadow-dom","tag-ui-dapp","tag-ui-development","tag-web-development"],"_links":{"self":[{"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/posts\/835498","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/comments?post=835498"}],"version-history":[{"count":6,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/posts\/835498\/revisions"}],"predecessor-version":[{"id":835528,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/posts\/835498\/revisions\/835528"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/media\/835491"}],"wp:attachment":[{"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/media?parent=835498"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/categories?post=835498"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mag.gridnet.org\/index.php\/wp-json\/wp\/v2\/tags?post=835498"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}