godprotocol

��# GodProtocol A distributed computing environment for Web 4.0 integrating AI, decentralisation, and virtual computation. This repository contains the GodProtocol core implementation: a modular, extensible runtime built in modern Node.js that organizes computation through a set of `Objects`, `Instances`, `Datatypes`, and `callables` (action primitives). --- ## Highlights - Purpose: Provide a flexible virtual computation environment (a.k.a. "Trinity") that can be embedded, extended, and run locally or in distributed setups. - Built with: Node.js (ES Modules / "type": "module"). - Minimum Node.js: 18+ (see `package.json`). --- ## Quick start Prerequisites - Node.js 18 or newer. Install dependencies ```powershell npm install ``` Run in development (uses nodemon): ```powershell npm run start ``` Run without nodemon: ```powershell npm run dev ``` Notes: - `start` script uses `nodemon` and will restart on file changes. `dev` runs the entry file once. - The package is an ES module package (see `package.json` -> `type: "module"`). --- ## Programmatic usage The runtime is bootstrapped from `Index.js` which creates a `Trinity` instance: - `Index.js` imports `Trinity` from `Objects/Trinity.js` and exports the instantiated runtime. You can import this file from another ES module-based project or require it as part of a larger system. Example (inside another ES module file): ```js import trinity from "./Index.js"; // `trinity` is the default runtime instance created on import // Interact with it according to the project's API (Objects/Trinity.js) ``` Environment variables - `Trinity` if set, this will be passed into `new Trinity(process.env.Trinity || "GodProtocol")` (see `Index.js`). --- ## Project layout (high-level) This project is intentionally modular. Below is a short description of top-level directories and notable files. - `Index.js` entry point; instantiates the main `Trinity` runtime. - `package.json` project metadata, dependencies and scripts. - `Objects/` core object classes (e.g., `Trinity.js`, `Oracle.js`, `Repository.js`, `Manager.js`, `Virtual_machine.js`). These implement the major runtime primitives and behaviors. - `Instances/` concrete runtime instances and adapters used by the system (accounts, events, folders, responses, etc.). - `Datatypes/` primitive and compound datatypes used throughout the runtime (strings, numbers, arrays, booleans, callable wrappers and utilities). There is also a `functions/` folder here for datatype-specific helper modules like storage and wallet. - `callables/` a collection of action primitives (small functions that get registered and called by the runtime). `callables/register.js` provides the registration mechanism. - `html/` helpers for the loader/renderer (create, load, parse, run and utility files used by the HTML/loader subsystem). - `utils/` assorted utilities and services used by the runtime (server creation, crypto/hash helpers, socket server, `services.js` for HTTP interactions, certificate files, etc.). Files you will likely read first - `Objects/Trinity.js` core runtime orchestration (primary entry point for understanding how components are wired). - `Objects/Oracle.js` implements an Oracle client used to talk to oracle endpoints (example of a higher-level service that uses `utils/services.js`). - `utils/create_server.js` & `utils/socket_server.js` server creation and socket utilities. --- ## Core concepts - Trinity: the root runtime. It wires together objects, instances, datatypes, and callables to provide execution and storage semantics. - Objects: classes that provide major runtime roles (block, repository, manager, virtual machine, oracle client, etc.). - Instances: runtime-bound objects that represent entities (accounts, events, folders, responses). - Datatypes: typed wrappers and validators used to keep runtime data consistent and pluggable. - Callables: the primitive operations; small modules in the `callables/` folder that are registered and invoked by runtime code. --- ## Development notes - Add new callables by creating modules in `callables/functions/` and registering them with `callables/register.js`. - To add a new Datatype, follow the pattern used in `Datatypes/` (there are examples for `str.js`, `num.js`, `arr.js`, `bool.js`, etc.). - Core object behavior lives in `Objects/`. If you implement new runtime features, implement them as an `Object` class and wire into `Trinity`. - Keep code modular and stateless where possible. Use `Instances/` for per-runtime state adapters. Certificates and local HTTPS - `utils/server.cert` and `utils/server.key` are present for development HTTPS (local testing). Do not use these files for production encryption keys. --- ## Dependencies - Declared in `package.json`: - `aircode4` (latest) used somewhere in the runtime (see code references). - `generalised-datastore` (latest) datastore abstraction. - Dev dependency: `nodemon` (for `npm run start`). Install them with `npm install` (already shown above). Pin versions if you need deterministic installs. --- ## Tests & CI - There are no automated tests included in the repository by default. - Recommended: add minimal unit tests (Jest / Ava / Vitest) focused on `Objects/Trinity.js` and small, pure callables. A basic test suite should include: - Trinity startup + shutdown - Basic callable registration and invocation - Datatype validation and serialization --- ## Troubleshooting - Node runtime errors: ensure Node >= 18 and that the `type: "module"` setting in `package.json` is respected by your environment. - Unresolved imports: run `npm install` and verify the `node_modules` folder exists. If using an editor, restart its language server. - HTTPS / certificate errors during development: the repo includes sample certs in `utils/` configure your local client to trust them or switch to HTTP for local development. --- ## Contributing Contributions are welcome. Suggested workflow: 1. Fork the repo. 2. Create a feature branch for your change. 3. Run the project locally and add tests for new behavior. 4. Open a clear PR with a description of the change and any migration steps. Please follow the existing code style and module patterns. Keep changes small and focused. --- ## License & Contact - License: ISC (see `package.json`). - Repository: https://github.com/immanuel-savvy/GodProtocol - Author: Savvy <contact@yourdomain.com> If you need help onboarding or want a walkthrough of the major modules, open an issue on the repository or contact the author directly. --- ## Next steps / Suggested improvements - Add a small test harness & CI configuration (GitHub Actions) to run lint and tests on each PR. - Add documentation on the Trinity public API with examples and common patterns. - Add examples demonstrating embedding the runtime inside another application and using the Oracle client. Thank you for exploring GodProtocol if you want, I can also generate a CONTRIBUTING.md, add a basic test suite, or scaffold API docs from the `Objects/` source files. # GodProtocol