Cosmic Bull

An autonomous Gno.land application engineering agent — an application factory.

Cosmic Bull takes an application objective and carries it end to end:

IDEA
  → DISCOVERY        find what already exists; do not rebuild it
  → ARCHITECTURE     decide the state shape and the authority model
  → REUSE            compose existing /p/ and /r/ before creating new
  → GNO CODE         write it, or port/remediate an existing implementation
  → TEST             unit + filetests against a chain-matched toolchain
  → AUDIT            adversarial review, RED / YELLOW / GREEN, evidence-gated
  → PEARL VALIDATION compile and simulate against the live target chain
  → DEPLOYMENT       Pearl-1 only, from verified bytes
  → LIVE VERIFICATION byte-match the deployed source; then attack it
  → DOCUMENTATION    a provenance record that a stranger can re-check

This repository is the canonical source of truth for the Cosmic Bull project itself — its operating rules, methodology, catalogs, and deployment records. It is not the source of truth for the individual applications. Each application lives in its own repository; this repo points at the exact commit that was deployed. See Source-of-truth boundary.

What Cosmic Bull is designed to do

• Discover existing Gno software before writing any — on-chain, in the ecosystem, and in its own catalog.
• Avoid unnecessary duplication. A second implementation of something that already works is a liability, not an achievement.
• Compose reusable primitives rather than growing bespoke infrastructure.
• Build and remediate Gno applications, including porting existing code onto current chain semantics without redesigning it.
• Test and adversarially audit — every finding backed by a quoted line.
• Validate Pearl compatibility before spending a transaction.
• Deploy to Pearl-1 through a single audited mechanism.
• Verify deployed source byte-for-byte against the commit it claims.
• Perform live functional and adversarial verification on the real chain.
• Maintain provenance — repository → SHA → transaction → realm → record.

The goal is not maximum code generation. The goal is useful applications produced through maximum appropriate reuse and rigorous verification.

The Gno architecture Cosmic Bull works in

Gno.land runs an interpreted Go-derived VM where source code lives on-chain. Every code unit is a package, and the path prefix is the kind:

/p/ — pure packages

• Stateless. No persistent state of their own; frozen after init.
• Composable infrastructure. Types, algorithms, guards, plumbing.
• Cannot declare crossing functions, so they cannot hold authority — a /p/ helper that needs a realm capability must take it as a parameter and check rlm.IsCurrent() before trusting it.
• This is where reuse pays. A correct /p/ primitive is imported by every later realm at zero marginal audit cost.

/r/ — realms

• Stateful. Persistent state across transactions; globals survive.
• User-facing application logic. Public crossing functions are the API.
• Hold an address, can hold funds, and carry an authority model.
• Deployed bytes are immutable — there is no upgrade in place. A realm is either right when it ships or it is replaced at a new path.

Why Cosmic Bull searches /p/ and /r/ before building

Three reasons, in order of weight:

1. Immutability makes mistakes permanent. A realm you deploy is a realm you live with. Reusing an already-audited, already-live primitive imports its track record along with its code.
2. Every new line is new audit surface. Duplicated infrastructure doubles the attack surface for zero new capability.
3. The ecosystem is real and reachable. The chain can be enumerated. Not searching it is a choice to be ignorant, not a constraint.

See docs/DISCOVERY_AND_REUSE.md for the mandatory gate that enforces this.

The application-factory thesis

The longer-term objective: Cosmic Bull accepts an application objective and decides how to satisfy it — choosing among four strategies rather than defaulting to the last one.

Strategy 4 is the expensive one, and it is the last resort by design. The discovery gate exists to make sure the agent has actually checked before claiming it.

The five pipeline applications are all strategy 3 — existing SillyZir GitHub applications ported onto current Pearl semantics, audited, remediated, and deployed. Four /p/ primitives now exist: feeledger and coinio were extracted from repeated realm code (strategy 4, with recorded reasoning) and are reused by later realms (strategy 1); duebook was written from an objective after discovery eliminated reuse, composition and adaptation (strategy 4 again, arrived at by a different route); permbook is strategy 4 and strategy 1 at once — it was written only against a quoted structural limit in an incumbent Cosmic Bull realm that discovery recorded as otherwise satisfying the objective, and it composes an ecosystem container package rather than writing one.

The portfolio

Live on pearl-1: 4 /p/ primitives · 15 application realms · 5 applications completed through the GitHub → Pearl pipeline · 5 applications built objective-first by the application factory.

(Two additional throwaway realms, cointest and cointest2, exist on-chain as validation helpers. They are not products and are excluded from the count of 15 — see catalog/README.md.)

Reusable /p/ primitives

The five GitHub-pipeline applications

All deployed under the namespace gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/… on pearl-1.

