Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

"Cowboy" is an early-stage protocol that enables proving facts about arbitrary web data, in a privacy-preserving manner.

Why

This allows blockchain applications, and indeed, regular applications to prove statements about data which were not possible previously.

A few examples of this:

  • a Defi loan contract allows users to get bitcoin loans based on a zkTLS applications which designates an earnings tier for them based on their bank account balance and income.
  • A blockchain application gets a strong identity primitive through a zkTLS application which retrieves a unique state id from a website, and hashes it.
  • A DAO verifies that a user has a particular social media attribute, such as their follower count, and assigns them a score tag and identity credential.

Getting Started

There are two types of actions you can perform on the network now:

  1. Generate proofs of authenticated web content. Head over to Generating and Submitting proofs.
  2. Explore the developer examples and build your own. Head on over to Developer Examples

Getting Started

Welcome to Cowboy — a privacy-preserving protocol that lets you prove facts about web data using zero-knowledge proofs. This guide will walk you through setting up your environment, generating your first proof, and writing your own integration.

🧰 What You'll Need

Before proving anything, you need two components installed:

  • Cowboy TLSN Browser Extension
    Captures web requests and works with a notary server to produce TLS Notary proofs.

  • Cowboy Prover Docker Container
    Generates RISC Zero zk-STARK proofs based on your TLS Notary transcript and custom logic.

➡️ See Resources for setup instructions.

✅ Quick Start Steps

  1. Install the Cowboy TLSN Extension

    • Follow the steps in Resources.
    • Configure it to use Cowboy’s hosted notary server.

  2. Run the Cowboy Prover Locally

    docker run -p 1881:1881 --platform linux/amd64 ghcr.io/project-cowboy/cowboy-prover:latest

  3. Capture a Web Request Use the extension to browse to a site like x.com, then trigger the notarization flow.

  4. Generate and Submit a Proof After capturing the TLS Notary proof, click the On-chain tab in the extension to:

    • Connect to a devnet node
    • Create a wallet and claim test funds
    • Look up any existing integration
    • Prove and submit your data to the network

See the Generating and Submitting Proofs guide for full details.

🧪 Test an Example Integration

Want to see what Cowboy can do? Try one of the example integrations:

  • X.com account proof
  • TikTok influencer tier, without revealing folllower count or username

These use preconfigured endpoints and logic to showcase how custom integrations work.

🛠️ Write Your Own Integration

Once you're comfortable submitting proofs, try writing your own:

  • Write a Rust program that parses the TLS Notary proof and asserts your desired conditions.
  • Use the prover to generate the app-specific zk-STARK proof.
  • Upload your integration to the chain and start verifying onchain.

Check out the Developer Examples for structure, utilities, and inspiration.

Repo

Check out the Repo here

🧠 Learn More

  • Introduction: What Cowboy is and why it matters.
  • FAQs: Get clarity on integrations, proof types, and more.
  • Resources: All tools in one place.

Generating and Submitting Proofs

This guide walks you through how to generate a proof from a web request and submit it to the Cowboy devnet. It also describes what happens under the hood and how your own programs (integrations) can be proved onchain.

Overview of the Proof Flow

My Test Image

🔧 What You Need

To generate and submit a proof, you’ll need:

  1. ✅ The Cowboy browser extension
    It lets you select web requests to prove, and handles communication with Notary and Prover.

  2. ✅ The Cowboy prover Docker container
    This generates zk-STARK proofs using RISC Zero.

Please see the Resources page to find the steps to prepare these on your machine.

🪼 Step-by-Step example: Submitting a Proof

1. Install the Cowboy Extension

  1. Follow instructions in the Resources guide to install and enable the extension in Chrome or Brave.
  2. Click the icon for the extension.
  3. Click the hamburger icon in the top-right corner > "Options"
  4. Under Notary API, enter: "https://juvenile-surface-corps-securities.trycloudflare.com"

This tells your browser how to contact Cowboy's hosted notary server. ⚠️ In general, make sure you're using a trusted notary server.

2. Run the Local Prover

You must run the prover container locally. If running on MacOS(arm64), you can do:

docker run -p 1881:1881 --platform linux/amd64 ghcr.io/project-cowboy/cowboy-prover:latest --node-url wss://goals-unable-seller-myspace.trycloudflare.com

If on amd64, omit the platform argument.

This component must be running in the background to generate and submit proofs.

3. Request an X account proof via the extension

  1. Click the extension icon to open its menu
  2. Click twitter profile.
  3. The sidebar should show some steps including browsing to twitter, and collecting cookies. Click them if the UI has not focused those elements.
  4. The notarization should be in progress. Wait, and once done, we can explore it.
  5. Click "View"

4. TLS Notary Proof Is Generated

Once generated, a new window should open, which contains information about the proof. Click the "onchain" tab to progress to a wallet interface.

  1. Click the "On-chain" tab
  2. You must tell the extension how to reach the node. In the Node Url field, enter wss://goals-unable-seller-myspace.trycloudflare.com
  3. Click "Connect"
  4. Click "Create new account". This creates a test account, and stores it in the wallet.
  5. Click "Claim" to interact with the onchain faucet account, and claim some funds for your account.
  6. Click "Connect and lookup app onchain". This asks the blockchain whether an integration exists for the class of proof you have in your extension. It should show a green success indicator.
  7. Click "Prove, and send to network". If the button is not clickable at first, you may need to try again.
  8. Wait... this will take a while. Feel free to observe progress in your local prover.

6. Proof Is Submitted to the Devnet

The final step above connects with your local prover, which will generate a zk proof that proves a fact about your twitter following.

