commonware

Primitives

Primitives are designed for deployment in adversarial environments. If you find an exploit, please refer to our security policy before disclosing it publicly (an exploit may equip a malicious party to attack users of a primitive).

• actor: Safely coordinate concurrent components.
• broadcast: Disseminate data over a wide-area network.
• codec: Serialize structured data.
• coding: Encode data to enable recovery from a subset of fragments.
• collector: Collect responses to committable requests.
• conformance: Automatically assert the stability of encoding and mechanisms over time.
• consensus: Order opaque messages in a Byzantine environment.
• cryptography: Generate keys, sign arbitrary messages, and deterministically verify signatures.
• deployer: Deploy infrastructure across cloud providers.
• glue: Default constructions that span multiple primitives.
• math: Create and manipulate mathematical objects.
• p2p: Communicate with authenticated peers over encrypted connections.
• parallel: Parallelize fold operations with pluggable execution strategies.
• resolver: Resolve data identified by a fixed-length key.
• runtime: Execute asynchronous tasks with a configurable scheduler.
• storage: Persist and retrieve data from an abstract store.
• stream: Exchange messages over arbitrary transport.

Examples

Examples may include insecure code (i.e. deriving keypairs from an integer arguments) to make them easier to run. Examples are not intended to be used directly in production.

• alto: A minimal (and wicked fast) blockchain built with the Commonware Library.
• battleware: An onchain battle secured by a VRF, Timelock Encryption, and MMRs.
• bridge: Send succinct consensus certificates between two networks.
• chat: Send encrypted messages to a group of friends.
• estimator: Simulate mechanism performance under realistic network conditions.
• flood: Spam peers deployed to AWS EC2 with random messages.
• log: Commit to a secret log and agree to its hash.
• reshare: Reshare a threshold secret over an epoched log.
• sync: Synchronize state between a server and client.

Miscellaneous

Sometimes, we opt to maintain software that is neither a primitive nor an example to make it easier to interact with the Commonware Library. Unless otherwise indicated, code in this section is intended to be used in production. Please refer to our security policy before disclosing an exploit publicly.

• docs: Access information about Commonware at https://commonware.xyz.
• docker: Dockerfiles used for cross-compilation and CI.
• formatting: Format and parse encoded data.
• invariants: Define and exercise invariants.
• macros: Augment the development of primitives with procedural macros.
• mcp: Interact with the Commonware Library via MCP at https://mcp.commonware.xyz.
• pipeline: Mechanisms under development.
• utils: Leverage common functionality across multiple primitives.

Stability

All public primitives (and primitive dialects) in the Commonware Library are annotated with a stability level:

Stability is transitive in the Commonware Library; primitives only depend on primitives with equal or higher stability. All examples are considered to be at ALPHA stability (and will continue to be for the foreseeable future).

Users employing the Commonware Library can compile with the commonware_stability_<level> configuration flag to both view scoped documentation and enforce their application only depends on primitives of a minimum stability:

# Generate docs for only code with stability >= BETA (level 1)
RUSTFLAGS="--cfg commonware_stability_BETA" RUSTDOCFLAGS="--cfg commonware_stability_BETA -A rustdoc::broken_intra_doc_links" cargo doc --open

# Check if your application only uses commonware APIs with stability >= BETA
RUSTFLAGS="--cfg commonware_stability_BETA" cargo build -p my-app

Licensing

This repository is dual-licensed under both the Apache 2.0 and MIT licenses. You may choose either license when employing this code.

Contributing

We encourage external contributors to submit issues and pull requests to the Commonware Library. To learn more, please refer to our contributing guidelines.

All work is coordinated via the tracker. If something in the backlog looks particularly useful, leave a comment so we can prioritize it!

MCP Support (for LLMs)

Make your LLM more effective by connecting to the Commonware Library MCP server. Learn more here.

Claude Code

claude mcp add --transport http commonware-library https://mcp.commonware.xyz

Cursor

{
  "mcpServers": {
    "commonware-library": {
      "url": "https://mcp.commonware.xyz"
    }
  }
}

Support

If you have any questions about using the Commonware Library, we encourage you to post in GitHub Discussions. We're happy to help!