Skip to content

seal.md

Latest commit

 

History

History
1147 lines (870 loc) · 41.5 KB

seal.md

File metadata and controls

1147 lines (870 loc) · 41.5 KB

================ CODE SNIPPETS

TITLE: Install and Run Locally DESCRIPTION: Commands to install dependencies and start the development server for the frontend application.

SOURCE: https://github.com/mystenlabs/seal/blob/main/examples/README.md

LANGUAGE: bash CODE:

cd frontend
pnpm install
pnpm dev

TITLE: Setting Up Pre-commit Hooks DESCRIPTION: Steps to install and configure Git pre-commit hooks for linting and testing code before committing. This includes installing Rust, nextest, and pre-commit itself.

SOURCE: https://github.com/mystenlabs/seal/blob/main/CONTRIBUTING.md

LANGUAGE: shell CODE:

1. Install [Rust](https://www.rust-lang.org/tools/install).
2. Install [nextest](https://nexte.st/).
3. [Install pre-commit](https://pre-commit.com/#install) using `pip` or your OS's package manager.
4. Run `pre-commit install -c .pre-commit-config-example.yaml` in the repository.

LANGUAGE: yaml CODE:

# Example of a custom .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: black
        name: black
        entry: black
        language: system
        types: [python]
      - id: ruff
        name: ruff
        entry: ruff format
        language: system
        types: [python]
      - id: cargo-check
        name: cargo check
        entry: cargo check
        language: system
        types: [rust]

# To use a custom configuration:
# 1. Create a file .pre-commit-config.yaml
# 2. Run `pre-commit install -c .pre-commit-config.yaml`

TITLE: Start Seal Key Server in Open Mode (Docker) DESCRIPTION: Starts the Seal key server in Open mode using Docker. Builds the Docker image and runs it, mounting the configuration file and setting environment variables for the configuration path and master key.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

docker build -t seal-key-server . --build-arg GIT_REVISION="$(git describe --always --abbrev=12 --dirty --exclude '*')"

docker run -p 2024:2024 -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
   -e MASTER_KEY=<MASTER_KEY> \
   seal-key-server

TITLE: Sui CLI Commands for Move Development DESCRIPTION: Demonstrates the basic Sui CLI commands used for building and publishing Move code, typically found in example directories.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

cd examples/move
sui move build
sui client publish

TITLE: Run Key Server DESCRIPTION: Commands to run the key server with specified environment variables for master key and configuration path. Includes examples for direct execution and Docker.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

# MASTER_KEY=<MASTER_SEED> CONFIG_PATH=crates/key-server/key-server-config.yaml cargo run --bin key-server 

MASTER_KEY=0x680d7268095510940a3cce0d0cfdbd82b3422f776e6da46c90eb36f25ce2b30e CONFIG_PATH=crates/key-server/key-server-config.yaml cargo run --bin key-server

LANGUAGE: docker CODE:

docker run -p 2024:2024 \
  -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
  -e MASTER_KEY=<MASTER_SEED> \
  seal-key-server

TITLE: Key Server Configuration DESCRIPTION: Example YAML configuration for the key server in permissioned mode. It specifies the server mode and initializes with an empty client configuration.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: yaml CODE:

server_mode: !Permissioned
  client_configs:

TITLE: Start Seal Key Server in Open Mode (CLI) DESCRIPTION: Starts the Seal key server in Open mode using the command line. Requires setting environment variables for the master key and configuration path. The configuration file specifies network, mode, and the key server object ID.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

CONFIG_PATH=crates/key-server/key-server-config.yaml MASTER_KEY=<MASTER_KEY> cargo run --bin key-server

TITLE: Transfer Key Server Object DESCRIPTION: Example Sui CLI command to transfer a key server object to a new owner. This is a prerequisite for importing the key to a different key server.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ sui transfer --object-id <KEY_SERVER_OBJECT_ID_0> --to <NEW_OWNER_ADDRESS>

TITLE: Start Seal Key Server in Open Mode (CLI) DESCRIPTION: Starts the Seal key server in Open mode using the command line. Requires setting environment variables for the master key and configuration path. The configuration file must specify the network, mode as '!Open', and the key server object ID.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ CONFIG_PATH=crates/key-server/key-server-config.yaml MASTER_KEY=<MASTER_KEY> cargo run --bin key-server

TITLE: Start Seal Key Server in Open Mode (Docker) DESCRIPTION: Starts the Seal key server in Open mode using Docker. This involves building the Docker image and running a container, mounting the configuration file and setting environment variables for the configuration path and master key.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ docker build -t seal-key-server . --build-arg GIT_REVISION="$(git describe --always --abbrev=12 --dirty --exclude '*')"

$ docker run -p 2024:2024 -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
   -e MASTER_KEY=<MASTER_KEY> \
   seal-key-server

TITLE: Custom CSS Reset DESCRIPTION: A custom CSS reset based on Josh's work, ensuring a consistent starting point for web applications. It sets box-sizing, removes default margins, and styles typography and media elements.

SOURCE: https://github.com/mystenlabs/seal/blob/main/examples/frontend/index.html

LANGUAGE: css CODE:

/* Josh's Custom CSS Reset https://www.joshwcomeau.com/css/custom-css-reset/ */ 
*, *::before, *::after { box-sizing: border-box; } 
* { margin: 0; } 
body { line-height: 1.5; -webkit-font-smoothing: antialiased; } 
img, picture, video, canvas, svg { display: block; max-width: 100%; } 
input, button, textarea, select { font: inherit; } 
p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; } 
#root, #__next { isolation: isolate; }

TITLE: Key Server Log Output DESCRIPTION: Example log output from the key server indicating unassigned derived public keys, which are used for client registration.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

2025-06-15T02:02:56.303459Z  INFO key_server: Unassigned derived public key with index 0: "<PUBKEY_0>"
2025-06-15T02:02:56.303957Z  INFO key_server: Unassigned derived public key with index 1: "<PUBKEY_1>"
2025-06-15T02:02:56.304418Z  INFO key_server: Unassigned derived public key with index 2: "<PUBKEY_2>"

TITLE: Import Key Configuration DESCRIPTION: Example configuration for importing a client master key into a new key server. It specifies the key source via an environment variable, the key server object ID, and associated package IDs.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: yaml CODE:

- name: "bob"
  client_master_key: !Imported
    env_var: "BOB_BLS_KEY"
  key_server_object_id: "<KEY_SERVER_OBJECT_ID_0>"
  package_ids:
    - "0x2222222222222222222222222222222222222222222222222222222222222222"

TITLE: Key Server Configuration (Permissioned Mode) DESCRIPTION: Example YAML configuration for the key server in permissioned mode. It specifies the server mode and initializes with an empty client configuration.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: yaml CODE:

server_mode: !Permissioned
  client_configs:

TITLE: Import Client Master Key Configuration DESCRIPTION: Provides an example YAML configuration for importing a client master key into a new key server. It specifies the key source, object ID, and associated packages.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: yaml CODE:

- name: "bob"
  client_master_key: !Imported
    env_var: "BOB_BLS_KEY"
  key_server_object_id: "<KEY_SERVER_OBJECT_ID_0>"
  package_ids:
    - "0x2222222222222222222222222222222222222222222222222222222222222222"

TITLE: On-chain Decryption with Move DESCRIPTION: References the use of derived keys for on-chain decryption in Move, pointing to an example file for implementation details.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: move CODE:

On-chain decryption in Move is supported using derived keys. For an example, see [voting.move](./move/patterns/sources/voting.move).

TITLE: Key Server Health and Service Endpoints DESCRIPTION: Provides example cURL commands to check the health of the key server and to interact with its service endpoint. The service endpoint can be used to get the latest SDK version information.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

curl http://0.0.0.0:2024/health

curl --header "Client-Sdk-Version: x.x.x" http://0.0.0.0:2024/v1/service # lastest sdk version from https://www.npmjs.com/package/@mysten/seal

TITLE: Unassigned Derived Public Keys Log DESCRIPTION: Example log output from the key server indicating unassigned derived public keys with their respective indices.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

2025-06-15T02:02:56.303459Z  INFO key_server: Unassigned derived public key with index 0: "<PUBKEY_0>"
2025-06-15T02:02:56.303957Z  INFO key_server: Unassigned derived public key with index 1: "<PUBKEY_1>"
2025-06-15T02:02:56.304418Z  INFO key_server: Unassigned derived public key with index 2: "<PUBKEY_2>"

TITLE: Seal Proxy Correct Bearer Token Log DESCRIPTION: Example log output from seal-proxy when a correct Bearer token is provided, showing a 200 status and acceptance.

SOURCE: https://github.com/mystenlabs/seal/blob/main/crates/seal-proxy/README.md

LANGUAGE: rust CODE:

seal-proxy  | 2025-07-18T21:55:17.199397Z  INFO tower_http::trace::on_response: finished processing request latency=0.001276666 s status=200
seal-proxy  | 2025-07-18T21:55:22.193788Z  INFO seal_proxy::middleware: auth_header: "Bearer abcdefghijklmnopqrstuvwxyz"
seal-proxy  | 2025-07-18T21:55:22.193805Z  INFO seal_proxy::allowers: Accepted Request from: "sample-token"

TITLE: Add Client Configuration DESCRIPTION: Example YAML snippet for adding a client's configuration. It includes the client's master key derived from a specific index, the key server object ID, and allowed package IDs.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: yaml CODE:

- name: "alice"
  client_master_key: !Derived
    derivation_index: 0
  key_server_object_id: "<KEY_SERVER_OBJECT_ID_0>"
  package_ids:
    - "0x1111111111111111111111111111111111111111111111111111111111111111"

TITLE: Add Client Entry to Config DESCRIPTION: Example YAML snippet showing how to add a client configuration entry. This includes the client's master key (derived), the key server object ID, and allowed package IDs.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: yaml CODE:

- name: "alice"
  client_master_key: !Derived
    derivation_index: 0
  key_server_object_id: "<KEY_SERVER_OBJECT_ID_0>"
  package_ids:
    - "0x1111111111111111111111111111111111111111111111111111111111111111"

TITLE: Update Key Server Object URL DESCRIPTION: Example Sui CLI command for the new owner to update the key server object's URL to point to their key server after a transfer.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ sui client call --function update --module key_server --package <PACKAGE_ID> --args <KEY_SERVER_OBJECT_ID_0> https://<NEW_URL>

TITLE: Seal Proxy Incorrect Bearer Token Log DESCRIPTION: Example log output from seal-proxy when an incorrect Bearer token is provided, showing a 401 status and rejection.

SOURCE: https://github.com/mystenlabs/seal/blob/main/crates/seal-proxy/README.md

LANGUAGE: rust CODE:

seal-proxy  | 2025-07-18T21:51:50.471395Z  INFO tower_http::trace::on_response: finished processing request latency=0.000157083 s status=401
seal-proxy  | 2025-07-18T21:51:55.462979Z  INFO seal_proxy::middleware: auth_header: "Bearer 1234567890"
seal-proxy  | 2025-07-18T21:51:55.462995Z  INFO seal_proxy::allowers: Rejected Bearer Token: "1234567890"
seal-proxy  | 2025-07-18T21:51:55.462996Z  INFO seal_proxy::middleware: invalid token, rejecting request

TITLE: Symmetric Decryption Example DESCRIPTION: Demonstrates how to symmetrically decrypt a message using a provided key and an encrypted object. The encrypted object contains the data to be decrypted, and the key is used for the decryption process.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

cargo run --bin seal-cli symmetric-decrypt --key e39651e5aa01949ba5174c67a2c37f58ee8217392ba2275a5789f0ac2c3540d8 0000000000000000000000000000000000000000000000000000000000000000000d53e66d756e6472206672f3f069030000000000000000000000000000000000000000000000000000000000000001010000000000000000000000000000000000000000000000000000000000000002020000000000000000000000000000000000000000000000000000000000000003030200841b3a59241e099e8b8d9cec1d531b1e8fe4b4170433e30d9aaa9fc764201f69e589a0b2a0e65bfb279d4b25ee1ce8141812bfb785abdb05134c3958f53c2e81e7bc06e5c1f1ebd7e489b5cf652216b13e6b7c2b13da70a4a7c05c3544a1ddf703b627cb3268d74c74ead83fb827c60fa23c1d192fb8a7db50ea8721bf7c95bd1748b5ed7da6873f4a5b539cb16085e5cd174206db776c04902c7d8c02d6fa47aada89c2fa0692973a83a7a900f2b0dd7f7475e55095d0df7b0483ae1192761d368985e51d72597df02764c654536130c905a8de4a6c9169643e9dd01efab17a9200723b7d7b2ede8924cfb3687a0c41599b87bebc9d913d8eb81a2027ba8286a7b2cd9f5303b6b551fa545189e2f13cb65642b66595ca4256f42cdda2ac78af39abde06184da29131437e1417ebb35c7136d2c74b8ab9fa4147077bbcdbfafc2b05458792eefe0424fedef10247b8b3c787e7772800

TITLE: Seal Access Control Approval Function DESCRIPTION: An example of a seal_approve* function in Move, demonstrating access control logic based on the equality of counter values. This function is side-effect free and used for Seal evaluation.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: move CODE:

struct Counter {
    id: UID,
    count: u64,
}

public fun increment(counter: &mut Counter) {
    counter.count = counter.count + 1;
}

entry fun seal_approve(id: vector<u8>, cnt1: &Counter, cnt2: &Counter) {
    assert!(cnt1.count == cnt2.count, ENoAccess);
    ...

TITLE: IBE Algorithms DESCRIPTION: Defines the core algorithms of an Identity-Based Encryption (IBE) scheme: Setup, Derive, Encrypt, and Decrypt. These algorithms form the cryptographic foundation for Seal's data security.

SOURCE: https://github.com/mystenlabs/seal/blob/main/Design.md

LANGUAGE: APIDOC CODE:

IBE Scheme Algorithms:

Setup: Generates a master secret key `msk` and a master public key `mpk`.
Derive(msk, id): Given a master secret key and an identity `id` (string or byte array), generates a derived secret key `sk` for that identity.
Encrypt(mpk, id, m): Given a public key, an identity and a message, returns an encryption `c`.
Decrypt(sk, c): Given a derived secret key and a ciphertext, compute the message `m`.

Correctness Condition: For any `id` and `m`, `(msk, mpk) ← Setup()` and `c ← Encrypt(mpk, id, m)` we have `Decrypt(Derive(msk, id, m), c) = m`.

TITLE: Decrypt Data with SessionKey DESCRIPTION: Shows how to construct a transaction for evaluating seal_approve functions and then use the client's decrypt function with the encrypted data, session key, and transaction bytes to get the decrypted data.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: typescript CODE:

// Create the Transaction for evaluating the seal_approve function.
const tx = new Transaction();
tx.moveCall({
    target: `${packageId}::${moduleName}::seal_approve`,
    arguments: [
        tx.pure.vector("u8", fromHEX(id)),
        // other arguments
   ]
 });
const txBytes = tx.build( { client: suiClient, onlyTransactionKind: true })
const decryptedBytes = await client.decrypt({
    data: encryptedBytes,
    sessionKey,
    txBytes,
});

TITLE: Seal Time-Lock Encryption Example DESCRIPTION: A Move module demonstrating time-lock encryption using Seal. It defines an access control function seal_approve that enforces time-based access to encrypted data.

SOURCE: https://github.com/mystenlabs/seal/blob/main/Design.md

LANGUAGE: move CODE:

module patterns::tle;

use sui::bcs;
use sui::clock;

const ENoAccess : u64 = 1;

/////////////////////////////////////////////
/// Access control
/// The IBE identity being used: [pkg id][bcs::to_bytes(time)]
/// The following function accepts only the inner identity, i.e., [bcs::to_bytes(time)], and Seal extends it with the namespace.
entry fun seal_approve(id: vector<u8>, c: &clock::Clock) {
    // Convert the identity to u64.
    let mut prepared: BCS = bcs::new(id);
    let t = prepared.peel_u64();
    let leftovers = prepared.into_remainder_bytes();

    // Check that the time has passed and the entire identity is consumed.
    assert!((leftovers.length() == 0) && (c.timestamp_ms() >= t), ENoAccess);
}

TITLE: Seal Move Package - Time-Lock Encryption Example DESCRIPTION: A Move module demonstrating time-lock encryption using Seal. It defines an access control function seal_approve that enforces time-based access to derived keys.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/Design.md

LANGUAGE: move CODE:

module patterns::tle;

use sui::bcs;
use sui::clock;

const ENoAccess : u64 = 1;

/////////////////////////////////////////////
/// Access control
/// The IBE identity being used: [pkg id][bcs::to_bytes(time)]
/// The following function accepts only the inner identity, i.e., [bcs::to_bytes(time)], and Seal extends it with the namespace.
entry fun seal_approve(id: vector<u8>, c: &clock::Clock) {
    // Convert the identity to u64.
    let mut prepared: BCS = bcs::new(id);
    let t = prepared.peel_u64();
    let leftovers = prepared.into_remainder_bytes();

    // Check that the time has passed and the entire identity is consumed.
    assert!((leftovers.length() == 0) && (c.timestamp_ms() >= t), ENoAccess);
}

TITLE: IBE Algorithms DESCRIPTION: Defines the core algorithms of an Identity-Based Encryption (IBE) scheme: Setup, Derive, Encrypt, and Decrypt. These algorithms are fundamental to how Seal encrypts and decrypts data based on identities.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/Design.md

LANGUAGE: APIDOC CODE:

Setup: Generates a master secret key `msk` and a master public key `mpk`.
Derive(msk, id): Given a master secret key and an identity `id` (string or byte array), generates a derived secret key `sk` for that identity.
Encrypt(mpk, id, m): Given a public key, an identity and a message, returns an encryption `c`.
Decrypt(sk, c): Given a derived secret key and a ciphertext, compute the message `m`.
Correctness: For any `id` and `m`, `(msk, mpk) ← Setup()` and `c ← Encrypt(mpk, id, m)` we have `Decrypt(Derive(msk, id, m), c) = m`.

TITLE: Initialize SealClient DESCRIPTION: Demonstrates how to initialize the SealClient with SuiClient and server configurations. It shows how to fetch allowlisted key servers and configure their object IDs and weights. The verifyKeyServers option is also highlighted.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: typescript CODE:

const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') });

// Replace this with a list of custom key server object IDs.
const serverObjectIds = getAllowlistedKeyServers('testnet');

const client = new SealClient({
  suiClient,
  serverConfigs: serverObjectIds.map((id) => ({
    objectId: id,
    weight: 1,
  })),
  verifyKeyServers: false,
});

TITLE: Local Documentation Preview with MkDocs DESCRIPTION: Instructions to set up and run a local development server for previewing documentation changes using MkDocs and Material for MkDocs.

SOURCE: https://github.com/mystenlabs/seal/blob/main/CONTRIBUTING.md

LANGUAGE: shell CODE:

pip install mkdocs-material

# or
brew install mkdocs-material

# From the root of the repository, run:
mkdocs serve

TITLE: Run Key Server with Docker DESCRIPTION: Demonstrates running the Seal key server using Docker, mounting the configuration file and setting environment variables for keys.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

docker run -p 2024:2024 \
  -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
  -e BOB_BLS_KEY=<CLIENT_MASTER_KEY> \
  -e MASTER_KEY=<MASTER_SEED> \
  seal-key-server

TITLE: Sui CLI Build and Publish DESCRIPTION: Demonstrates how to build and publish Move code using the Sui CLI, a common process for deploying smart contracts on the Sui blockchain.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

cd examples/move
sui move build
sui client publish

TITLE: Run Key Server with Environment Variables DESCRIPTION: Shows how to run the Seal key server using a configuration file and environment variables for the master key and client master key.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

CONFIG_PATH=crates/key-server/key-server-config.yaml BOB_BLS_KEY=<CLIENT_MASTER_KEY> MASTER_KEY=<MASTER_SEED> cargo run --bin key-server

TITLE: Local End-to-End Testing with Docker Compose DESCRIPTION: Commands to set up and run the local end-to-end test environment for seal-proxy using Docker Compose.

SOURCE: https://github.com/mystenlabs/seal/blob/main/crates/seal-proxy/README.md

LANGUAGE: bash CODE:

cd docker/seal-proxy/local-test
docker compose up --build

TITLE: Run Key Server DESCRIPTION: Commands to run the key server with the master key and configuration path set as environment variables. The server will list unassigned derived public keys upon startup.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

# MASTER_KEY=<MASTER_SEED> CONFIG_PATH=crates/key-server/key-server-config.yaml cargo run --bin key-server 

$ MASTER_KEY=0x680d7268095510940a3cce0d0cfdbd82b3422f776e6da46c90eb36f25ce2b30e CONFIG_PATH=crates/key-server/key-server-config.yaml cargo run --bin key-server

TITLE: SealClient Initialization and Configuration DESCRIPTION: Initializes the SealClient with SuiClient and server configurations. Allows for custom key server lists and optional verification.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: typescript CODE:

const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') });

// Replace this with a list of custom key server object IDs.
const serverObjectIds = getAllowlistedKeyServers('testnet');

const client = new SealClient({
  suiClient,
  serverConfigs: serverObjectIds.map((id) => ({
    objectId: id,
    weight: 1,
  })),
  verifyKeyServers: false,
});

TITLE: Seal SDK API Documentation DESCRIPTION: Provides an overview of the Seal SDK's core functionalities, including client initialization, encryption, and key server management.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: APIDOC CODE:

SealClient:
  __init__(suiClient: SuiClient, serverConfigs: ServerConfig[], verifyKeyServers: boolean)
    suiClient: An instance of SuiClient for interacting with the Sui network.
    serverConfigs: An array of ServerConfig objects, each containing objectId, weight, and optional apiKeyName and apiKey.
    verifyKeyServers: A boolean flag to enable or disable key server verification.

  encrypt(options: EncryptOptions)
    options:
      threshold: number - The encryption threshold.
      packageId: string - The package ID of the deployed contract.
      id: string - The ID associated with the access control policy.
      data: any - The data to encrypt.
    Returns: Promise<{ encryptedObject: Uint8Array, key: Uint8Array }> - The encrypted object and the symmetric key.

getAllowlistedKeyServers(network: string): string[]
  network: The Sui network ('testnet', 'mainnet', etc.).
  Returns: An array of allowlisted key server object IDs.

EncryptedObject.parse(encryptedBytes: Uint8Array): EncryptedObject
  encryptedBytes: The byte array representing the encrypted object.
  Returns: An EncryptedObject instance containing metadata.

TITLE: Run Key Server with Environment Variables DESCRIPTION: Command to run the Seal key server using a specific configuration path and providing the client master key and master seed via environment variables.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ CONFIG_PATH=crates/key-server/key-server-config.yaml BOB_BLS_KEY=<CLIENT_MASTER_KEY> MASTER_KEY=<MASTER_SEED> cargo run --bin key-server

TITLE: Fetch Multiple Keys Efficiently DESCRIPTION: Illustrates using the fetchKeys function with a multi-command PTB to retrieve multiple keys more efficiently, reducing the number of requests to key servers.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: typescript CODE:

await client.fetchKeys({
    ids: [id1, id2],
    txBytes: txBytesWithTwoSealApproveCalls,
    sessionKey,
    threshold: 2,
});

TITLE: Seal Key Server Modes and Providers (Testnet) DESCRIPTION: Details the 'Open' and 'Permissioned' modes for Seal key servers and lists verified providers for the testnet. Includes URLs and Object IDs for each provider and mode.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/Pricing.md

LANGUAGE: APIDOC CODE:

Seal Key Server Modes:

Open Mode:
  - Description: Lets anyone request keys for any access policy package, using a shared master key. Ideal for public or trial use.
  - Use Case: Experimentation, development, and testing.

Permissioned Mode:
  - Description: Restricts access to approved access policy packages per client, each with a dedicated master key. Supports secure key server rotation or switching. Designed for dedicated or commercial use.
  - Use Case: Dedicated or commercial use, requiring client-specific access control.

Verified Testnet Key Servers:

Mysten Labs:
  - Mode: Open
  - Servers:
    - mysten-testnet-1: https://seal-key-server-testnet-1.mystenlabs.com
    - mysten-testnet-2: https://seal-key-server-testnet-2.mystenlabs.com
  - Notes: Source-based rate limit configured, cannot be changed for any client.

Ruby Nodes:
  - Open Mode:
    - URL: https://free-eu-central-1.api.rubynodes.io
    - Object Id: 0x781389fae54633649d78b731b708c5b363cf7fa4753a48997d4f6f82d5cc5b98
  - Permissioned Mode:
    - URL: https://starter-eu-central-1.api.rubynodes.io
    - Notes: Contact provider to configure client and generate unique key server object id.

NodeInfra:
  - Open Mode:
    - URL: https://open-seal-testnet.nodeinfra.com
    - Object Id: 0x5466b7df5c15b508678d51496ada8afab0d6f70a01c10613123382b1b8131007
  - Permissioned Mode:
    - URL: https://seal-testnet.nodeinfra.com
    - Notes: Contact provider to configure client and generate unique key server object id.

Studio Mirai:
  - Open Mode:
    - URL: https://public.key-server.testnet.seal.mirai.cloud
    - Object Id: 0x27cf65cfd514e9fad1211c2f6e164b59c000be43466088faeb4a65952b6bfb99
  - Permissioned Mode:
    - URL: https://private.key-server.testnet.seal.mirai.cloud
    - Notes: Contact provider to configure client and generate unique key server object id.

Overclock:
  - Open Mode:
    - URL: https://seal-testnet-open.overclock.run
    - Object Id: 0x9c949e53c36ab7a9c484ed9e8b43267a77d4b8d70e79aa6b39042e3d4c434105
  - Permissioned Mode:
    - URL: https://seal-testnet-permissioned.overclock.run
    - Notes: Contact provider to configure client and generate unique key server object id.

H2O Nodes:
  - Open Mode:
    - URL: https://seal-open.sui-testnet.h2o-nodes.com
    - Object Id: 0x39cef09b24b667bc6ed54f7159d82352fe2d5dd97ca9a5beaa1d21aa774f25a2
  - Permissioned Mode:
    - URL: https://seal-permissioned.sui-testnet.h2o-nodes.com
    - Notes: Contact provider to configure client and generate unique key server object id.

Triton One:
  - Open Mode:
    - URL: https://seal.testnet.sui.rpcpool.com
    - Object Id: 0x4cded1abeb52a22b6becb42a91d3686a4c901cf52eee16234214d0b5b2da4c46
  - Permissioned Mode:
    - URL: https://seal.testnet.sui.rpcpool.com/private
    - Notes: Contact provider to configure client and generate unique key server object id.

Important Notes:
  - Testnet key servers are for developer testing only and lack availability guarantees or SLAs.
  - Avoid using testnet servers for data requiring reliable future access.
  - Key server URLs may change; the Object Id is the persistent reference to the on-chain object containing the latest URL.

TITLE: SealClient and Encryption Methods DESCRIPTION: Provides an overview of the SealClient's functionality, focusing on the encryption process. It details the parameters required for the encrypt method, including threshold, package ID, access control policy ID, and the data to be encrypted. It also explains the return values: the encrypted object and the symmetric key, and how to parse the encrypted object.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: APIDOC CODE:

SealClient:
  __init__(suiClient: SuiClient, serverConfigs: ServerConfig[], verifyKeyServers: boolean = false)
    suiClient: An instance of SuiClient for interacting with the Sui network.
    serverConfigs: An array of ServerConfig objects, each specifying a key server's objectId and weight. Optional fields apiKeyName and apiKey can be included for API key authentication.
    verifyKeyServers: A boolean flag to enable verification of key server URLs against their on-chain registered public keys. Defaults to false.

  encrypt(options: EncryptOptions): Promise<{ encryptedObject: Uint8Array, key: Uint8Array }>
    options:
      threshold: number - The minimum number of key servers required for decryption.
      packageId: Uint8Array - The package ID of the deployed contract containing seal_approve* functions.
      id: Uint8Array - The ID associated with the access control policy.
      data: Uint8Array - The data to encrypt.
    Returns:
      encryptedObject: Uint8Array - The encrypted data.
      key: Uint8Array - The symmetric key used for encryption, which can be used for backup or manual decryption.

  EncryptedObject.parse(encryptedBytes: Uint8Array): EncryptedObject
    encryptedBytes: The byte array returned by the encrypt method.
    Returns:
      An EncryptedObject instance containing metadata such as the ID and other associated fields.

TITLE: Seal Proxy Usage DESCRIPTION: Command-line usage for the seal-proxy, including configuration file paths for settings and bearer tokens.

SOURCE: https://github.com/mystenlabs/seal/blob/main/crates/seal-proxy/README.md

LANGUAGE: rust CODE:

seal-proxy --config=seal-proxy.yaml --bearer-tokens-path=bearer-tokens.yaml

TITLE: Register Client On-Chain DESCRIPTION: Command to register a new key server on-chain using the create_and_transfer_v1 function from the seal::key_server module. This associates a derived public key with a client.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

-- Replace `0` with the appropriate derivation index and derived public key for the nth client.

$ sui client call --function create_and_transfer_v1 --module key_server --package <PACKAGE_ID> --args <YOUR_SERVER_NAME> https://<YOUR_URL> 0 <PUBKEY_0>

# outputs object of type key_server::KeyServer <KEY_SERVER_OBJECT_ID_0>

TITLE: Run Key Server with Docker DESCRIPTION: Docker command to run the Seal key server, mounting the configuration file and providing necessary keys via environment variables. Exposes port 2024 for the server.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ docker run -p 2024:2024 \
  -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
  -e BOB_BLS_KEY=<CLIENT_MASTER_KEY> \
  -e MASTER_KEY=<MASTER_SEED> \
  seal-key-server

TITLE: Transfer Key Server Object using Sui CLI DESCRIPTION: Illustrates the process of transferring a key server object to a new owner using the Sui CLI. This involves a transfer command and then an update call to set the new URL.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

sui transfer --object-id <KEY_SERVER_OBJECT_ID_0> --to <NEW_OWNER_ADDRESS>
sui client call --function update --module key_server --package <PACKAGE_ID> --args <KEY_SERVER_OBJECT_ID_0> https://<NEW_URL>

TITLE: Seal Client API DESCRIPTION: Provides an overview of the SealClient's capabilities, including caching for performance optimization and the importance of reusing client instances. It also mentions the fetchKeys function for efficient retrieval of multiple keys.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: APIDOC CODE:

SealClient:
  decrypt(data: EncryptedData, sessionKey: SessionKey, txBytes: Uint8Array): Promise<Uint8Array>
    - Decrypts data using the provided session key and transaction bytes.
    - Caches retrieved keys for performance.

  fetchKeys(ids: string[], txBytes: Uint8Array, sessionKey: SessionKey, threshold: number): Promise<KeyMap>
    - Retrieves multiple keys efficiently using a multi-command PTB.
    - Recommended for scenarios requiring multiple keys.
    - Parameters:
      - ids: Array of key identifiers to fetch.
      - txBytes: Transaction bytes containing seal_approve calls.
      - sessionKey: The initialized SessionKey object.
      - threshold: The minimum number of approvals required.

  Caching:
    - The SealClient caches keys to optimize performance for repeated decryptions of the same ID.
    - Reusing the same client instance reduces backend calls and latency.

  Rate Limiting:
    - Key servers may apply rate limiting. Design applications to minimize key retrieval frequency.

  Error Handling:
    - InvalidParameter error may occur if a recently created on-chain object is used. Retry after a short delay.

TITLE: Register Client On-Chain DESCRIPTION: Sui CLI command to register a new key server on-chain using the create_and_transfer_v1 function. This links a derived public key to a server object.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

-- Replace `0` with the appropriate derivation index and derived public key for the nth client.

sui client call --function create_and_transfer_v1 --module key_server --package <PACKAGE_ID> --args <YOUR_SERVER_NAME> https://<YOUR_URL> 0 <PUBKEY_0>

# outputs object of type key_server::KeyServer <KEY_SERVER_OBJECT_ID_0>

TITLE: Export Client Key using seal-cli DESCRIPTION: Demonstrates how to export a client key using the seal-cli tool. This involves specifying the master seed and the derivation index of the key to be exported. The output includes the master key and public key.

SOURCE: https://github.com/mystenlabs/seal/blob/main/UsingSeal.md

LANGUAGE: shell CODE:

cargo run --bin seal-cli derive-key --seed <MASTER_SEED> --index 0

Master key: <CLIENT_MASTER_KEY>
Public key: <CLIENT_MASTER_PUBKEY>

TITLE: Verified Testnet Key Servers DESCRIPTION: Lists verified key servers available for testnet usage, categorized by provider and mode ('Open' or 'Permissioned'). Each entry includes the server URL and a unique Object ID, which serves as the source of truth for the server's configuration.

SOURCE: https://github.com/mystenlabs/seal/blob/main/Pricing.md

LANGUAGE: APIDOC CODE:

Mysten Labs Testnet:
  - mysten-testnet-1: https://seal-key-server-testnet-1.mystenlabs.com
  - mysten-testnet-2: https://seal-key-server-testnet-2.mystenlabs.com

Ruby Nodes:
  - Open Mode:
    URL: https://free-eu-central-1.api.rubynodes.io
    Object Id: 0x781389fae54633649d78b731b708c5b363cf7fa4753a48997d4f6f82d5cc5b98
  - Permissioned Mode:
    URL: https://starter-eu-central-1.api.rubynodes.io
    Contact provider for Object Id.

NodeInfra:
  - Open Mode:
    URL: https://open-seal-testnet.nodeinfra.com
    Object Id: 0x5466b7df5c15b508678d51496ada8afab0d6f70a01c10613123382b1b8131007
  - Permissioned Mode:
    URL: https://seal-testnet.nodeinfra.com
    Contact provider for Object Id.

Studio Mirai:
  - Open Mode:
    URL: https://public.key-server.testnet.seal.mirai.cloud
    Object Id: 0x27cf65cfd514e9fad1211c2f6e164b59c000be43466088faeb4a65952b6bfb99
  - Permissioned Mode:
    URL: https://private.key-server.testnet.seal.mirai.cloud
    Contact provider for Object Id.

Overclock:
  - Open Mode:
    URL: https://seal-testnet-open.overclock.run
    Object Id: 0x9c949e53c36ab7a9c484ed9e8b43267a77d4b8d70e79aa6b39042e3d4c434105
  - Permissioned Mode:
    URL: https://seal-testnet-permissioned.overclock.run
    Contact provider for Object Id.

H2O Nodes:
  - Open Mode:
    URL: https://seal-open.sui-testnet.h2o-nodes.com
    Object Id: 0x39cef09b24b667bc6ed54f7159d82352fe2d5dd97ca9a5beaa1d21aa774f25a2
  - Permissioned Mode:
    URL: https://seal-permissioned.sui-testnet.h2o-nodes.com
    Contact provider for Object Id.

Triton One:
  - Open Mode:
    URL: https://seal.testnet.sui.rpcpool.com
    Object Id: 0x4cded1abeb52a22b6becb42a91d3686a4c901cf52eee16234214d0b5b2da4c46
  - Permissioned Mode:
    URL: https://seal.testnet.sui.rpcpool.com/private
    Contact provider for Object Id.

TITLE: SessionKey Class DESCRIPTION: Details the SessionKey class, including its creation, initialization with user signatures, and optional parameters like mvr_name for improved user experience and persistence options using IndexedDB.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: APIDOC CODE:

SessionKey:
  create(options: SessionKeyCreateOptions): Promise<SessionKey>
    - Creates a new SessionKey object.
    - Options:
      - address: The Sui address associated with the session.
      - packageId: The Move package ID.
      - ttlMin: Time-to-live for the session in minutes.
      - suiClient: An instance of SuiClient.

  getPersonalMessage(): Uint8Array
    - Retrieves the personal message that needs to be signed by the user.

  setPersonalMessageSignature(signature: Signature):
    - Sets the user's signature to initialize the SessionKey.

  Optional Initialization:
    - Can be initialized with a passed-in Signer in the constructor.

  Optional Parameters:
    - mvr_name: Move Package Registry name for the package. Improves readability of messages shown to the user.

  Persistence:
    - Can be stored in IndexedDB instead of localStorage for persistence across tabs.
    - Provides import and export methods for IndexedDB usage.

TITLE: Key Server CORS Configuration Headers DESCRIPTION: Recommended CORS headers for configuring the Seal key server to allow direct browser requests. Includes origin, methods, and headers for cross-origin communication.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Request-Id, Client-Sdk-Type, Client-Sdk-Version

TITLE: Restart Key Server DESCRIPTION: Commands to restart the key server after configuration changes. This includes running directly with cargo or using Docker.

SOURCE: https://github.com/mystenlabs/seal/blob/main/docs/UsingSeal.md

LANGUAGE: shell CODE:

$ MASTER_KEY=<MASTER_SEED> CONFIG_PATH=crates/key-server/key-server-config.yaml cargo run --bin key-server 

$ docker run -p 2024:2024 \
  -v $(pwd)/crates/key-server/key-server-config.yaml:/config/key-server-config.yaml \
  -e CONFIG_PATH=/config/key-server-config.yaml \
  -e MASTER_KEY=<MASTER_SEED> \
  seal-key-server