Contract Source Validation SEP

[orbitlens]

Contract Source Validation SEP

Preamble

SEP: TBD
Title: Contract Source Validation
Authors: OrbitLens <@orbitlens>
Track: Standard
Status: Draft
Created: 2024-09-28
Updated: 2024-12-03
Version: 0.2.0
Discussion: https://github.com/stellar/stellar-protocol/discussions/1573

Simple Summary

A toolkit for the verification of the trust chain between contract WASM and its source code.

Motivation

Stellar doesn't store the source code of contracts in the blockchain, so it may be quite challenging for users to make sure that a contract they are going to invoke is not malicious and behaves as advertised.

Abstract

This SEP describes an approach of automated source code matching based on GitHub Actions Workflows and GitHub Attestations. It provides the ability to establish a trust chain from a smart contract deployed on Stellar Network to a specific commit in GitHub repository containing source code of this contract. As a side benefit, this standard workflow streamlines the smart contracts compilation and release process for Soroban WASM runtime.

In order to turn on automatic code attestation, smart contract developers create a simple configuration file in a contract Git repository.

When triggered, this workflow:

• Compiles a smart contract (or multiple contracts) in the repository
• Creates an optimized WebAssembly file ready to be deployed to Soroban
• Publishes GitHub release with attached build artifacts
• Creates GitHub attestation artifact associated with the repository

Upon successful validation, anyone can retrieve the GitHub repo link from the contract binary and verify the authenticity of the build directly on the contract GitHub repository Attestations page or using a blockchain explorer that supports this SEP. The trust chain can be validated up to a particular point-in-time snapshot of the source code at the given commit used to build the contract.

Specification

The verification mechanism relies on the GitHub automation and Attestations build artifacts generated during the automated smart contract compilation. Each attestation contains:

• Source code repository
• Environment variables
• Output binary hash (matches the hash of the contract WASM deployed on the ledger)
• Commit hash (required to point at a specific point-in-time codebase snapshot)
• Link to the workflow associated with the artifact (used to ensure the security of the compilation process)

In addition to the source code repository link, the workflow can also store a home domain in the contract to provide a consistent off-chain organization and/or token information resolution using a standard SEP-0001 stellar.toml file.

During the compilation, the pipeline stores a repository address in every compiled contract by adding WASM metadata to the contractmetav0 custom sections. Metadata is stored in the contract as SCMetaEntry XDR entry. Downstream systems can retrieve this information directly from the WASM, read repository contents and retrieve corresponding attestation from the GitHub API endpoint: https://api.github.com/repos/<user_name>/<repo_name>/attestations/sha256:<wasm_hash>, where wasm_hash is the SHA256 hash of the contract WASM binary.

Metadata entries stored in the contract WASM:

• source_repo=github:<user_name>/<repo_name> - source repository link
  example: source_repo=github.com:reflector-network/reflector-dao-contract
• home_domain=<domain_name> - domain that hosts organization's stellar.toml (domain name only, without schema or relative path)
  example: home_domain=reflector.network

Based on this information anyone can verify the authenticity and integrity of the smart contract source code, and perform a reverse lookup of the contract information from the organization's domain.

Workflow Setup and Configuration

Prerequisites

• Create a GitHub Actions workflow file .github/workflows/release.yml in your repository.
• Decide how the compilation workflow will be triggered. The recommended way is to configure workflow activation on git tag creation. This should simplify versioning and ensure unique release names.

Workflow inputs and secrets

Basic compilation workflow path:
stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main

The workflow expects the following inputs in the with section:

• release_name (required) - release name template (should include a release version variable, e.g. ${{ github.ref_name }})
  package (optional) - package name to build, builds contract in working directory by default
• relative_path (optional) - relative path to the contract source directory, defaults to the repository root directory
• make_target (optional) - make target to invoke, empty by default (useful for contracts with dependencies that must be built before the main contract)

Basic workflow for the repository with a single contract