In the current devnet-only wallet implementation, the extension handles a few steps for you - receiving the proof, and signing a transaction to submit it onchain.

The chain verifies it and may emit public outputs written by the integration logic.

You have just submitted your first zkTLS proof to the Cowboy devnet, and verified it onchain!

🧬 Recap: What happened?

Above, we just did something very powerful, let's walk through it:

  1. We decided we wanted to prove something about our social media profile, and make that available onchain.
  2. We used an extension that allows our browser to work with another component, the "notary" to prove the integrity of our web request/response contents.
  3. Once we retrieved that proof, we asked our local zk prover to take that proof, as well as the data, and prove some facts about it, in zero-knowledge.
  4. The prover first proved the correctness of the proof, before running a different program against that data, to optionally prove a fact about our twitter data, and output a unique credential that we can only receive if authenticated.
  5. We received that proof, and wrapped it in a transaction, sent it onchain for it to be verified.
  6. Once verified, it emitted an event containing the unique credential from their zkTLS proof!

This showcases some flexibility of the system, and hints at how you might use zkTLS for dApps such as DAOs, or social fi.

🧠 What Are Integrations?

Integrations are developer-written programs that define custom logic on top of core proofs. They:

  • Accept TLS proof + parsed web data
  • Perform custom assertions in Rust
  • Output public data to the chain

See Developer Examples for templates and inspiration.

🪨 Writing Your Own Integration (Preview)

Interested in submitting your own logic?

  1. Write a Cowboy-compatible Rust program that consumes a TLS Notary proof and parsed web response.
  2. Generate the app-specific proof using the prover.
  3. Submit to the chain to verify and emit output.

See Getting Started and Developer Examples to dive in.

🧪 Test the Flow

Use the live devnet to:

  • Observe onchain proof submissions
  • Monitor emitted public outputs
  • Debug issues or verify output formats

✅ Summary

You now understand:

  • How to generate and submit TLS Notary proofs
  • The role of the extension, prover, and notary
  • What integrations are and how to create your own

🔗 Ready to build? Explore Developer Examples or start Getting Started.

Example Integrations

Cowboy enables developers to build privacy-preserving proofs about web data using custom integrations. This section gives a high-level overview of how these integrations are structured, how they work, and what they enable.

🎯 Purpose of Integrations

Integrations allow developers to:

  • Prove specific statements about web data (e.g., “My age according to a government website is over 21.”)
  • Embed custom logic that runs inside zero-knowledge proofs.
  • Emit structured public outputs for use in identity systems, scoring mechanisms, credentials, or composable applications.

This is the utility layer of Cowboy, where developers define what they want to verify about web data and how it can be reused across the ecosystem.

🏗️ Integration Structure

Each integration includes the following key components:

  • A web target — An endpoint or page on the internet (e.g., https://pokeapi.co/api/v2/pokemon/jigglypuff) whose request/response will be proven.
  • An application-specific program — A zk-STARK circuit written in Rust that verifies the TLSNotary proof (core proof) and checks custom conditions about the fetched data (e.g., checking follower count, extracting specific fields).
  • Public outputs — Optional values emitted by the program after verification, used on-chain or by other integration proofs.

These programs are tested using the Cowboy prover container and submitted to the devnet for deployment and interaction.

🧪 Example Integration Overview

The example integrations demonstrate both what’s possible and how to use the provided dev tools for building, testing, and uploading integrations. Each includes:

  1. TLSNotary Proof Input
    Each integration expects a TLSNotary proof aligned to a specific URL — for example, the TikTok integration requires a proof of a request to www.tiktok.com/aweme/v2/data/insight/. This proof is generated by the browser extension and passed to the prover.

    ✅ Both example integrations come with a working sample proof so you can start developing immediately. You can also generate your own proof using the extension and prover.

  2. Utilities

    • run: Prove your integration locally against a given input. This is useful during development.
    • upload: Deploy your integration to the chain so that others can use it and verify proofs onchain.

Next Steps

Check out the Repo here

Resources

Cowboy TLSN Extension Fork

To get the browser extension on a Chrome-based browser

  1. Go to the Github release
  2. Click the build.zip.
  3. Unzip
  4. If on Chrome, go to chrome://extensions/. If on Brave, go to brave://extensions/
  5. "Load unpacked"
  6. Select the unzipped folder. If it doesn't allow you to upload, you may need to select a build sub-folder.

Cowboy Prover

To run the local prover which enables proving custom logic developed on Cowboy, please do:

docker  run -p 1881:1881  ghcr.io/project-cowboy/cowboy-prover:latest ./target/release/k256-example --node-url  "wss://goals-unable-seller-myspace.trycloudflare.com"

Leave this running whenever you are using the extension or doing local proving.

Access the live devnode

To access the live devnode, visit it via the polkadotjs explorer link here

FAQs

Q: What are 'integrations' in Cowboy? A: Custom integrations consist of Rust programs written by developers which receive a "core" proof that authenticates the web data, and then enacts its own custom logic against that web data. This execution is proven as a zk-STARK. This program is uploaded onchain. Verifications of this proof can output public outputs of the proof that the developer wrote.

Q: What are 'proofs' in Cowboy? A: Supported proofs in Cowboy are zk-STARK proofs, generated by a RISC Zero prover. Proofs can be split into three categories:

  • TLS Notary proofs
  • "Core" Proofs
  • Application-specific proofs

TLS Notary proofs are generated by your browser and the selected notary, following the TLS Notary protocol. "Core" proofs are proofs that ensure the integrity of the TLS Notary proof, and are a requirement for any custom integration. Application-specific proofs are generated by custom integrations written by developers.