Full per-application records — architecture, reused primitives, discovery classification, audit findings, live verification, and limitations — are in catalog/applications.md. The authoritative transaction-level records are in pearl/DEPLOYMENT.md.

One divergence, recorded rather than hidden. SillyZir/fee_split has since moved to e5aadfebc890c21ade4076e1d75c9c0e0dd77809, a pushed remediation that is not deployed. The live fee_split v1 remains frozen at the bytes derived from 819239a. No fee_split_v2 exists. Do not "reconcile" the two by redeploying.

Earlier portfolio realms (pre-pipeline)

Application-factory realms (objective-first)

Built from a stated objective rather than ported from an existing repository: discovery decides the strategy, and the five runs so far chose differently.

Build #1 reused the existing primitives and subtracted; build #2 found nothing that performed an effect under the consumer's own authority and wrote a new one; build #3 found that Cosmic Bull's own live permission_registry already satisfied the objective, recorded that first, recommended it, left it untouched, and built only against the one property it could not work around — caps that are global, shared and unraisable on an immutable realm. Builds #4 and #5 are pure composition: one new state machine each over the same audited value-handling primitives. All five decisions are argued from enumerated evidence in their respective DISCOVERY.md files.

Security philosophy

Full treatment in docs/SECURITY.md. The load-bearing principles:

• Source provenance. Deployed bytes are verified against the committed bytes of a named commit, before broadcast and after, via vm/qfile. A deployment record without a byte match is not a deployment record.
• Caller identity from the realm capability, not the stack. Identity comes from a crossing entrypoint's runtime-current cur.Previous().Address(). Stack-walking PreviousRealm() inside a non-crossing helper is a bug class, and it was found in every one of the five applications.
• Authorization boundaries. Holding a permission is not holding admin. Authority moves, it does not copy. The deployer holds no residual privilege unless the design says so and the tests prove it.
• Adversarial testing. Every application is attacked live on-chain after deployment, with the abort messages byte-matched against audited source.
• Stray-send rejection. A realm with no banker must refuse attached coins, or they strand at its address forever. All five applications ship the guard.
• Value invariants. Conservation identities (held == users + fees + surplus and friends) are checked against real bank state at every checkpoint, not asserted in a comment.
• Deterministic execution. Ordered iteration for anything that reaches Render; no map iteration in output paths.
• Bounded attacker-controlled state. Anything a third party can grow must be capped, and the rendering of it must be bounded.
• RED / YELLOW / GREEN methodology. RED and material YELLOW findings are resolved before deployment. Findings are never downgraded to reach a deploy.
• Live verification. Reads, writes, and attacks against the real deployed realm, recorded by transaction hash.
• Unresolved limitations stated explicitly. Coverage that was not achieved is written down as not achieved — including why.

Deployment philosophy

Full treatment in docs/DEPLOYMENT.md.

• Pearl-1 is the current deployment target.
• Mainnet is NOT an automatic deployment target. It requires a separate, explicit authorization and has never been used by this pipeline.
• One deployment mechanism. Deploys go through the Gno MCP gno_addpkg tool, simulate-first. No raw gnokey, no shell signing, no key-file access.
• Live realms are immutable and are never redeployed as a side effect of other work.

The application-level authorization model

Once an application is explicitly selected for the pipeline, Cosmic Bull may carry it through the full bounded lifecycle without artificial authorization gates at each stage:

DISCOVERY → ARCHITECTURE → REUSE ANALYSIS → PORT / REMEDIATION → TEST
  → AUDIT → GITHUB COMMIT/PUSH → FRESH GITHUB VERIFICATION
  → PEARL VALIDATION → PEARL DEPLOYMENT → LIVE VERIFICATION
  → DEPLOYMENT RECORD

Human approval happens at the application level, not at every stage. A routine, clearly-scoped implementation problem is fixed, retested, re-audited and carried forward.

It must stop and report for unexpected material:

• security issues not covered by the current audit
• unresolved RED or material YELLOW findings
• source divergence from the verified commit
• signer or key mismatch
• deployment target collisions
• network changes
• materially different economics (cost, custody, privilege)
• architectural changes, or a need to build a different application
• any mainnet involvement
• changes to unrelated repositories or live applications

Completing one application never authorizes starting the next.

Authorship

Every commit in every Cosmic Bull repository:

Author:    SillyZir
Committer: SillyZir

No Co-authored-by: Claude. No Co-authored-by: Anthropic. No AI attribution trailer of any kind. Direct commits to main; no pull requests unless explicitly requested; no history rewriting; no force-pushes.

Authorship is verified after every push, and scanned across the full commit history — not just the tip.

Source-of-truth boundary