name: Build and Release  # arbitrary name
on:
  push: 
    tags:
      - 'v*'  # triggered whenever a new tag (prefixed with "v") is pushed

permissions:  # required permissions
  id-token: write
  contents: write
  attestations: write

jobs:
  release-contract-a:
    uses: stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main
    with:
      release_name: ${{ github.ref_name }}   # git tag as unique release name
      release_description: 'Contract release'   # text to attach to the release
      relative_path: '["src/my-awesome-contract"]'   # relative contract path
      package: 'my-awesome-contract'   # package name to build
      make_target: 'build-dependencies'   # make target to invoke
      home_domain: 'doman.name'    # organization's domain name (optional)
    secrets:  # authentication tokens will be automatically created by GitHub
      release_token: ${{ secrets.GITHUB_TOKEN }}   # don't modify this line

Workflow permissions

In order to create a release, the workflow needs id-token: write, contents: write and attestations: write permissions. Default workflow permissions for a repository can be found at "Settings" -> "Actions" -> "Workflow permissions". It's important to specify permissions on the top level in the .github/workflows/release.yml configuration file itself:

permissions:
  id-token: write
  contents: write
  attestations: write

Building multiple contracts

To build multiple contracts, add a separate job for each contract. The workflow will compile and release each contract independently.

name: Build and Release Multiple Contracts
on:
  push: 
    tags:
      - 'v*'  # triggered on a new tag (prefixed with "v")

permissions:
  id-token: write
  contents: write
  attestations: write

jobs:
  release-contract-a:
    uses: stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main
    with:
      release_name: ${{ github.ref_name }}          
      release_description: 'Contract A Release'       
      relative_path: '["src/my-awesome-contract"]'  
      package: 'my-awesome-contract'                
      make_target: 'build-dependencies'             
    secrets:
      release_token: ${{ secrets.GITHUB_TOKEN }}
  
  release-contract-b:
    uses: stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main
    with:
      release_name: ${{ github.ref_name }}          
      release_description: 'Contract B Release'
      relative_path: '["src/another-awesome-contract"]'
    secrets:
      release_token: ${{ secrets.GITHUB_TOKEN }}
    
  release-contract-from-root:
    uses: stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main
    with:
      release_name: ${{ github.ref_name }}          
      release_description: 'Root Contract Release'
    secrets:
      release_token: ${{ secrets.GITHUB_TOKEN }}

Triggering build process manually

Triggering this workflow manually requires a unique release name prompt. Replace the trigger condition in config and update release_name to utilize the value from the prompt.

on:
  workflow_dispatch:
    inputs:
      release_name:
        description: 'Unique release name'
        required: true
        type: string
permissions:
  id-token: write
  contents: write
  attestations: write
jobs:
  release-contract:
    with:
      release_name: ${{ github.event.inputs.release_name }}

Notes

• The workflow assumes that each contract directory contains the necessary structure and files for the build process.
• It makes sense to run contract tests automatically before deploying the contract to make sure that broken contracts won't end up in published releases. It requires adding corresponding action invocation before the release_contract job.
• In case of the multi-contract repository setup, contracts shouldn't have the same name (defined in TOML file) and version to avoid conflicts during the release process.
• To enable automatic contract source validation process, contracts should be deployed to Stellar Network directly from a compiled GitHub release generated by this workflow. Otherwise the deployed contract hash may not match the release artifacts due to the compilation environment variations.

Design Rationale

Currently, the pipeline relies on GitHub platform tools and does not provide the toolkit for other platforms, like GitLab or BitBucket. GitHub has the largest market share, so the initial implementation utilized its standard APIs and instruments. In the future, in response to the demand, similar automated workflow can be created for other platforms as well. The source_repo metadata record contains a platform prefix (github:) as an extension point for the smooth integration of other repository hosting providers. In addition, attestations can be also potentially stored on IPFS or other distributed storage to increased the data availability.

