code-attest

A lightweight tool for pinning code to IPFS and anchoring the attestation onchain.

Not a Git replacement. Not a new protocol. Just a verifiable receipt for code that matters.

---

The Problem

When code matters — a security tool, a deploy script, AI-generated infra, a smart contract — there's no trustless way to say "this is the real version, unmodified, published at this time." You're trusting GitHub, an S3 bucket, or whoever is hosting the file. Any of those can be edited or deleted silently.

---

What This Is

A CLI tool (and agent skill) that:

1. Takes a file or directory
2. Pins it to IPFS — content-addressed, immutable
3. Posts an attestation to Ethereum as a blob transaction:

   {
     "name": "my-deploy-script",
     "version": "v1.2.3",
     "ipfs_cid": "QmXyz...",
     "sha256": "abc123...",
     "signer": "0xYourAddress",
     "timestamp": 1741000000
   }
   

4. Returns a verification URL

Anyone can independently verify: pull the file from IPFS, hash it, check it matches the onchain record. No trusted party in the loop.

---

CLI Usage

# Attest a file
code-attest ./deploy.sh --name deploy-script --version v1.0.0

# Attest a directory (hashes the whole tree)
code-attest ./contracts/ --name my-contracts --version v2.1.0

# Verify a previous attestation
code-attest verify 0x<tx_hash>
code-attest verify QmXyz...

Output:

✓ Pinned to IPFS:  ipfs://QmXyz...
✓ Attested onchain: base tx 0xabc...
✓ Verify at:        https://attest.sh/0xabc

---

Agent Skill

AI agents that generate sensitive code (deploy scripts, config files, infra code) can call this as the final step before delivering output. The attestation creates an audit trail:

• What was generated (IPFS content hash)
• When it was attested (onchain timestamp)
• Who attested it (signing address)

This is particularly useful for agent-generated code where provenance is otherwise zero.

# Agent workflow
clawd attest ./output/ --name "clawd-deploy-$(date +%Y%m%d)" --version v1.0.0

---

How It Works Under the Hood

On publish, two things happen simultaneously:

1. The code is pinned to IPFS by the publisher — CID is known immediately
2. A blob tx is posted to Base containing the attestation JSON + the actual code (if < 128KB), or just the metadata + CID for larger payloads

{
  "name": "my-deploy-script",
  "version": "v1.2.3",
  "ipfs_cid": "QmXyz...",
  "sha256": "abc123...",
  "signer": "0xYourAddress",
  "timestamp": 1741000000,
  "content": "<raw file bytes if small enough>"
}

Content resolution (dual-source):

Days 1–18:   resolve from the blob directly (fast, free, no IPFS needed)
Day 18+:     blob pruned by nodes → fall back to IPFS CID
             (publisher already pinned it; others may have too)

async function resolve(txHash) {
  const tx = await getBlob(txHash)
  if (tx.age < 18_days && tx.blobData?.content) {
    return tx.blobData.content  // serve direct from blob
  } else {
    return fetchFromIPFS(tx.attestation.ipfs_cid)  // fallback
  }
}

During the 18-day window, anyone pulling the code (to verify, run it, review it) naturally becomes a potential IPFS pinner. The blob is the initial distribution mechanism. IPFS is the long-term layer.

Verification (same path regardless of source):

• Fetch content from blob or IPFS
• Compute sha256
• Compare to the hash committed in the blob tx
• Check signer matches expected publisher
• The CID was derived from the content before publishing — so no matter who pinned it to IPFS, if the hash matches, it's the real thing

---

What to Build (Phases)

Phase 1 — CLI + Base deployment

• code-attest CLI (Node.js or Go)
• Pinata integration for IPFS
• Blob tx submission on Base (cheapest, fast)
• code-attest verify <tx> command

Phase 2 — Indexer + Verify page

• Simple indexer that watches a set of addresses for blob attestations
• attest.sh/<tx> or attest.sh/<cid> — shows the attestation, lets you re-verify
• Human-readable: "deploy.sh v1.0.0 attested by austingriffith.eth on Mar 12 2026"

Phase 3 — Agent skill + SE2 template

• OpenClaw skill: agents call it as a post-build step
• Scaffold-ETH 2 template showing the full pattern
• GitHub Action for adding attestation to your release workflow

---

Why Blobs (Not Calldata or a Smart Contract)

• Blobs (EIP-4844): ~$0.001 per attestation. Data available for 18 days — enough time for indexers. Permanent tx hash as pointer.
• Calldata: Works too, more expensive, but data is in permanent tx history
• Smart contract registry: Optional upgrade — adds queryability onchain but not required for the core use case

Start with blobs. Add a contract registry later if needed.

---

Non-Goals

• Not replacing Git or GitHub for collaboration
• Not storing full file history
• Not a new token or protocol
• Not requiring everyone to use Ethereum — just the publisher attests, anyone can verify

---

Stack

• CLI: Node.js (fits the SE2/BuidlGuidl ecosystem)
• IPFS: Pinata API (or Helia for local)
• Chain: Base (cheapest, fast, Coinbase distribution)
• Wallet: viem + a local key or Safe for team use
• Indexer: simple Node.js process watching an address
• Frontend: Next.js, minimal