The pearl/r/<app>/ directories in this repo hold the port + remediation working trees for the pipeline applications. They exist as audit evidence and are deliberately not presented as the applications' source of truth. Where a working tree diverges from the live realm, that divergence is recorded in pearl/INFRASTRUCTURE.md.

Repository layout

README.md                     this file
CLAUDE.md                     permanent operating rules for the agent
docs/
  ARCHITECTURE.md             Gno model, /p/ vs /r/, interrealm semantics
  APPLICATION_FACTORY.md      the four strategies and how one is chosen
  DISCOVERY_AND_REUSE.md      the mandatory discovery gate
  DEPENDENCY_CLOSURE.md       proving tests ran against what the chain executes
  CATALOG.md                  the portfolio manifest, its verifier, and the API reference
  SECURITY.md                 audit methodology + accumulated findings
  DEPLOYMENT.md               deployment process and philosophy
  TOOLCHAIN.md                chain-matched toolchain, reusable gotchas
  CONTRIBUTING.md             authorship, commit rules, working agreements
  ECONOMICS.md                two-track economic architecture (protocol fees +
                              commercial services) — a proposal, nothing
                              deployed; not rendered on the public site
tools/
  verify_depclosure.py        the dependency-closure equivalence checker
  test_verify_depclosure.sh   its test suite (22 tests, 11 negative)
  portfolio_depclosure.sh     every deployed package with committed source in one run
  verify_catalog.py           proves the catalog against the chain and the source
  test_verify_catalog.sh      its test suite (89 tests)
  gen_api_docs.py             generates catalog/api/ from vm/qdoc; --check for drift
  test_gen_api_docs.sh        its test suite (36 tests)
  gen_site.py                 builds the cosmicbull.net static site into site/ (gitignored)
  sitemd.py                   its Markdown renderer, scoped to the measured construct inventory
  test_gen_site.sh            their test suite (193 tests, offline by assertion)
pearl/
  DEPLOYMENT.md               authoritative transaction-level records §1–§17
  INFRASTRUCTURE.md           live infrastructure catalog + known divergences
  p/                          feeledger, coinio, duebook, permbook (authored here)
  r/                          portfolio realms + pipeline working trees
catalog/
  README.md                   how to read the catalog
  applications.md             pipeline + factory application records
  primitives.md               the four /p/ primitives + the realms that use them
  portfolio.json              the same inventory, machine-readable and verified
  api/                        the exported API of every package, generated from the chain
  DISCOVERY.md                discovery record behind the manifest
  DISCOVERY_APIDOCS.md        discovery record behind the API reference
  DISCOVERY_SITE.md           discovery record behind the cosmicbull.net static build
benchmarks/
  README.md                   what has been benchmarked and what it proved
p/tally, r/upvotes            first vertical slice — local only, never deployed

Status

Pipeline applications #1–#5 and factory builds #1–#5 are live, verified, and closed. No application is currently in flight.

• snapshot_poll — not started, not deployed.
• fee_split_v2 — does not exist.
• mainnet — never used by this pipeline.

These are not assertions from the records. The namespace was enumerated live on pearl-1 (height 640217, block_time 2026-09-23T03:16:51Z) and returns exactly twenty-one packages — the 4 primitives, the 15 application realms, and the 2 validation helpers. fee_split_v2 and snapshot_poll are absent from the chain, and fee_split appears once.

That enumeration is no longer a hand-check. tools/verify_catalog.py re-derives it, compares it in both directions against catalog/portfolio.json, and re-proves every recorded height, transaction, byte hash and import for all twenty-one: VERIFIED — 877 checks, 0 findings on 2026-09-22. See docs/CATALOG.md for what that does and does not cover.

Using the code

Provenance answers are these the right bytes. It does not answer how do I call them. catalog/api/ does: the exported API of all twenty-one packages — signatures, doc comments, types, methods and crossing-function flags — generated from vm/qdoc on the live chain and re-checkable with tools/gen_api_docs.py --check (MATCHES — 22 pages, 372 exported symbols from 21 packages, 2026-09-22).

For realms, gnoweb's live $help view is better still and every page links to it — it carries a generated gnokey maketx call command. For the four /p/ primitives it is not: $help renders exported top-level functions only, so it shows 11 of their 67 exported symbols and none of their methods or types. Deployed bytes are immutable, so that cannot be repaired on chain. The measurement, and the decisions not to build an API service or an on-chain docs realm, are in catalog/DISCOVERY_APIDOCS.md. The site that record deferred has since been built: tools/gen_site.py renders the manifest, the API reference and the committed records into site/ — a gitignored build output, offline and hermetic by construction, serving localhost only. It is not deployed; the discovery record behind it is catalog/DISCOVERY_SITE.md.