Likewise, this SEP and workflow can be extended in the future to execute automatic contract deployment to the network on build. However, this process has a huge a list of potential security concerns which need to be evaluated, addressed, and documented before including this functionality in the continuous delivery pipeline.

Security Concerns

This SEP does not create any direct security concerns for the Stellar protocol or ecosystem applications.

Since the verification routine relies on the GitHub build automation and attestations mechanism, this approach implies the trust in GitHub’s security. If GitHub security is compromised, it means that verification data cannot be trusted. The possibility of such an event looks very low considering the track records of GitHub and its enterprise backers.

Unlike other building artifacts, attestations are stored in GitHub forever (or at least until the code repository is removed). Therefore, if developers decide to remove a smart contract repository, the verification chain may be broken. However, downstream systems (like blockchain explorers) may retain the verification information indefinitely, alleviating such risks.

While the build process itself is performed in the virtual Docker environment shielded from any external access, smart contract developers still can potentially use some subtle techniques to inject malicious code into the contract during the compilation phase. Protecting end users from malicious developer actions is out of the scope of this SEP – the primary goal is to provide unfalsifiable evidences that a contract has been compiled automatically using a particular GitHub repository.

The automation workflow that builds smart contracts is currently hosted by StellarExpert. We suggest transferring its repository ownership to SDF in order to minimize trust concerns.

Implementations

• Workflow

Changelog

• v0.2.0 - Added home_domain meta, notes on meta XDR and format, design rationale for the GitHub platform lock-in
• v0.1.1 - Defined metadata storage key format explicitly
• v0.1.0 - Initial draft

[tupui]

I have been using your action for my project and it's great 👍 It's very important for the whole supply chain security that we get that part right.

Some comments/suggestions:

• Besides reproducible build, which comes with its own set of challenges, the last bit would be to have a CD step. But that's very debatable from a security point of view and also because then it's very locked in on a specific platform. (Sticking to GitHub, you could use OpenID Connect.)

• On the attestation storage part. I would suggest to move that to IPFS. That would alleviate a bit of lock in and I think that as an industry we should do more with IPFS and try to rely less on things like GitHub, AWS, etc. PyPi is uploading their attestations to sigstore, but here as well it's very much centralized and they only guarantee 3 9s. Otherwise they invite you to spin up their service on your infra. Which to me is a cry for IPFS or else.

• It might be missing is a general API definition in case people would want to use another platform (e.g. GitLab).

• Can this be viewed as a security concern? In the end we also need to put some trust in the GitHub action especially if it can inject stuff in the contract.

  During the compilation, the pipeline stores a repository address in every compiled contract by adding custom WASM metadata in the source_repo=github:<user_name>/<repo_name> format.

• Do you have plans for adding SBOM? I think that's also important (and in some cases needed for regulatory purposes like DORA.)

[orbitlens]

Thanks for the detailed feedback.

Besides reproducible build, which comes with its own set of challenges, the last bit would be to have a CD step.

The workflow can be relatively extended in the future to execute automatic contract deployment to the network on build. However, this process has a huge a list of potential security concerns which need to be evaluated, addressed, and documented before including this functionality in the continuous delivery pipeline.

On the attestation storage part. I would suggest to move that to IPFS.

This is something definitely worth researching in the future. I'm not sure whether it's possible to resolve contract hash -> IPFS attestation hash relation without a centralized entity since IPFS hashes the content of the attestation data itself.

It might be missing is a general API definition in case people would want to use another platform

It requires a lot of work. While I think it's the right path, I'm not ready to spare resources for R&D on this right now.

Can this be viewed as a security concern? In the end we also need to put some trust in the GitHub action especially if it can inject stuff in the contract.

Yes, it's a security concern. We have to trust a centralized entity (GitHub) that it won't mess up with the code, and we need to trust the workflow itself. I mentioned this in the "Security Concerns" section. Please let me know if it's unclear and I need to elaborate on this.

Do you have plans for adding SBOM?

We cannot include SBOM information directly into the contract itself, but probably can generate it alongside with the contract binary attestation. I'll check this.

