diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f0c3aa0e..faef8049 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/cookbook/file_transfer_ui.md b/src/cookbook/file_transfer_ui.md index 9f33aa43..dc3406f6 100644 --- a/src/cookbook/file_transfer_ui.md +++ b/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', diff --git a/src/getting_started/login.md b/src/getting_started/login.md index 91f91fd3..2d60cf77 100644 --- a/src/getting_started/login.md +++ b/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] @@ -54,6 +50,8 @@ Options: Maximum number of passthroughs serve as a router (default 0) --soft-ulimit Enforce a static maximum number of file descriptors (default fetched from system) + --process-verbosity + 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,
OPTIONAL: Acquiring an RPC API Key +### 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) diff --git a/src/glossary.md b/src/glossary.md new file mode 100644 index 00000000..f4791b73 --- /dev/null +++ b/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) diff --git a/src/kit/build.md b/src/kit/build.md index 35c7b6cb..fdd6e138 100644 --- a/src/kit/build.md +++ b/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. diff --git a/src/kit/kit-dev-toolkit.md b/src/kit/kit-dev-toolkit.md index f6ee9a92..b21f2612 100644 --- a/src/kit/kit-dev-toolkit.md +++ b/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) diff --git a/src/kit/new.md b/src/kit/new.md index 8f21b43e..7ba86e67 100644 --- a/src/kit/new.md +++ b/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] Arguments: - Path to create template directory at (must contain only a-z, A-Z, 0-9, `-`) + Path to create template directory at (must contain only a-z, 0-9, `-`) Options: - -a, --package Name of the package (must contain only a-z, A-Z, 0-9, `-`) [default: DIR] - -u, --publisher Name of the publisher (must contain only a-z, A-Z, 0-9, `-`, `.`) [default: template.os] + -a, --package Name of the package (must contain only a-z, 0-9, `-`) [default: DIR] + -u, --publisher Name of the publisher (must contain only a-z, 0-9, `-`, `.`) [default: template.os] -l, --language Programming language of the template [default: rust] [possible values: rust] -t, --template