cycles-quartz/crates/contracts/core/SPEC.md

Quartz CosmWasm (quartz-contract-core) Specification

Abstract

This document specifies the quartz-contract-core package, which provides a high-level framework for building attestation-aware smart contracts on CosmWasm. The package implements secure message handling, state management, and attestation verification for Intel SGX-based contracts.

Table of Contents

• Introduction
• Functionality
• Implementation
• Properties
• Assumptions

Introduction

The quartz-contract-core package is designed to facilitate the development of secure, attestation-aware smart contracts on the CosmWasm platform. It provides a set of tools and abstractions that allow developers to easily integrate Intel SGX remote attestation into their smart contracts, ensuring that only authorized enclaves can interact with the contract's sensitive functions.

Scope

This specification covers the core components of the quartz-contract-core package, including:

1. The Attested<M, A> wrapper for secure message handling
2. Attestation types and verification processes
3. State management utilities
4. Message handling and execution flow

Design Goals

• Provide a secure and easy-to-use framework for attestation-aware smart contracts
• Abstract away the complexities of SGX attestation verification
• Ensure compatibility with DCAP attestation protocols (EPID is deprecated now by Intel)
• Allow for easy testing and mocking of SGX environments

Functionality

The quartz-contract-core package provides the following key functionalities:

1. Secure message wrapping with Attested<M, A>
2. Attestation verification for DCAP protocols
3. State management utilities for CosmWasm contracts
4. Execution handlers for attested messages

Definitions

• Attested<M, A>: A wrapper struct that holds a message M and its attestation A.
• Attestation: A trait that defines the common interface for different attestation types.
• DcapAttestation: A struct representing a DCAP attestation.
• MockAttestation: A struct for mocking attestations in test environments.

Implementation

The quartz-contract-core package is implemented in Rust and relies on the CosmWasm framework. The main components are:

Attested Message Wrapper

The Attested<M, A> struct is a wrapper for holding a message and its attestation:

/// A wrapper struct for holding a message and its attestation.
#[derive(Clone, Debug, PartialEq)]
pub struct Attested<M, A> {
    pub msg: M,
    pub attestation: A,
}

impl<M, A> Attested<M, A> {
    pub fn new(msg: M, attestation: A) -> Self {
        Self { msg, attestation }
    }
}

Attestation Trait

The Attestation trait defines the common interface for different attestation types:

pub trait Attestation {
    fn verify(&self, deps: Deps<'_>, env: &Env) -> Result<(), Error>;
}

Attestation Verification

The attestation verification process is handled by the quartz-tee-ra package, which is a dependency of quartz-contract-core. The verification functions are called within the execution handlers of quartz-contract-core.

pub use intel_sgx::{
    dcap::verify as verify_dcap_attestation,
    Error,
};

Execution Handler

The execution handler is responsible for processing attested messages and verifying their attestations before executing the contained message.

pub fn handle_attested<M, A, H>(
    deps: DepsMut<'_>,
    env: Env,
    info: MessageInfo,
    attested: Attested<M, A>,
) -> Result<Response, Error>
where
    M: DeserializeOwned + Serialize,
    A: Attestation,
    H: Handler<M>,
{
    // Verify the attestation
    attested.attestation.verify(deps.as_ref(), &env)?;

    // Extract the message from the attested wrapper
    let msg = attested.msg;

    // Dispatch the message to the appropriate handler
    H::handle(deps, env, info, msg)
}

Properties

The quartz-contract-core package ensures the following properties:

1. Attestation Integrity: All messages wrapped with Attested<M, A> must have a valid attestation that can be verified.

2. Message Confidentiality: The contents of attested messages are only accessible after successful attestation verification.

3. Enclave Identity Verification: The package verifies that messages come from authorized enclaves by checking the MRENCLAVE value.

4. DCAP Support: The package supports DCAP attestation protocols.

5. Testability: The mock-sgx feature allows for easy testing of contracts without a real SGX environment.

Assumptions

The quartz-contract-core package operates under the following assumptions:

1. The underlying SGX hardware and software stack is secure and not compromised.

2. The attestation verification process provided by the Intel Attestation Service (IAS) or DCAP infrastructure is reliable and secure.

3. The CosmWasm runtime environment correctly executes the contract code and maintains the integrity of the contract's state.

4. The communication channel between the enclave and the smart contract is secure and resistant to man-in-the-middle attacks.

5. The contract developers correctly implement the quartz-contract-core abstractions and follow secure coding practices.

6. The MRENCLAVE values of authorized enclaves are known and correctly configured in the contract's state.

By adhering to this specification, developers can create secure, attestation-aware smart contracts that leverage the power of Intel SGX technology within the CosmWasm ecosystem.# Quartz CosmWasm (quartz-contract-core) Specification