Walrus Sites Provenance Specification

This document outlines the structure and convention used to verify and manage provenance for Walrus Sites.

Storage Convention

• Provenance data is not stored as on-chain metadata but is verified against deployment artifacts.
• During deployment, a provenance file is added to a known location in the deployed content.

File Structure

The following files must be included in the deployed site:

• .well-known/walrus-sites.intoto.jsonl: This file contains the provenance data (in-toto format).
• .well-known/site.config.json: This file holds deployment configuration.

site.config.json Fields

Although this file is not used for verification, it plays a crucial role in deployment configuration. It contains:

• The network (e.g., testnet, mainnet)
• The Sui address of the site owner
• Site name
• Metadata (such as description, image, and links)
• Site object ID (if updating an existing site)
• Number of epochs to keep site data available

Verification Flow

1. Site Build

   • Build the site and generate the static artifact files.

2. Generate Provenance File

   • Create .intoto.jsonl from the build output with SHA-256 hashes of each resource.

3. Add Provenance to Output

   • Save walrus-sites.intoto.jsonl in .well-known/ folder of your site.
   • Save site.config.json in the same folder.

4. Deploy to Walrus

   • Deploy the site using Walrus Publisher. The resulting Site Object will contain the list of registered resources with their hashes.

5. Verify Provenance

   • Use the domain prefix (e.g., xxx.wal.app) to resolve the Site Object on Sui blockchain.
   • Retrieve the list of resources and their hashes from the Site Object.
   • Compare each hash to the corresponding entry in the .intoto.jsonl file.

Resource Hash Verification

• The source of truth for the hashes is the Site Object registered on Sui.
• The .intoto.jsonl file serves as a locally stored proof of integrity.
• A verification service (like notary.wal.app) compares these two sources.

Naming Convention

• Provenance file: .well-known/walrus-sites.intoto.jsonl
• Config file: .well-known/site.config.json

These naming conventions are essential to allow verifiers to discover and validate the provenance information automatically.