[tupui]

It might be missing is a general API definition in case people would want to use another platform

It requires a lot of work. While I think it's the right path, I'm not ready to spare resources for R&D on this right now.

Just to be clear, here I was proposing that you put the OpenAPI schema (or else) that you currently use for your current API. It should be a good starting point as it works.

Yes, it's a security concern. We have to trust a centralized entity (GitHub) that it won't mess up with the code, and we need to trust the workflow itself. I mentioned this in the "Security Concerns" section. Please let me know if it's unclear and I need to elaborate on this.

In the security section you mention the trust into GitHub, but I think here we also need to clearly mention again that the contract is being modified to add some metadata into it. In the top section the description is ok I think, but here we should expand on the security implications of modifying the contract.

[leighmcculloch]

👋🏻 This proposal is really important and it's wonderful to see it starting to get use already.

I think the proposal bundles together three super valuable things that need more specification, independently:

• 1️⃣ Linking built wasms to source code
• 2️⃣ Linking built wasms to home domains
• 3️⃣ A convenient common build process or common build containers

Why:

• they have different goals
• they do not need to be used together
• independent, they would be composable
• some are easy to specify in full now and expect never to change (1️⃣, 2️⃣), others require more iterative ongoing work (3️⃣)
• by bundling we create a mega-SEP of sorts that:
  • misses some specificity, e.g. doesn't discuss the concrete guarantees and how to validate and reproduce those guarantees

---

1️⃣ Linking built wasms to source code –

The proposal achieves this with GitHub Attestations and Sigstore's Rekor (transparency log) 👏🏻.

GitHub Attestations are sufficient for proving the wasm to source code link. We know this because it's now a software engineering best practice adopted by other ecosystems (npm, pypi, homebrew). The rest of the proposal provides other guarantees and benefits that aren't critical for proving a link between a binary (wasm) and code.

The less we add to this verification process that is bespoke, the more we lean on the software engineering industries best practices, the more we can benefit from development outside the Stellar ecosystem. For example, using common tools like the github-cli to facilitate verification.

For the purposes of defining how to verify code, the proposal would be sufficient to set it's scope on:
a) set the source_repo meta
b) define how to generate attestations
c) define how to verify attestations

Currently the proposal doesn't indicate how to do (b) or (c), other than use the stellar-expert/soroban-build-workflow workflow to publish and stellar.expert to view verifications. I think it's critical the proposal discuss both in detail at a foundational level so that others can implement the proposal. So I think the proposal needs to discuss:

• At a basic level how someone can create an attestation. It could show how to do this with GitHub's action at least, or sigstore tooling. e.g.:

      - uses: actions/attest-build-provenance@v1
        with:
          subject-name: contract.wasm
          subject-path: target/wasm32-unknown-unknown/release/contract.wasm

• Detail how to verify a wasm was built from code. Discuss what GitHub APIs to call, the https://in-toto.io/Statement/v1 payload data, how to verify the payload in the Rekor transparency log (still important, even though this proposal trusts GitHub, because it limits the trust to build time and not verify time), and what fields of the payload data are critical to verify and why. It could direct users how to determine the git commit, the repo, the workflow that was executed. It could discuss subtle but important aspects such as as what type of runner the build was executed on because non-github-hosted runners are custom environments where a different trust model would be required not only on GitHub.

The proposal suggests SDF take ownership of the bespoke workflow, but if we reduce the verification proposal to the above, there will be no need for any trust in any workflow owner, other than GitHub. Assuming the use of Rekor in the verification process, GitHub on its own would only be trusted at build time, not at verification time.

It would be awesome if the proposal could discuss the sigstore primitives that are being used. Because really this solution is platform agnostic already. A payload is produced, signed, published to the sigtore transparency log (rekor), and if you trust the signer, you can verify the payload. But being most practical I think it's fine if it relies on GitHub APIs and maybe in the future a compatible SEP is written that describes the process at the sigstore layer.

