diff --git a/docs/cli/Guides/deploy-app/deploy-app-example.md b/docs/cli/Guides/deploy-app/deploy-app-example.md new file mode 100644 index 00000000..762949db --- /dev/null +++ b/docs/cli/Guides/deploy-app/deploy-app-example.md @@ -0,0 +1,175 @@ +--- +id: "deploy-app-example" +title: "Example: Python script" +slug: "/guides/deploy-app/example" +sidebar_position: 1 +--- + +This guide serves as an example to the more general [deployment guide](/cli/guides/deploy-app) and shows how to deploy a Python script on Super Protocol without modifying its code. + +The [simple script](/files/usd_to_crypto.py) used here as an example calculates how much Bitcoin (BTC) and Ether (ETH) can be bought for given amount in US dollars: + +1. Reads the input amount from `input.txt` located in the same directory. +2. Fetches current prices of BTC and ETH using CoinGecko API. +3. Calculates how much BTC and ETH can be bought for this amount of USD. +4. Creates `result.txt` in the same directory and writes the result to it. + +In this deployment, the script will be the solution, and `input.txt` will be the data. + +## Prerequisites + +- Docker +- [SPCTL](/cli) + +### 0. Prepare the files + +Create a local directory `usd_to_crypto`. Download the [example script](/files/usd_to_crypto.py) and rename it to `usd_to_crypto.py`. + +Create a new file `input.txt` to serve as the data input, and add a number—USD amount, for example, `100000`. + +Copy SPCTL and its `config.json` into this directory. + +### 1. Prepare the solution + +Keep in mind that file locations inside a CVM will differ from a local run: + +- Data (`input.txt`) must be found in one of the `/sp/inputs/input-xxxx` directories. +- `result.txt` must be placed into `/sp/output` to be available to download once the execution is finished. + +1.1. Create a new file named `entrypoint.sh` and add the following code: + +```sh title="entrypoint.sh" +#!/bin/sh +set -eu + +# Fixed CVM paths (overridable if needed) +: "${INPUTS_DIR:=/sp/inputs}" +: "${OUTPUT_DIR:=/sp/output}" +: "${SCRIPT_PATH:=/usr/local/bin/usd_to_crypto.py}" + +mkdir -p "${OUTPUT_DIR}" +cd "${OUTPUT_DIR}" + +# Resolve input file +INPUT_FILE="$(find "${INPUTS_DIR}" -mindepth 2 -maxdepth 3 -type f -name 'input.txt' 2>/dev/null | sort | head -n 1 || true)" + +# Make the script's expected input file available in CWD (/sp/output) +rm -f input.txt || true +if [ -n "${INPUT_FILE}" ] && [ -f "${INPUT_FILE}" ]; then + cp -f "${INPUT_FILE}" input.txt +else + # If missing, create an empty file so the Python script emits a clean error + : > input.txt +fi + +# Run the Python script; it reads ./input.txt and writes ./result.txt here (/sp/output) +exec python3 "${SCRIPT_PATH}" +``` + +Create a new file named `Dockerfile` and add the following code: + +```dockerfile title="Dockerfile" +FROM ubuntu:22.04 + +# Non-interactive tzdata install +ENV DEBIAN_FRONTEND=noninteractive + +# System deps +RUN apt-get update && apt-get install -y \ + python3 \ + python3-pip \ + ca-certificates \ + curl \ + jq \ + openssl \ + tzdata \ + sed \ + grep \ + coreutils \ + && rm -rf /var/lib/apt/lists/* + +# Python deps +RUN pip3 install --no-cache-dir requests + +# Put the scripts where your environment expects executables +COPY usd_to_crypto.py /usr/local/bin/usd_to_crypto.py +RUN chmod +x /usr/local/bin/usd_to_crypto.py + +COPY entrypoint.sh /usr/local/bin/entrypoint.sh +RUN chmod +x /usr/local/bin/entrypoint.sh + +# Set /sp as workdir (doesn't matter in this case; entrypoint.sh uses /sp/output as workdir) +WORKDIR /sp + +# Set entrypoint +ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] +``` + +1.2. Build a Docker image: + +```shell +docker build -t usd_to_crypto . +``` + +1.3. Save and archive the image: + +```shell +docker save usd_to_crypto:latest | gzip > usd_to_crypto.tar.gz +``` + +1.4. Upload the archive: + +```shell +./spctl files upload usd_to_crypto.tar.gz \ + --filename usd_to_crypto.tar.gz \ + --output usd_to_crypto.resource.json +``` + +### 2. Prepare data + +2.1. Archive the file: + +```shell +tar -czvf input.tar.gz ./input.txt +``` + +2.2. Upload the archive: + +```shell +./spctl files upload ./input.tar.gz \ +--filename input.tar.gz \ +--output input.resource.json +``` + +### 3. Deploy + +Place an order: + +```shell +./spctl workflows create \ +--tee 7 \ +--solution ./usd_to_crypto.resource.json \ +--data ./input.resource.json +``` + +Find the order ID in the output, for example: + +``` +Workflow was created, TEE order id: ["275510"] +``` + +### 4. Download the result + +Replace `275510` with your order ID: + +```shell +./spctl orders download-result 275510 +``` + +If there is no result for your order yet, wait a couple of minutes and try again. + +Find `output/result.txt` inside the downloaded archive `result.tar.gz`. + +## Support + +If you have any issues or questions, contact Super Protocol on [Discord](https://discord.gg/superprotocol) or via the [contact form](https://superprotocol.zendesk.com/hc/en-us/requests/new). \ No newline at end of file diff --git a/docs/cli/Guides/quick-guide.md b/docs/cli/Guides/deploy-app/index.md similarity index 82% rename from docs/cli/Guides/quick-guide.md rename to docs/cli/Guides/deploy-app/index.md index 89d14492..205961f8 100644 --- a/docs/cli/Guides/quick-guide.md +++ b/docs/cli/Guides/deploy-app/index.md @@ -1,7 +1,7 @@ --- -id: "quick-guide" +id: "deploy-app" title: "Deploy Your App" -slug: "/guides/quick-guide" +slug: "/guides/deploy-app" sidebar_position: 2 --- @@ -18,13 +18,13 @@ This quick guide provides instructions on deploying your own TEE: -| **Location** | **Purpose** | **Access** | +|
**Location**
| **Purpose** |
**Access**
| | :- | :- | :- | -| `/sp/inputs/input-0001`
`/sp/inputs/input-0002`
etc. | Possible data locations | Read-only | -| `/sp/output` | Output directory for results | Write; read own files | +| `/sp/inputs/input-0001`
`/sp/inputs/input-0002`
... | Possible data locations | Read-only | +| `/sp/output` | Output directory for results | Read and write | | `/sp/certs` | Contains the order certificate, private key, and workloadInfo | Read-only | -So, your solution must find the data in `/sp/inputs` and write the results to `/sp/output`. +When you provide multiple data inputs, they are placed in separate directories inside the CVM: the first in `/sp/inputs/input-0001`, the second in `/sp/inputs/input-0002`, and so on. Your solution must find the data in `/sp/inputs` and write the results to `/sp/output`. :::important @@ -32,7 +32,9 @@ Always use absolute paths, such as `/sp/...`. ::: -You can find several Dockerfile examples in the [Super-Protocol/solutions](https://github.com/Super-Protocol/solutions) GitHub repository. +Check the [example](/cli/guides/deploy-app/example) at the end of this guide. + +More Dockerfile examples can be found in the [Super-Protocol/solutions](https://github.com/Super-Protocol/solutions) GitHub repository. ### 1.2. Build a Docker image @@ -124,17 +126,11 @@ Place an order using the [`workflows create`](/cli/commands/workflows/create) co --data ./more-data.resource.json ``` -:::note - -When you provide multiple data inputs, they are placed in separate directories inside the CVM: the first in `/sp/inputs/input-0001`, the second in `/sp/inputs/input-0002`, and so on. - -::: - Find the order ID in the output. ## 4. Download the result -Wait a few minutes and [check the order status](/cli/commands/orders/get): +Wait a few minutes and check the order status: ```shell ./spctl orders get @@ -146,7 +142,7 @@ For example: ./spctl orders get 256587 ``` -If the status is `Done`, the order is ready, and you can [download the order result](/cli/commands/orders/download-result): +If the status is `Done` or `Error`, you can [download the order result](/cli/commands/orders/download-result): ```shell ./spctl orders download-result diff --git a/docs/cli/Guides/tgwui.md b/docs/cli/Guides/tgwui.md index e12f58ef..66ac340a 100644 --- a/docs/cli/Guides/tgwui.md +++ b/docs/cli/Guides/tgwui.md @@ -12,7 +12,7 @@ This guide provides step-by-step instructions for uploading and deploying an AI ## Prerequisites -- [SPCTL](https://docs.develop.superprotocol.com/cli/) +- [SPCTL](/cli/) - BNB and SPPI tokens (opBNB) to pay for transactions and orders ## 1. Prepare @@ -91,19 +91,20 @@ Replace `` with the tunnel order ID from the previous step. ./spctl orders download-result ``` -3.5. Extract the downloaded `result.tar.gz`, open `output/result.json`, and find the domain address. For example: +3.5. Extract the downloaded `result.tar.gz`, open `output/result.json`, and find the domain. For example: ```json title="result.json" "domain":"pret-tons-wade.superprotocol.io" ``` -Your model's web UI will be available at this address. +Your model's web UI will be available at this URL. ## 4. Prepare engine configuration files 4.1. Open the SPCTL's `config.json` and find the `workflow.resultEncryption.key` property that contains the key used for decrypting workflow results; for example: `NapSrwQRz2tL9ZftJbi6DATpCDn0BRImpSStU9xZT/s=`. -4.2. +4.2. Create configuration files: + Create a file named `engine-configuration-tgwui.json` and paste the following: @@ -150,7 +151,7 @@ Your model's web UI will be available at this address. } ``` - + Create a file named `engine-configuration-comfyui.json` and paste the following: ```json title="engine-configuration-comfyui.json" @@ -184,10 +185,10 @@ Save and close the file. ## 5. Deploy the model -5.1. +5.1. Create the main order to deploy your uploaded model: + - Create the main order to deploy your uploaded model: ```shell ./spctl workflows create --tee --solution 25 --solution-configuration ./engine-configuration-tgwui.json --data ./model.resource.json @@ -197,8 +198,7 @@ Save and close the file. Note that `--solution 25` refers to [Text Generation Web UI with GPU support](https://marketplace.superprotocol.com/marketplace/models?offer=offerId%3D25). If you need the CPU version, use `--solution 26` instead. - - Create the main order to deploy your uploaded model: + ```shell ./spctl workflows create --tee --solution 27 --solution-configuration ./engine-configuration-comfyui.json --data ./model.resource.json @@ -231,4 +231,8 @@ The most important statuses (see the [full list](/fundamentals/orders#compute-or - **Processing**: The compute is executing the order inside a TEE. Your model is either already available or will be available soon. - **In Queue**: The order is waiting for the compute to become available. This status appears only if the compute is overloaded with orders. If this status persists for a few minutes, place a new main order the same tunnel order and engine configuration but another compute offer. - **Done**: The order is completed successfully and the model's UI is no longer available. -- **Error**: The order completed with an error. [Download the order results](/cli/commands/orders/download-result) to get more information about the error. \ No newline at end of file +- **Error**: The order completed with an error. [Download the order results](/cli/commands/orders/download-result) to get more information about the error. + +## Support + +If you have any issues or questions, contact Super Protocol on [Discord](https://discord.gg/superprotocol) or via the [contact form](https://superprotocol.zendesk.com/hc/en-us/requests/new). \ No newline at end of file diff --git a/docs/cli/Guides/unsloth.md b/docs/cli/Guides/unsloth.md index 24b46110..70ae7f67 100644 --- a/docs/cli/Guides/unsloth.md +++ b/docs/cli/Guides/unsloth.md @@ -7,11 +7,11 @@ sidebar_position: 5 This guide provides step-by-step instructions for fine-tuning an AI model using the Super Protocol packaging of [Unsloth](https://unsloth.ai/), an open-source framework for LLM fine-tuning and reinforcement learning. -The solution allows you to run fine-tuning within Super Protocol's Trusted Execution Environment (TEE). This provides enhanced security and privacy and enables a range of [confidential collaboration](https://docs.develop.superprotocol.com/cli/guides/multi-party-collab) scenarios. +The solution allows you to run fine-tuning within Super Protocol's Trusted Execution Environment (TEE). This provides enhanced security and privacy and enables a range of [confidential collaboration](/cli/guides/multi-party-collab) scenarios. ## Prerequisites -- [SPCTL](https://docs.develop.superprotocol.com/cli/) +- [SPCTL](/cli/) - Git - BNB and SPPI tokens (opBNB) to pay for transactions and orders diff --git a/docs/cli/Guides/vllm.md b/docs/cli/Guides/vllm.md index a833a22d..d701a650 100644 --- a/docs/cli/Guides/vllm.md +++ b/docs/cli/Guides/vllm.md @@ -9,7 +9,7 @@ This guide provides step-by-step instructions for running an AI model inference ## Prerequisites -- [SPCTL](https://docs.develop.superprotocol.com/cli/) +- [SPCTL](/cli/) - Git - BNB and SPPI tokens (opBNB) to pay for transactions and orders diff --git a/docs/fundamentals/certification.md b/docs/fundamentals/certification.md index a943c6b5..4ef4e184 100644 --- a/docs/fundamentals/certification.md +++ b/docs/fundamentals/certification.md @@ -5,37 +5,67 @@ slug: "/certification" sidebar_position: 6 --- -Super Protocol uses a certification system for signing data, verifying signatures, and ensuring applications operate within a trusted confidential computing environment. Verified data is published on the blockchain on behalf of confidential containers, allowing anyone to validate application integrity and ensure confidentiality. End users only interact with issued certificates and verify signatures, while the complexities of Remote Attestation are seamlessly managed in the background. +The Super Protocol Certification System is a hierarchical infrastructure for managing trust in confidential computing environments. The main purpose of the system is to create a valid chain of X.509 certificates for any applications running in Trusted Execution Environments (TEEs). The Certification System itself also operates within TEEs, ensuring the entire chain is rooted in hardware-based trust. -All the system components are open-source, ensuring transparency and verifiability. +The Certification System performs remote attestation under the hood, but exposes a familiar X.509-style certificate chain on the surface. This allows any verifier (a user, an auditor, or an automated service) to validate that: + +- The execution took place within a TEE. +- The certificate chain leading to the workload is valid and trusted. + +The Certification System can function as an independent, standalone service. In this capacity, it could serve external companies and users who need to establish certificate chains for their own confidential computing applications. + +Note that the system is not responsible for validating what an application does internally. Its primary role is to issue certificates to trusted confidential environments, forming a cryptographically verifiable trust chain. + +All system components are planned to be open-sourced, improving transparency and verifiability. ## Architecture -The backbone of the system is a hierarchical structure of Certification Authorities operating inside Trusted Execution Environments (TEE)—Intel SGX enclaves. +The Certification System is organized as a hierarchy of Certification Authorities (CAs) that establishes trust for TEEs through a standard certificate chain. Every CA operates within a TEE—Intel SGX enclave.

-The Root Certification Authority (*Root CA*) is located at the highest hierarchical level. At the start, Root CA generates a self-signed certificate, embedding the SGX attestation quote. +The chain consists of three levels: + +- Root CA is the top-level certificate authority that establishes the trust anchor for the entire system. At the start, it generates a self-signed certificate that embeds the SGX attestation quote. +- SubRoot CAs are intermediate certificate authorities. They submit their quotes and public keys to the Root CA and request certificates. The Root CA verifies these incoming requests and then issues and signs certificates for the SubRoot CAs. Once a SubRoot CA is certified by the Root CA, it can certify any TEE-backed environment that proves it is actually confidential. +- End certificates are issued to specific workloads, entire Confidential Virtual Machines (CVMs) running in TEEs, and in some other cases. These certificates are not CAs and cannot be used to sign or issue other certificates. + +Each level in the hierarchy receives its certificate from the level above, creating a chain of trust that ultimately traces back to the Root CA. + +## Trusted Loader -SubRoot Certification Authorities (*SubRoot CAs*) are located at the next hierarchical level. These submit their quotes and public keys to the Root CA and request certificates. The Root CA verifies these incoming requests and then issues and signs certificates for the SubRoot CAs. +Trusted Loader is a special service that prepares and launches the workload associated with an order inside a CVM running in a TEE. Loader occupies a privileged position within the execution environment, enabling it to access the platform's underlying attestation capabilities. Workloads themselves do not have such access. -The SubRoot CAs, in turn, issue and sign certificates for orders by request. +Trusted Loader also: + +- Collects hashes of the workload and its components. +- Verifies workload integrity before execution starts. +- Requests end certificates. + +All end certificates are requested and received by Trusted Loader. Other components do not interact directly with Certificate Authorities. Trusted Loader may request certificates in several cases: + +- At startup. The certificate confirms that the confidential environment is correctly configured and that the attestation challenge (TDX, SEV-SNP, etc.) matches expectations. +- When generating session keys. The certificate is included in the session key structures used during execution. +- When forming a TEE Confirmation Block (TCB). The certificate is embedded into TCB, which also includes system information and measurements. +- When deploying an order. An order-specific certificate is issued and delivered, along with cryptographic keys, to the order's execution environment. ## Order certificates -The issuing of order certificates involves Trusted Loader—a software mechanism developed by Super Protocol to load and run applications within a TEE. Trusted Loader operates inside the Confidential VM that executes the order. This Confidential VM may be deployed within a CPU-based or CPU/GPU-augmented TEE using technologies such as Intel TDX, AMD SEV-SNP, NVIDIA Confidential Computing, or others, making the system TEE-agnostic. +Trusted Loader requests a dedicated order-specific certificate when an order is prepared for execution. This certificate includes order-specific data, such as the hash of workload information. -To receive an order certificate, the Trusted Loader sends a request to a SubRoot CA providing the quote and a public key. The SubRoot CA verifies the quote, issues the order certificate, and signs it with the provided public key. +Trusted Loader places the order certificate as a file into the order's execution environment. There, it can be used by the order itself to prove that it was launched within a confidential environment. + +Note that the Certification System does not determine whether a CVM is correct or compromised. If a CVM runs in a confidential environment, it can obtain certificates. However, differences in hashes are visible in the certificate chain and can be detected by any verifying party. ### Order validation -Orders in Super Protocol are created with necessary input data. This execution environment is referred to as *Workload Info*. +Orders in Super Protocol are created with a workload description known as *Workload Info*. -The Workload Info includes an array called `runtimeInfo[]` with metadata about solutions and datasets used in the order. Each such order component has an entry in this array, which includes: +Workload Info includes an array called `runtimeInfo` that contains information about solutions and data associated with the order. Each data and solution component of the order has an entry in this array, which includes: -- Type +- Type (solution or data) - Hash - Size - Signature key hash (optional) @@ -43,9 +73,13 @@ The Workload Info includes an array called `runtimeInfo[]` with metadata about < The hash of the Workload Info is included in the order certificate. -Trusted Loader generates and publishes a report in the blockchain, allowing anyone to validate the order. This order report includes: +Before order execution begins, Trusted Loader checks the integrity of the full workload composition (solutions, data, and configuration). The order proceeds only if this verification succeeds. + +Trusted Loader also generates and publishes a report to the blockchain, allowing any verifier to validate the order. The report includes: - The public components of all the certificates in the chain - Workload Info: - Order creation date - - The `runtimeInfo[]` array \ No newline at end of file + - The `runtimeInfo` array + +The immutable nature of blockchain prevents any further alterations to the report once it is published. The report enables verifiers to confirm what exactly was launched and that the certificate corresponds to that specific workload. \ No newline at end of file diff --git a/docs/fundamentals/images/certification-system-architecture.png b/docs/fundamentals/images/certification-system-architecture.png index 4e4ffd05..32eead65 100644 Binary files a/docs/fundamentals/images/certification-system-architecture.png and b/docs/fundamentals/images/certification-system-architecture.png differ diff --git a/docs/guides/index.md b/docs/guides/index.md index 31dab108..26693316 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -18,12 +18,12 @@ sidebar_position: 0 ## CLI -|
**Guide**
|
**Description**
| -| :- | :- | -| [Configure SPCTL](/cli) | How to set up SPCTL—a Super Protocol CLI tool. | -| [Configure Provider Tools](/cli/guides/provider-tools) | How to set up Provider Tools—a Super Protocol CLI utility for registering providers and creating offers. | -| [Quick Deployment Guide](/cli/guides/quick-guide) | Quick instructions on deploying a solution and data on Super Protocol. | -| [Confidential Collaboration](/cli/guides/multi-party-collab) | A scenario of confidential collaboration on Super Protocol. | +|
**Guide**
|
**Description**
| +| :- | :- | +| [Configure SPCTL](/cli) | How to set up SPCTL—a Super Protocol CLI tool. | +| [Configure Provider Tools](/cli/guides/provider-tools) | How to set up Provider Tools—a Super Protocol CLI utility for registering providers and creating offers. | +| [Quick Deployment Guide](/cli/guides/deploy-app) | Quick instructions on deploying a solution and data on Super Protocol. | +| [Confidential Collaboration](/cli/guides/multi-party-collab) | A scenario of confidential collaboration on Super Protocol. | ### Solutions diff --git a/docusaurus.config.js b/docusaurus.config.js index c3a86fd7..db773ef3 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -42,10 +42,10 @@ const config = { from: "/hackathon", to: "/hackathon/about", }, - /*{ - from: "/colab", - to: "/colab/jupyter", - },*/ + { + from: "/cli/guides/quick-guide", + to: "/cli/guides/deploy-app", + }, ], }, ], diff --git a/src/theme/Layout/index.js b/src/theme/Layout/index.js index eeac7d18..980964c8 100644 --- a/src/theme/Layout/index.js +++ b/src/theme/Layout/index.js @@ -87,9 +87,21 @@ export default function Layout(props) { ᐧ A tunnel client hosts a web server; it remains hidden behind the tunnel server and protected from external threats. + + TEE Confirmation Block (TCB) contains a unique device ID, equipment benchmark results,
various hashes, device signature, and a certificate chain for signature verification.

+ + Trusted Loader generates and publishes TCB on the blockchain every 24 hours. + + + // Stabs and abbreviations + Confidential Virtual Machine + + + Trusted Loader + ); } \ No newline at end of file diff --git a/static/files/usd_to_crypto.py b/static/files/usd_to_crypto.py new file mode 100644 index 00000000..88da57e5 --- /dev/null +++ b/static/files/usd_to_crypto.py @@ -0,0 +1,45 @@ +import requests +import sys + +def main(): + input_file = "input.txt" + output_file = "result.txt" + + try: + # Read the input amount + with open(input_file, "r") as f: + content = f.read().strip() + if not content: + raise ValueError("Input file is empty") + + try: + usd_amount = float(content) + except ValueError: + raise ValueError("Input is not a valid number") + + # Fetch BTC and ETH prices from CoinGecko + url = "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd" + response = requests.get(url, timeout=10) + if response.status_code != 200: + raise RuntimeError(f"API request failed with status code {response.status_code}") + + data = response.json() + btc_price = data["bitcoin"]["usd"] + eth_price = data["ethereum"]["usd"] + + # Calculate how much BTC and ETH can be bought + btc_amount = usd_amount / btc_price + eth_amount = usd_amount / eth_price + + # Write results to output file, rounded to 6 decimals + with open(output_file, "w") as f: + f.write(f"BTC: {btc_amount:.6f}\n") + f.write(f"ETH: {eth_amount:.6f}\n") + + except Exception as e: + # Write the error message to the result file + with open(output_file, "w") as f: + f.write(f"Error: {str(e)}\n") + +if __name__ == "__main__": + main()