Merge pull request #265 from kinode-dao/develop

develop

src/SUMMARY.md

@@ -15,7 +15,7 @@
     - [Extensions](./system/process/extensions.md)
     - [WIT APIs](./system/process/wit_apis.md)
   - [Networking Protocol](./system/networking_protocol.md)
-  - [HTTP Server & Client](./system/http-server_and_client.md)
+  - [HTTP Server & Client](./system/http_server_and_client.md)
   - [Read+Write to Chain](./system/read_and_write_to_chain.md)
   - [Files](./system/files.md)
   - [Databases](./system/databases.md)
@@ -82,3 +82,4 @@
   - [WebSocket API](./apis/websocket.md)
 - [Hosted Nodes User Guide](./hosted-nodes.md)
 - [Audits and Security](./audits-and-security.md)
+- [Glossary](./glossary.md)

src/cookbook/file_transfer_ui.md

@@ -611,7 +611,7 @@ const SearchFiles = function() {
 
     const handleSearch = () => {
         if (!searchTerm) return alert('Please enter a node name.');
-        if (!searchTerm.match(/^[a-zA-Z0-9-]+\.os$/)) return alert('Invalid node name.');
+        if (!searchTerm.match(/^[a-z0-9-]+\.os$/)) return alert('Invalid node name.');
         try {
             fetch(`${import.meta.env.BASE_URL}/files?node=${searchTerm}`, {
                 method: 'GET',

src/getting_started/login.md

@@ -14,10 +14,6 @@ Print out the arguments expected by the binary:
 
 ```
 $ ./kinode --help
-
-DOCKER_BUILD_IMAGE_VERSION: none
-PACKAGES_ZIP_HASH: 9558ea0e2180aea1afc69cbf055a4da14c51cea67fbff9cfb847533caef301fd
-
 A General Purpose Sovereign Cloud Computing Platform
 
 Usage: kinode [OPTIONS] <home>
@@ -54,6 +50,8 @@ Options:
           Maximum number of passthroughs serve as a router (default 0)
       --soft-ulimit <SOFT_ULIMIT>
           Enforce a static maximum number of file descriptors (default fetched from system)
+      --process-verbosity <JSON_STRING>
+          ProcessId: verbosity JSON object [default: ]
   -h, --help
           Print help
   -V, --version
@@ -68,6 +66,8 @@ If no `--port` flag is supplied, Kinode will bind to `8080` if it is available,
 
 <details><summary>OPTIONAL: Acquiring an RPC API Key</summary>
 
+### Acquiring an RPC API Key
+
 Create a new "app" on [Alchemy](https://dashboard.alchemy.com/apps) for Optimism Mainnet.
 
 ![Alchemy Create App](../assets/alchemy-create-app.png)

src/glossary.md

@@ -0,0 +1,173 @@
+# Glossary
+
+Kinode uses a variety of technical terms.
+The glossary defines those terms.
+
+## Address
+
+[Processes](#process) have a globally-unique [address](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/kinode/process/standard/struct.Address.html) to and from which [messages](#message) can be routed.
+
+## App Store
+
+The Kinode App Store is the place where users download Kinode apps and where devs distribute Kinode [packages](#package).
+
+
+## Blob
+
+See [LazyLoadBlob](#LazyLoadBlob).
+
+## Capability
+
+Kinode uses [capabilities](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/kinode/process/standard/struct.Capability.html) to restrict what [processes](#process) can do.
+A capability is issued by a process (the "issuer") and signed by the [kernel](#kernel).
+The holder of a capability can then attach that capability to a message.
+The kernel will confirm it is valid by checking the signature.
+If valid, it will be passed to the recipient of the message.
+Only trust capabilties from [local](#local) holders!
+A [remote](#remote) [node](#node) need not follow the rules above (i.e. it may run a modified [runtime](#runtime)).
+
+There are system-level and userspace-level capabilities.
+
+System-level capabilities are of two types:
+- `"messaging"`, which allows the holder to send messages to the issuer.
+- `"net"`, which allows the holder to send/receive messages over the network to/from remote nodes.
+
+System-level capabilities need not be attached explicitly to messages.
+They are requested and granted at process start-time in the [manifest](#manifest).
+
+Userspace-level capabilities are defined within a process.
+They are issued by that process.
+Holders must explictly attach these capabilities to their messages to the issuing process.
+The issuer must define the logic that determines what happens if a sender has or does not have a capability.
+E.g., the system Contacts app defines capabilities [here](https://github.com/kinode-dao/kinode/blob/main/kinode/packages/contacts/api/contacts%3Asys-v0.wit#L2-L7) and the logic that allows/disallows access given a sender's capabilities [here](https://github.com/kinode-dao/kinode/blob/main/kinode/packages/contacts/contacts/src/lib.rs#L291-L314).
+
+## Inherit
+
+## Kernel
+
+The Kinode microkernel is responsible for:
+1. Starting and stopping [processes](#process).
+2. Routing [messages](#message).
+3. Enforcing [capabilities](#capability).
+
+## Kimap
+
+Kimap is the onchain component of Kinode.
+Kimap is a path-value map.
+Protocols can be defined on Kimap.
+
+Examples:
+
+The KNS protocol stores contact information for all [Kinodes](#node) in Kimap entries.
+That contact information looks like:
+1. A public key.
+2. Either an IP address or a list of other nodes that will route messages to that node.
+The `kns-indexer` Kinode [process](#process) reads the Kimap, looking for these specific path/entries, and then uses that information to contact other nodes offchain.
+
+The Kinode [App Store](#app-store) protocol stores the app metadata URI and hash of that metadata in Kimap entries.
+The `app-store` Kinode process reads the Kimap, looking for these specific path/entries, and then uses that information to coordinate:
+1. Fetching app information.
+2. Finding mirrors to download from (over the Kinode network or HTTP).
+3. Confirming those mirrors gave the expected files.
+4. Fetching and installing updates, if desired, when made available.
+
+Read more [here](./getting_started/kimap.md).
+
+## Kimap-safe
+
+A String containing only a-z, 0-9, `-`, and, for a publisher [node](#node), `.`.
+
+## LazyLoadBlob
+
+An optional part of a [message](#message) that is "loaded lazily".
+The purpose of he [LazyLoadBlob](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/kinode/process/standard/struct.LazyLoadBlob.html) is to avoid the cost of repeatedly bringing large data across the Wasm boundary in a [message-chain](#message-chain) when only the ends of the chain need to access the data.
+
+## Local
+
+Of or relating to our [node](#node).
+Contrasts with [remote](#remote).
+
+E.g., a local [process](#process) is one that is running on our node.
+[Messages](#message) sent to a local process need not traverse the Kinode network.
+
+Capabilities attached to messages received from a local process can be trusted since the [kernel](#kernel) can be trusted.
+
+## Manifest
+
+## Message
+
+Kinode [processes](#process) communicate with each other by passing messages.
+Messages are [addressed](#address) to a local or remote [process](#process), contain some content, and have a variety of associated metadata.
+Messages can be [requests](#request) or [responses](#response).
+Messages can set off [message-chains](#message-chain) of requests and responses.
+A process that sends a request must specify the address of the recipient.
+In contrast, a response will be routed automatically to the sender of the most recently-received request in the message-chain that expected a response.
+
+## Message-chain
+
+## Module
+
+A module, or runtime module, is similar to a [process](#process).
+[Messages](#message) are [addressed](#address) to and received from a module just like a process.
+The difference is that processes are [Wasm components](#wasm-component), which restricts them in a number of ways, e.g., to be single-threaded.
+Runtime modules do not have these same restrictions.
+As such they provide some useful features for processes, such as access to the Kinode network, a virtual file system, databases, the Ethereum blockchain, an HTTP server and client, etc.
+
+## Node
+
+A node (sometimes referred to as a Kinode) is a server running the Kinode [runtime](#runtime).
+It communicates with other nodes over the Kinode network using [message](#message) passing.
+It has a variety of [runtime modules](#module) and also runs userspace [processes](#process) which are [Wasm components](#component).
+
+## Package
+
+An "app".
+A set of one-or-more [processes](#process) along with one-or-more UIs.
+Packages can be distributed using the Kinode [App Store](#app-store).
+
+Packages have a unique [identity](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/kinode/process/standard/struct.PackageId.html).
+
+## PackageId
+
+## Process
+
+Kinode processes are the code bundles that make up userspace.
+Kinode processes are [Wasm components](#wasm-component) that use either the [Kinode process WIT file](https://github.com/kinode-dao/kinode-wit/blob/v1.0.0/kinode.wit) or that define their own [WIT](#wit) file that [wraps the Kinode process WIT file](./cookbook/package_apis.md).
+
+Processes have a unique [identity](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/kinode/process/standard/struct.ProcessId.html) and a globally unique [address](#address).
+
+## ProcessId
+
+## Remote
+
+Of or relating to someone else's [node](#node).
+Contrasts with [local](#local).
+
+E.g., a remote [process](#process) is one that is running elsewhere.
+[Messages](#message) sent to a remote process must traverse the Kinode network.
+
+Capabilities attached to messages received from a remote process cannot be trusted since the [kernel](#kernel) run by that remote node might be modified.
+E.g., the hypothetical modified kernel might take all capabilities issued to any process it runs and give it to all processes it runs.
+
+## Request
+
+A [message](#message) that requires the [address](#address) of the recipient.
+A [request](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/struct.Request.html) can start off a messsage-chain if the sender sets metadata that indicates it expects a [response](#response).
+
+## Response
+
+A [message](#message) that is automatically routed to the sender of the most recently-received [request](#request) in the [message-chain](#message-chain) that expected a [response](https://docs.rs/kinode_process_lib/latest/kinode_process_lib/struct.Response.html).
+
+## Runtime
+
+## Wasm Component
+
+[The WebAssembly Component Model](https://component-model.bytecodealliance.org/) is a standard that builds on top of WebAssembly and WASI.
+Wasm components define their interfaces using [WIT](#wit).
+Kinode [processes](#process) are Wasm components.
+
+## WIT
+
+WIT is the [Wasm Interface Type](https://component-model.bytecodealliance.org/design/wit.html).
+WIT is used to define the interface for a [Wasm component](#wasm-component).
+Kinode [processes](#process) must use either the [Kinode process WIT file](https://github.com/kinode-dao/kinode-wit/blob/v1.0.0/kinode.wit) or define their own WIT file that [wraps the Kinode process WIT file](./cookbook/package_apis.md)

src/kit/build.md

@@ -21,7 +21,7 @@ It automatically detects what language each process is, and builds it appropriat
 
 `kit build` builds a Kinode package directory.
 Specifically, it iterates through all directories within the given package directory and looks for `src/lib.??`, where the `??` is the file extension.
-Currently, `rs`, `py`, and `js` are supported, corresponding to processes written in `rust`, `python`, and `javascript`, respectively.
+Currently, `rs` is supported, corresponding to processes written in `rust`.
 Note that a package may have more than one process and those processes need not be written in the same language.
 
 After compiling each process, it places the output `.wasm` binaries within the `pkg/` directory at the top-level of the given package directory.

src/kit/kit-dev-toolkit.md

@@ -9,6 +9,7 @@
 - [`kit new`](../kit/new.md)
 - [`kit build`](../kit/build.md)
 - [`kit start-package`](../kit/start-package.md)
+- [`publish`](../kit/publish.md)
 - [`kit build-start-package`](../kit/build-start-package.md)
 - [`kit remove-package`](../kit/remove-package.md)
 - [`kit chain`](../kit/chain.md)

src/kit/new.md

@@ -10,7 +10,7 @@ kit new foo
 
 creates the default template (a Rust chat app with no UI) in the `foo/` directory.
 
-The package name must be "Kimap-safe": contain only a-z, A-Z, 0-9, and `-`.
+The package name must be "Kimap-safe": contain only a-z, 0-9, and `-`.
 
 ## Example Usage
 
@@ -54,11 +54,11 @@ Create a Kinode template package
 Usage: kit new [OPTIONS] <DIR>
 
 Arguments:
-  <DIR>  Path to create template directory at (must contain only a-z, A-Z, 0-9, `-`)
+  <DIR>  Path to create template directory at (must contain only a-z, 0-9, `-`)
 
 Options:
-  -a, --package <PACKAGE>      Name of the package (must contain only a-z, A-Z, 0-9, `-`) [default: DIR]
-  -u, --publisher <PUBLISHER>  Name of the publisher (must contain only a-z, A-Z, 0-9, `-`, `.`) [default: template.os]
+  -a, --package <PACKAGE>      Name of the package (must contain only a-z, 0-9, `-`) [default: DIR]
+  -u, --publisher <PUBLISHER>  Name of the publisher (must contain only a-z, 0-9, `-`, `.`) [default: template.os]
   -l, --language <LANGUAGE>    Programming language of the template [default: rust] [possible values: rust]
   -t, --template <TEMPLATE>    Template to create [default: chat] [possible values: blank, chat, echo, fibonacci, file-transfer]
       --ui                     If set, use the template with UI
@@ -75,14 +75,14 @@ By default the package name is set to the name specified here, if not supplied b
 short: `-a`
 
 Name of the package; defaults to `DIR`.
-Must be Kimap-safe: contain only a-z, A-Z, 0-9, and `-`.
+Must be Kimap-safe: contain only a-z, 0-9, and `-`.
 
 ### `--publisher`
 
 short: `-u`
 
 Name of the publisher; defaults to `template.os`.
-Must be Kimap-safe (plus `.`): contain only a-z, A-Z, 0-9, `-`, and `.`.
+Must be Kimap-safe (plus `.`): contain only a-z, 0-9, `-`, and `.`.
 
 ### `--language`
 

src/my_first_app/build_and_deploy_an_app.md

@@ -2,7 +2,7 @@
 
 In these tutorials, you'll setup your development environment and learn about the `kit` tools.
 You'll learn about templates and also walk through writing an application from the ground up, backend and frontend.
-And finally, you'll learn how to deploy applications through the Kinode app store.
+And finally, you'll learn how to deploy applications through the Kinode App Store.
 
 For the purposes of this documentation, terminal commands are provided as-is for ease of copying except when the output of the command is also shown.
 In that case, the command is prepended with a `$ ` to distinguish the command from the output.

src/my_first_app/chapter_1.md

@@ -32,18 +32,18 @@ Create a Kinode template package
 Usage: kit new [OPTIONS] <DIR>
 
 Arguments:
-  <DIR>  Path to create template directory at (must contain only a-z, A-Z, 0-9, `-`)
+  <DIR>  Path to create template directory at (must contain only a-z, 0-9, `-`)
 
 Options:
-  -a, --package <PACKAGE>      Name of the package (must contain only a-z, A-Z, 0-9, `-`) [default: DIR]
-  -u, --publisher <PUBLISHER>  Name of the publisher (must contain only a-z, A-Z, 0-9, `-`, `.`) [default: template.os]
+  -a, --package <PACKAGE>      Name of the package (must contain only a-z, 0-9, `-`) [default: DIR]
+  -u, --publisher <PUBLISHER>  Name of the publisher (must contain only a-z, 0-9, `-`, `.`) [default: template.os]
   -l, --language <LANGUAGE>    Programming language of the template [default: rust] [possible values: rust]
   -t, --template <TEMPLATE>    Template to create [default: chat] [possible values: blank, chat, echo, fibonacci, file-transfer]
       --ui                     If set, use the template with UI
   -h, --help                   Print help
 ```
 
-Create a package `my-chat-app` (you can name it anything "Kimap-safe", i.e. containing only a-z, A-Z, 0-9, `-`; but we'll assume you're working with `my-chat-app` in this document):
+Create a package `my-chat-app` (you can name it anything "Kimap-safe", i.e. containing only a-z, 0-9, `-`; but we'll assume you're working with `my-chat-app` in this document):
 
 ```bash
 kit new my-chat-app
@@ -92,7 +92,7 @@ my-chat-app
     └── tests.toml
 ```
 
-The `my-chat-app/` package here contains two processes:
+The `my-chat-app/` package here contains two processes, each represented by a directory:
 - `my-chat-app/` — containing the main application code, and
 - `send/` — containing a [script](../cookbook/writing_scripts.html).
 
@@ -104,10 +104,10 @@ Another standard Rust `Cargo.toml` file, a [virtual manifest](https://doc.rust-l
 
 Also within the package directory is a `pkg/` directory.
 The `pkg/` dirctory contains two files:
-- `manifest.json` — required: specifes information the Kinode needs to run the package, and
+- `manifest.json` — required: specifes information Kinode needs to run the package, and
 - `scripts.json` — optional: specifies details needed to run [scripts](../cookbook/writing_scripts.html).
 
-The `pkg/` directory is also where `.wasm` binaries will be deposited by [`kit build`](#building-the-package).
+The `pkg/` directory is also where `.wasm` binaries (and, optionally, built UI files) will be deposited by [`kit build`](#building-the-package).
 The files in the `pkg/` directory are injected into the Kinode with [`kit start-package`](#starting-the-package).
 
 The `metadata.json` is a required file that contains app metadata which is used in the Kinode [App Store](./chapter_5.html).
@@ -186,7 +186,7 @@ $ cat my-chat-app/metadata.json
         "code_hashes": {
             "0.1.0": ""
         },
-        "wit_version": 0,
+        "wit_version": 1,
         "dependencies": []
     },
     "external_url": "",
@@ -195,9 +195,14 @@ $ cat my-chat-app/metadata.json
 ```
 Here, the `publisher` is the default value (`"template.os"`), but for a real package, this field should contain the KNS ID of the publishing node.
 The `publisher` can also be set with a `kit new --publisher` flag.
-The `wit_version` is an optional field.
-If elided, the package will use [`kinode.wit` `0.7.0`](https://github.com/kinode-dao/kinode-wit/blob/aa2c8b11c9171b949d1991c32f58591c0e881f85/kinode.wit).
-If included with a value of `0`, it will use [`kinode.wit` `0.8.0`](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit).
+The `wit_version` is an optional field:
+
+`wit_version` value | Resulting `kinode.wit` version
+------------------- | ------------------------------
+elided              | [`kinode.wit` `0.7.0`](https://github.com/kinode-dao/kinode-wit/blob/aa2c8b11c9171b949d1991c32f58591c0e881f85/kinode.wit)
+`0`                 | [`kinode.wit` `0.8.0`](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit)
+`1`                 | [`kinode.wit` `1.0.0`](https://github.com/kinode-dao/kinode-wit/blob/v1.0.0/kinode.wit)
+
 The `dependencies` field is also optional; see discussion in [WIT APIs](../system/process/wit_apis.md).
 The rest of these fields are not required for development, but become important when publishing a package with the [`app-store`](https://github.com/kinode-dao/kinode/tree/main/kinode/packages/app-store).
 
@@ -207,7 +212,7 @@ As an aside: each process has a unique `ProcessId`, used to address messages to
 <process-name>:<package-name>:<publisher-node>
 ```
 
-Each field separated by `:`s must be "Kimap safe", i.e. can only contain a-z, A-Z, 0-9, `-` (and, for publisher node, `.`).
+Each field separated by `:`s must be "Kimap safe", i.e. can only contain a-z, 0-9, `-` (and, for publisher node, `.`).
 
 You can read more about `ProcessId`s [here](../system/process/processes.md#overview).
 
@@ -257,8 +262,8 @@ To exit from the fake node, press `Ctrl + C`.
 By default, the fake node will bind to port `8080`.
 Note the port number in the output for [later](#starting-the-package); it will look something like:
 
-```bash
-Thu 22:50 http-server: running on port 8080
+```
+Serving Kinode at http://localhost:8080
 ```
 
 `kit boot-fake-node` also accepts a `--runtime-path` argument.