---

2️⃣ Linking built wasms to home domains –

The proposal includes instructions for how to store home_domain meta inside a wasm file, but doesn't define how to do verification of the domain. There should be a corresponding change to SEP-1 stellar.toml and a verification process where a wasm file must point to the stellar.toml, and the stellar.toml must point to the wasm hash, to confirm that neither the wasm file or the stellar.toml are fraudulent.

This 'home_domain' linking could be an independent SEP and doesn't need to be coupled with source code verification.

The wasm file home_domain linking may also not be sufficient for all use cases. Not all deployments of a wasm hash should be associated with the same home domain. Contract deployments/instances also need a way to report their home_domain linkage, and so it may be better to do linking at the instance level instead of the wasm file meta level.

---

3️⃣ A convenient common build process or common build containers –

The proposal as written requires the use of a GitHub build workflow where contracts are built in a specific Ubuntu docker image, and attestation/verification requires releasing:

stellar-expert/soroban-build-workflow/.github/workflows/release.yml@main

The workflow is opinionated and makes assumptions about how a developer wants to build and release their contracts.

In other ecosystems that use attestation, building is not opinionated or coupled to attestation, for e.g.:

• Should this action pre-install wheel? pypa/gh-action-pypi-publish#11 (comment)

The workflow expands the surface area of a contract developers risk, because they must be concerned with a third parties action, and the additional third party components that workflow pull in and may be supply chain exploitable. For example:

• softprops/action-gh-release@v2 dependency within the workflow stellar-expert/soroban-build-workflow#2

It shifts control away from the developer and requires developers to use a specific approach to releasing and building their applications. Ideally developers can be in full control of their own build and release processes and still be permitted to participate in verification.

I think a standard GitHub Action that builds Rust Stellar contracts would be good for the ecosystem, but it seems unnecessary to couple it with source code verification.

A standard Docker image for building could further the goal of reproducible builds as another method for making it possible to verify builds. This proposal would need more than what exists here though, such as a fully and truly reproducible build image, and a way to securely link wasm builds back to their build image. That effort is much more likely to be iterative and require more work because reproducible builds in Rust are hard (something @brson has spent some effort on improving ❤️) and building other peoples Rust code is unsafe (because building Rust code executes it on the host).

---

In an example contract repo I've written a build process that I think should be compatible with the verification proposal, because it uses attestation reasonably to prove linkage between a wasm and code. Currently it doesn't show up as verified on stellar.expert because it doesn't use the stellar-expert workflow:

• https://github.com/leighmcculloch/exp-stellar-expert-verified-builds/blob/main/.github/workflows/custom-release.yml

In my own learning I wrote a prototype CLI command that verifies the code links to the binary using only the source_repo meta and the GitHub Attestation APIs. It's just a toy, and not something I plan to merge as is, but for folks who want to play with it:

• Experimental contract verify command stellar-cli#1778

@orbitlens and folks, wdyt? Are there three proposals here we can separate?

@tupui given your experience with pypi I'm interested if separating this proposal makes sense, specifically separately 1️⃣ and 3️⃣, given that ecosystem has as far as I can tell.

[tupui]

I sort of agree with separating the concerns and I personally think the split you propose is sensible.

1,3. this is also what we went for with our specification https://scientific-python.org/specs/spec-0008/ we mostly just discuss signing and plan to add more specifications to discuss the build part. Though it's less clear as Python is a wider build scope as Soroban. In any case, hard to get reproducible builds and that part only would make sense to have as a workflow, which would likely only be accepted by the community if that comes from SDF. I doubt the action we have in Python will ever try to build, or only do so for pure Python packages. Otherwise it's quite nice that it make attestations and publish to PyPi. I doubt that people would trust to put some keys on GitHub to update their contract, but why not after all.

2. If this becomes its own SEP, I would propose to combine it with our discussion on having a standard for metadata and the implementation e.g. from @ArrietaDev https://sorobandomains.org/docs/key_value_db