From a622b7708deed5143ec6b5dbcc912341a3a6fe99 Mon Sep 17 00:00:00 2001
From: Kahtaf Alam <kahtaf@gmail.com>
Date: Mon, 16 Sep 2024 13:16:29 -0400
Subject: [PATCH] chore: docs update

---
 README.md                  | 32 ++++++++++++++++++++++++--------
 my-proof.manifest.template | 20 ++++++++++----------
 2 files changed, 34 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 157abfc..6e790f6 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,33 @@
 # Vana Satya Proof of Contribution - Python Template
 
-This repository serves as a template for creating proof of contribution tasks using Python and Gramine for secure computation.
+This repository serves as a template for creating a [proof of contribution](https://docs.vana.org/vana/core-concepts/key-elements/proof-of-contribution) tasks using Python. It is executed on Vana's Satya Network, a group of highly confidential and secure compute nodes that can validate data without revealing its contents to the node operator.
 
 ## Overview
 
 This template provides a basic structure for building proof tasks that:
 
-1. Read input files from the `/input` directory
-2. Process the data securely
-3. Write proof results to the `/output` directory
-4. Use the `/sealed` directory for secure storage (when available)
+1. Read input files from the `/input` directory.
+2. Process the data securely, running any necessary validations to prove the data authentic, unique, high quality, etc.
+3. Write proof results to the `/output/results.json` file in the following format:
+
+```json
+{
+  "dlp_id": 1234, // DLP ID is found in the Root Network contract after the DLP is registered
+  "valid": false, // A single boolean to summarize if the file is considered valid in this DLP
+  "score": 0.7614457831325301, // A score between 0 and 1 for the file, used to determine how valuable the file is. This can be an aggregation of the individual scores below.
+  "authenticity": 1.0, // A score between 0 and 1 to rate if the file has been tampered with
+  "ownership": 1.0, // A score between 0 and 1 to verify the ownership of the file
+  "quality": 0.6024096385542169, // A score between 0 and 1 to show the quality of the file
+  "uniqueness": 0, // A score between 0 and 1 to show unique the file is, compared to others in the DLP
+  "attributes": { // Custom attributes that can be added to the proof to provide extra context about the encrypted file
+    "total_score": 0.5,
+    "score_threshold": 0.83,
+    "email_verified": true
+  }
+}
+```
 
-The project is designed to work with Gramine, a lightweight library OS that enables running unmodified applications in secure enclaves, such as Intel SGX (Software Guard Extensions). This allows the code to run in a trusted execution environment, ensuring confidentiality and integrity of the computation.
+The project is designed to work with [Gramine](https://gramine.readthedocs.io/en/latest/), a lightweight library OS that enables running unmodified applications in secure enclaves, such as Intel SGX (Software Guard Extensions). This allows the code to run in a trusted execution environment, ensuring confidentiality and integrity of the computation.
 
 ## Project Structure
 
@@ -21,7 +37,7 @@ The project is designed to work with Gramine, a lightweight library OS that enab
 - `demo/`: Contains sample input and output for testing
 - `.github/workflows/`: CI/CD pipeline for building and releasing
 - `Dockerfile`: Defines the container image for the proof task
-- `my-proof.manifest.template`: Gramine manifest template for secure execution
+- `my-proof.manifest.template`: Gramine manifest template for running securely in an Intel SGX enclave
 - `config.yaml`: Configuration file for Gramine Shielded Containers (GSC)
 
 ## Getting Started
@@ -37,7 +53,7 @@ To use this template:
 
 The main proof logic is implemented in `my_proof/proof.py`. To customize it, update the `Proof.generate()` function to change how input files are processed.
 
-The proof can be configured using environment variables:
+The proof can be configured using environment variables. When running in an enclave, the environment variables must be defined in the `my-proof.manifest.template` file as well. The following environment variables are used for this demo proof:
 
 - `USER_EMAIL`: The email address of the data contributor, to verify data ownership
 
diff --git a/my-proof.manifest.template b/my-proof.manifest.template
index bc5048b..0b2d7f8 100644
--- a/my-proof.manifest.template
+++ b/my-proof.manifest.template
@@ -4,28 +4,28 @@ sgx.enclave_size = "256M"
 # Increase this as needed, e.g., if you run a web server.
 sgx.max_threads = 4
 
-fs.mounts = [
-  { type = "encrypted", path = "/sealed", uri = "file:/sealed", key_name = "_sgx_mrenclave" },
-  { path = "/input", uri = "file:/input" },
-  { path = "/output", uri = "file:/output" },
-]
-
 # Whitelist ENV variables that get passed to the enclave
+# Using { passthrough = true } allows values to be passed in from the Satya node's /RunProof endpoint
 loader.env.USER_EMAIL = { passthrough = true }
 
 # Gramine gives a warning that allowed_files is not safe in production, but it
 # should generally be fine for our use case which inherently assumes that input
 # files are untrusted until proven otherwise.
-#
-# Establishing a secure channel would be strong in that it would be harder for
-# malicious third parties to tamper with the files.
 sgx.allowed_files = [
   "file:/input/",
   "file:/output/",
+  # Required for internet access from inside the enclave
   "file:/etc/hosts",
   "file:/etc/resolv.conf",
 ]
 
+# These directories are mounted from the host, which will be a temporary directory from the Satya node that's running the proof.
+fs.mounts = [
+  { type = "encrypted", path = "/sealed", uri = "file:/sealed", key_name = "_sgx_mrenclave" },
+  { path = "/input", uri = "file:/input" },
+  { path = "/output", uri = "file:/output" },
+]
+
 # You can add other Gramine-manifest-compatible options as needed, see the
 # Gramine documentation for more details: https://gramine.readthedocs.io. Note
-# that gsc defines a number of manifest settings by default.
\ No newline at end of file
+# that gsc defines a number of manifest settings by default.