Task

Write a specification and add it to the mdbook docs for psibase

Specification

Access to database operations

To enable database actions within plugins, a plugin must import database read/write functionality.

Read/write functionality is provided by a system plugin in the clientdata namespace. That plugin provides a high level key/value API for plugins to use that is specific to psibase plugins.

As an MVP implementation, the API will simply provide a get/set implementation such as:

    set      : func(key : string, value : string) -> result<_, error>;
    get      : func(key : string) -> result<string, error>;

Design implications

There is actually no standardized wasi-keyvalue interface (The proposal is still in stage 2 at the time of writing), so any interface we enable today will be subject to future change. This design specifies that plugins should import a custom psibase-plugin-specific API that itself leverages the wasi-keyvalue standard.

Host provided functionality

The clientdata plugin must itself import functionality that allows it to interact with some persistent storage layer.

This host functionality is a browser shim implementation of the wasi-keyvalue API. Technically, any plugin can import this API and use it directly. But using the standard clientdata plugin simplifies the integration (uses standard error types, exposes a more convenient interface).

The wasi-keyvalue implementation currently uses LocalStorage as its data backing, because it is a synchronous interface which is easiest to integrate with wasm.

Persistence

When private user data is written, it is immediately persisted.

Concurrency

All reads/writes are currently synchronous, with no concurrency.

Synchronization across devices

Plugins all run within the domain of the supervisor, which ensures that all plugin data is written-to/read-from a storage backing tied to the supervisor domain. Cloning storage in the supervisor domain between TLDs is a way to synchronize plugin data across devices.