From c5c801be1ab05c8cd4a1e5ab211e0dbaf31993cb Mon Sep 17 00:00:00 2001 From: habsul-rignyr Date: Tue, 18 Jun 2024 12:42:38 -0600 Subject: [PATCH] remove all reference to 'OS' --- src/chess_app.md | 2 +- src/design_philosophy.md | 27 ++++++++++++------ src/frontends.md | 2 +- src/getting-started.md | 6 ++-- src/http_server_and_client.md | 5 ++-- src/identity_system.md | 9 +++--- src/install.md | 9 ++++-- src/intro.md | 20 ++++++------- src/kit-dev-toolkit.md | 32 ++++++++++----------- src/login.md | 6 ++-- src/processes-overview.md | 2 +- src/read_and_write_to_chain.md | 51 +++++++++++++++++----------------- src/terminal.md | 37 +++++++++++++----------- 13 files changed, 115 insertions(+), 93 deletions(-) diff --git a/src/chess_app.md b/src/chess_app.md index 8c61a4ca..d06a037e 100644 --- a/src/chess_app.md +++ b/src/chess_app.md @@ -1,4 +1,4 @@ # In-Depth Guide: Chess App -This guide will walk you through building a very simple chess app on Kinode OS. +This guide will walk you through building a very simple chess app on Kinode. The final result will look like [this](https://github.com/kinode-dao/kinode/tree/main/kinode/packages/chess): chess is in the basic runtime distribution so you can try it yourself. diff --git a/src/design_philosophy.md b/src/design_philosophy.md index 009fa2de..2233e159 100644 --- a/src/design_philosophy.md +++ b/src/design_philosophy.md @@ -1,30 +1,37 @@ # Design Philosophy -The following is a high-level overview of Kinode OS's design philosophy, along with the rationale for fundamental design choices. + +The following is a high-level overview of Kinode's design philosophy, along with the rationale for fundamental design choices. ### Decentralized Software Requires a Shared Computing Environment + A single shared computing environment enables software to coordinate directly between users, services, and other pieces of software in a common language. Therefore, the best way to enable decentralized software is to provide an easy-to-use, general purpose node (that can run on anything from laptops to data centers) that runs the same operating system as all other nodes on the network. This environment must integrate with existing protocols, blockchains, and services to create a new set of protocols that operate peer-to-peer within the node network. ### Decentralization is Broad + A wide array of companies and services benefit from some amount of decentralized infrastructure, even those operating in a largely centralized context. Additionally, central authority and centralized data are often essential to the proper function of a particular service, including those with decentralized properties. The Kinode environment must be flexible enough to serve the vast majority of the decentralization spectrum. ### Blockchains are not Databases + To use blockchains as mere databases would negate their unique value. Blockchains are consensus tools, and exist in a spectrum alongside other consensus strategies such as Raft, lockstep protocols, CRDTs, and simple gossip. All of these are valid consensus schemes, and peer-to-peer software, such as that built on Kinode, must choose the correct strategy for a particular task, program, or application. ### Decentralized Software Outcompetes Centralized Software through Permissionlessness and Composability + Therefore, any serious decentralized network must identify and prioritize the features that guarantee permissionless and composable development. Those features include: -* a persistent software environment (software can run forever once deployed) -* client diversity (more actors means fewer monopolies) -* perpetual backwards-compatibility -* a robust node network that ensures individual ownership of software and data + +- a persistent software environment (software can run forever once deployed) +- client diversity (more actors means fewer monopolies) +- perpetual backwards-compatibility +- a robust node network that ensures individual ownership of software and data ### Decentralized Software Requires Decentralized Governance + The above properties are achieved by governance. Successful protocols launched on Kinode will be ones that decentralize their governance in order to maintain these properties. We believe that systems that don't proactively specify their point of control will eventually centralize, even if unintentionally. @@ -32,13 +39,15 @@ The governance of Kinode itself must be designed to encourage decentralization, In practice, this looks like an on-chain permissionless App Store. ### Good Products Use Existing Tools + Kinode is a novel combination of existing technologies, protocols, and ideas. Our goal is not to create a new programming language or consensus algorithm, but to build a new execution environment that integrates the best of existing tools. Our current architecture relies on the following systems: -* ETH: a trusted execution layer -* Rust: a performant, expressive, and popular programming language -* Wasm: a portable, powerful binary format for executable programs -* Wasmtime: a standalone Wasm runtime + +- ETH: a trusted execution layer +- Rust: a performant, expressive, and popular programming language +- Wasm: a portable, powerful binary format for executable programs +- Wasmtime: a standalone Wasm runtime In addition, Kinode is inspired by the [Bytecode Alliance](https://bytecodealliance.org/) and their vision for secure, efficient, and modular software. We make extensive use of their tools and standards. diff --git a/src/frontends.md b/src/frontends.md index d3f377ad..cc24e65e 100644 --- a/src/frontends.md +++ b/src/frontends.md @@ -1,6 +1,6 @@ # Frontends -Kinode OS can easily serve any webpage or web app developed with normal libraries and frameworks. +Kinode can easily serve any webpage or web app developed with normal libraries and frameworks. There are some specific endpoints, JS libraries, and process lib functions that are helpful for doing frontend development. diff --git a/src/getting-started.md b/src/getting-started.md index 1ed808ed..d5056ef9 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -1,17 +1,19 @@ # The Kinode Book -Kinode OS is a decentralized operating system, peer-to-peer app framework, and node network designed to simplify the development and deployment of decentralized applications. -It is also a *sovereign cloud computer*, in that Kinode can be deployed anywhere and act as a server controlled by anyone. +Kinode is a decentralized operating system, peer-to-peer app framework, and node network designed to simplify the development and deployment of decentralized applications. +It is also a _sovereign cloud computer_, in that Kinode can be deployed anywhere and act as a server controlled by anyone. Ultimately, Kinode facilitates the writing and distribution of software that runs on privately-held, personal server nodes or node clusters. You are reading the Kinode Book, which is a technical document targeted at developers. If you're a non-technical user: + - Learn about Kinode at the [Kinode blog](https://kinode.org/blog). - Spin up a hosted node at [Valet](https://valet.kinode.org/). - [Follow us on X](https://x.com/intent/follow?screen_name=KinodeOS). - Join the conversation on [our Discord](https://discord.gg/mYDj74NkfP) or [Telegram](https://t.me/KinodeOS). If you're a developer: + - Get your hands dirty with the [Quick Start](./quick-start.md), or the more detailed [My First Kinode Application](./build-and-deploy-an-app.md) tutorial. - Learn how to boot a Kinode locally in the [Installation](./install.md) section. diff --git a/src/http_server_and_client.md b/src/http_server_and_client.md index 65759f44..e74bece9 100644 --- a/src/http_server_and_client.md +++ b/src/http_server_and_client.md @@ -3,7 +3,7 @@ No server or web services backend would be complete without an HTTP interface. Kinodes must be able to both create and serve HTTP requests. This enables Kinode apps to read data from the web (and other Kinodes), and also serve both public and private websites and APIs. -The HTTP server is how most processes in the Kinode OS present their interface to the user, through an authenticated web browser. +The HTTP server is how most processes in the Kinode present their interface to the user, through an authenticated web browser. The specification for the [server](./apis/http_server.md) and [client](./apis/http_client.md) APIs are available in the API reference. These APIs are accessible via messaging the [`http_server:distro:sys`](https://github.com/kinode-dao/kinode/blob/main/kinode/src/http/server.rs) and [`http_client:distro:sys`](https://github.com/kinode-dao/kinode/blob/main/kinode/src/http/client.rs) runtime modules, respectively. @@ -12,6 +12,7 @@ The only [capability](./process/capabilities.md) required to use either process WebSocket server/client functionality is presented alongside HTTP. At startup, the server either: + 1. Binds to the port given at the commandline, or 2. Searches for an open port (starting at 8080, if not, then 8081, etc.). @@ -20,7 +21,7 @@ The server then binds this port, listening for HTTP and WebSocket requests. ## Private and Public Serving All server functionality can be either private (authenticated) or public. -If a given functionality is public, the Kinode serves HTTP openly to the world; if it is authenticated, you need your node's password so that your node can generate a cookie that grants you access. +If a given functionality is public, the Kinode serves HTTP openly to the world; if it is authenticated, you need your node's password so that your node can generate a cookie that grants you access. ## Direct and Indirect Nodes diff --git a/src/identity_system.md b/src/identity_system.md index 3c8b539b..edb11aa5 100644 --- a/src/identity_system.md +++ b/src/identity_system.md @@ -2,11 +2,12 @@ One of the most important features of a peer-to-peer network is the ability to maintain a unique and persistent identity. This identity must be self-sovereign, unforgeable, and easy to discover by peers. -Kinode OS uses a domain system similar to [ENS](https://ens.domains/) to achieve this. +Kinode uses a domain system similar to [ENS](https://ens.domains/) to achieve this. It should be noted that, in our system, the concepts of `domain`, `identity`, and `username` are identical and interchangeable. Like ENS, Kinode domains (managed by our KNS) are registered by a wallet and owned in the form of an NFT. However, unlike ENS, Kinode domains never expire. Additionally, they contain metadata necessary to cover both: + - **Domain provenance** - to demonstrate that the NFT owner has provenance of a given Kinode identity. - **Domain resolution** - to be able to route messages to a given identity on the Kinode network. @@ -32,15 +33,15 @@ Again, this is similar to registering a WWW domain name and pointing it at your However, running a direct node is both technically demanding (you must maintain the ability of your machine to be accessed remotely) and a security risk (you must open ports on the server to the public internet). Therefore, indirect nodes are the best choice for the majority of users that choose to run their own node. -Instead of sharing their IP and port, indirect nodes simply post a list of *routers* onchain. -These routers are other *direct* nodes that have agreed to forward messages to indirect nodes. +Instead of sharing their IP and port, indirect nodes simply post a list of _routers_ onchain. +These routers are other _direct_ nodes that have agreed to forward messages to indirect nodes. When a node wants to send a message to an indirect node, it first finds the node onchain, and then sends the message to one of the routers listed in the node's metadata. The router is responsible for forwarding the message to the indirect node and similarly forwarding messages from that node back to the network at large. ## Conclusion For more information about the architectural specifics of the networking protocol, see [Networking Protocol](./networking_protocol.md). -The main takeaway for the identity system is that *domain provenance* and *domain resolution* are unified by KNS. +The main takeaway for the identity system is that _domain provenance_ and _domain resolution_ are unified by KNS. Like .eth for ENS, the KNS domain space is fixed inside the `.os` top-level domain. However, Kinode DAO has the right to manage domains, including domains other than `.os`, so domain availability is likely to expand in the future (subject to governance decisions). diff --git a/src/install.md b/src/install.md index 6f342062..fd263ca0 100644 --- a/src/install.md +++ b/src/install.md @@ -1,6 +1,6 @@ # Installation -This section will teach you how to get the Kinode OS core software, required to run a live node. +This section will teach you how to get the Kinode core software, required to run a live node. After acquiring the software, you can learn how to run it and [Join the Network](./login.md). - If you are just interested in starting development as fast as possible, skip to [My First Kinode Application](./build-and-deploy-an-app.md). @@ -17,7 +17,7 @@ There is no need to download the `simulation-mode` binary — it is used behind Extract the `.zip` file: the binary is inside. Note that some operating systems, particularly Apple, may flag the download as suspicious. -While the binary has not been tested exhaustively on all Linux distributions, it should *just work*. +While the binary has not been tested exhaustively on all Linux distributions, it should _just work_. ### Apple @@ -56,6 +56,7 @@ If you are running a direct node, you **must** map port `9000` to the same port Otherwise, your Kinode will not be able to connect to the rest of the network as connection info is written to the chain, and this information is based on the view from inside the Docker container. Run the following command to create a volume: + ```bash docker volume create kinode-volume ``` @@ -63,6 +64,7 @@ docker volume create kinode-volume Then run the following command to create the container. Replace `kinode-volume` with the name of your volume, and `my-kinode` with a unique name. To map the port to a different port (for example, `80` or `6969`), change `8080:8080` to `PORT:8080`, where `PORT` is the post on the host machine. + ```bash docker run -d -p 127.0.0.1:8080:8080 -it --name my-kinode \ --mount type=volume,source=kinode-volume,destination=/kinode-home \ @@ -81,6 +83,7 @@ If you need further help with Docker, [access the official Docker documentation You can compile the binary from source using the following instructions. This is only recommended if: + 1. The [pre-compiled binaries](#download-binary) don't work on your system and you can't use [Docker](#docker) for some reason, or 2. You need to make changes to the Kinode core source. @@ -118,7 +121,7 @@ For more information, or debugging, see the [Rust lang install page](https://www Kinode uses the **nightly** build of Rust. You will want to run the command `rustup update` on a regular basis to keep your version of the language current, especially if you run into issues compiling the runtime down the line. -### Acquire Kinode OS core +### Acquire Kinode core Clone and set up the repository: diff --git a/src/intro.md b/src/intro.md index 226706fb..66caed06 100644 --- a/src/intro.md +++ b/src/intro.md @@ -2,20 +2,20 @@ The Kinode Book describes the Kinode operating system, both in conceptual and practical terms. -Kinode OS is a decentralized operating system, peer-to-peer app framework, and node network designed to simplify the development and deployment of decentralized applications. -It is also a *sovereign cloud computer*, in that Kinode can be deployed anywhere and act as a server controlled by anyone. +Kinode is a decentralized operating system, peer-to-peer app framework, and node network designed to simplify the development and deployment of decentralized applications. +It is also a _sovereign cloud computer_, in that Kinode can be deployed anywhere and act as a server controlled by anyone. Ultimately, Kinode facilitates the writing and distribution of software that runs on privately-held, personal server nodes or node clusters. Kinode eliminates boilerplate and reduces the complexity of p2p software development by providing four basic and necessary primitives: -Primitive | Description ----------------- | ----------- -Networking | Passing messages from peer to peer. -Identity | Linking permanent system-wide identities to individual nodes. -Data Persistence | Storing data and saving it in perpetuity. -Global State | Reading shared global state (blockchain) and composing actions with this state (transactions). +| Primitive | Description | +| ---------------- | ---------------------------------------------------------------------------------------------- | +| Networking | Passing messages from peer to peer. | +| Identity | Linking permanent system-wide identities to individual nodes. | +| Data Persistence | Storing data and saving it in perpetuity. | +| Global State | Reading shared global state (blockchain) and composing actions with this state (transactions). | -The focus of this book is how to build and deploy applications on Kinode OS. +The focus of this book is how to build and deploy applications on Kinode. ## Architecture Overview @@ -24,7 +24,7 @@ Kinode's kernel handles the startup and teardown of processes, as well as messag Processes are programs compiled to Wasm, which export a single `init()` function. They can be started once and complete immediately, or they can run "forever". -Peers in Kinode OS are identified by their onchain username in the "KNS": Kinode Name System, which is modeled after ENS. +Peers in Kinode are identified by their onchain username in the "KNS": Kinode Name System, which is modeled after ENS. The modular architecture of the KNS allows for any Ethereum NFT, including ENS names themselves, to generate a unique Kinode identity once it is linked to a KNS entry. Data persistence and blockchain access, as fundamental primitives for p2p apps, are built directly into the kernel. diff --git a/src/kit-dev-toolkit.md b/src/kit-dev-toolkit.md index a81fbea3..f7a187d1 100644 --- a/src/kit-dev-toolkit.md +++ b/src/kit-dev-toolkit.md @@ -1,21 +1,21 @@ # kit -[`kit`](https://github.com/kinode-dao/kit) is a CLI tool**kit** to make development on Kinode OS ergonomic. +[`kit`](https://github.com/kinode-dao/kit) is a CLI tool**kit** to make development on Kinode ergonomic. ## Table of Contents -* [Installation](./kit/install.md) -* [`kit boot-fake-node`](./kit/boot-fake-node.md) -* [`kit new`](./kit/new.md) -* [`kit build`](./kit/build.md) -* [`kit start-package`](./kit/start-package.md) -* [`kit build-start-package`](./kit/build-start-package.md) -* [`kit remove-package`](./kit/remove-package.md) -* [`kit chain`](./kit/chain.md) -* [`kit dev-ui`](./kit/dev-ui.md) -* [`kit inject-message`](./kit/inject-message.md) -* [`kit run-tests`](./kit/run-tests.md) -* [`kit connect`](./kit/connect.md) -* [`kit reset-cache`](./kit/reset-cache.md) -* [`kit boot-real-node`](./kit/boot-real-node.md) -* [`kit view-api`](./kit/view-api.md) +- [Installation](./kit/install.md) +- [`kit boot-fake-node`](./kit/boot-fake-node.md) +- [`kit new`](./kit/new.md) +- [`kit build`](./kit/build.md) +- [`kit start-package`](./kit/start-package.md) +- [`kit build-start-package`](./kit/build-start-package.md) +- [`kit remove-package`](./kit/remove-package.md) +- [`kit chain`](./kit/chain.md) +- [`kit dev-ui`](./kit/dev-ui.md) +- [`kit inject-message`](./kit/inject-message.md) +- [`kit run-tests`](./kit/run-tests.md) +- [`kit connect`](./kit/connect.md) +- [`kit reset-cache`](./kit/reset-cache.md) +- [`kit boot-real-node`](./kit/boot-real-node.md) +- [`kit view-api`](./kit/view-api.md) diff --git a/src/login.md b/src/login.md index 33b52a53..f9aaacc1 100644 --- a/src/login.md +++ b/src/login.md @@ -3,7 +3,7 @@ This page discusses joining the network with a locally-run Kinode. To instead join with a hosted node, see [Valet](https://valet.kinode.org/). -These directions are particular to the Kinode OS beta release. +These directions are particular to the Kinode beta release. Kinode is in active development on Optimism. ## Starting the Kinode @@ -62,17 +62,19 @@ Next, check the box next to Optimism "MAINNET". After one is chosen, click "SAVE On the "Active Endpoints" tab, there are tabs for "HTTPS" and "WebSockets". Select the WebSockets tab. Copy this endpoint and use it in place of the Alchemy endpoint in the following step, "Running the Binary". ![Active Endpoints Infura](./assets/active_endpoints_infura.png) - + ### Running the Binary In a terminal window, run: + ```bash ./kinode home ``` A new browser tab should open, but if not, look in the terminal for this line: + ``` login or register at http://localhost:8080 ``` diff --git a/src/processes-overview.md b/src/processes-overview.md index dce5330a..75c5d0d4 100644 --- a/src/processes-overview.md +++ b/src/processes-overview.md @@ -1,6 +1,6 @@ # Processes -Processes are independent pieces of Wasm code running on Kinode OS. +Processes are independent pieces of Wasm code running on Kinode. They can either be persistent, in which case they have in-memory state, or temporary, completing some specific task and returning. They have access to long-term storage, like the filesystem or databases. They can communicate locally and over the Kinode network. diff --git a/src/read_and_write_to_chain.md b/src/read_and_write_to_chain.md index 5da8edec..c61294e8 100644 --- a/src/read_and_write_to_chain.md +++ b/src/read_and_write_to_chain.md @@ -1,6 +1,6 @@ # Read+Write to Chain -Kinode OS comes with a built-in provider module for Ethereum and other EVM chains/rollups. +Kinode comes with a built-in provider module for Ethereum and other EVM chains/rollups. This runtime module lives in [`eth:distro:sys`](https://github.com/kinode-dao/kinode/tree/main/kinode/src/eth) and is usable by any package that acquires the messaging capability for it. In addition to allowing read/write connections directly to WebSocket RPC endpoints, the provider module can also connect via the Kinode networking protocol to other Kinodes and use their provider modules as a relay to an RPC endpoint (or to another Kinode, forming a relay chain). The node must be configured to allow relay connections, which can be done with a public/private flag or explicit allow/deny list. @@ -13,7 +13,7 @@ For more advanced or direct usage, such as configuring the provider module, see The provider module is capable of using any RPC endpoint that follows the [JSON-RPC API](https://ethereum.org/developers/docs/apis/json-rpc) that is used by Ethereum and most other EVM chains and rollups. The runtime uses the [Alloy](https://github.com/alloy-rs) family of libraries to connect to WS RPC endpoints. -It does not currently support HTTP endpoints, as subscriptions are vastly preferable for many of the features that Kinode OS uses. +It does not currently support HTTP endpoints, as subscriptions are vastly preferable for many of the features that Kinode uses. ### Configuration @@ -26,31 +26,31 @@ The file is a JSON object: a list of providers, with the following shape (exampl ```json [ - { - "chain_id": 1, - "trusted": false, - "provider": { - "RpcUrl": "wss://ethereum.publicnode.com" - } - }, - { - "chain_id": 11155111, - "trusted": false, - "provider": { - "Node": { - "use_as_provider": true, - "kns_update": { - "name": "default-router-1.os", - "owner": "", - "node": "0xb35eb347deb896bc3fb6132a07fca1601f83462385ed11e835c24c33ba4ef73d", - "public_key": "0xb1b1cf23c89f651aac3e5fd4decb04aa177ab0ec8ce5f1d3877b90bb6f5779db", - "ip": "123.456.789.101", - "port": 9000, - "routers": [] - } - } + { + "chain_id": 1, + "trusted": false, + "provider": { + "RpcUrl": "wss://ethereum.publicnode.com" + } + }, + { + "chain_id": 11155111, + "trusted": false, + "provider": { + "Node": { + "use_as_provider": true, + "kns_update": { + "name": "default-router-1.os", + "owner": "", + "node": "0xb35eb347deb896bc3fb6132a07fca1601f83462385ed11e835c24c33ba4ef73d", + "public_key": "0xb1b1cf23c89f651aac3e5fd4decb04aa177ab0ec8ce5f1d3877b90bb6f5779db", + "ip": "123.456.789.101", + "port": 9000, + "routers": [] } + } } + } ] ``` @@ -59,4 +59,3 @@ Nodes that wish to maximize their connectivity should supply themselves with url In fact, a future update to the provider module will likely integrate Helios, which will allow nodes to convert untrusted endpoints to trusted ones. This is the reason for the `trusted` flag in the provider object. Lastly, note that the `kns_update` object must fully match the onchain PKI data for the given node, otherwise the two nodes will likely not be able to establish a connection. - diff --git a/src/terminal.md b/src/terminal.md index da713ef7..f9ddb604 100644 --- a/src/terminal.md +++ b/src/terminal.md @@ -5,11 +5,11 @@ The [terminal syntax](https://github.com/kinode-dao/kinode?tab=readme-ov-file#te ## Commands All commands in the [terminal](https://github.com/kinode-dao/kinode/tree/main/kinode/packages/terminal) are calling scripts — a special kind of process. -Kinode OS comes pre-loaded with a number of scripts useful for debugging and everyday use. +Kinode comes pre-loaded with a number of scripts useful for debugging and everyday use. These scripts are fully named `