How to Document Cryptographic Assumptions

Cryptographic assumptions are the foundational axioms upon which the security of blockchain protocols and zero-knowledge proofs is built. Unlike mathematical theorems, these are statements about the computational hardness of specific problems—such as the Discrete Logarithm Problem or the Knowledge-of-Exponent Assumption—that are believed to be true but not proven. Formal documentation of these assumptions is critical. It provides a clear, unambiguous security model, enabling rigorous analysis, facilitating protocol audits, and allowing for the composition of different cryptographic primitives. Without this documentation, security claims are informal and vulnerable to misinterpretation.

A well-documented assumption must precisely define the adversarial model and the security game. This involves specifying the computational power of the adversary (e.g., probabilistic polynomial time), the resources they control, and the exact win condition. For example, the Strong RSA assumption is formally stated as: "Given a composite RSA modulus n and a random element y ∈ Zₙ, it is computationally infeasible for any PPT adversary to find any pair (x, e > 1) such that xᵉ ≡ y mod n." This clarity prevents "gap" assumptions where the security proof requires a stronger property than the one formally stated.

In practice, documentation should follow a structured template. Start with a Unique Identifier (e.g., DLP-G1). Then, provide a Plain Language Description for accessibility. The core is the Formal Definition, written in precise mathematical notation. Follow this with the Security Game, often described as an interaction between a challenger and an adversary. Finally, list Known Reductions to other assumptions and document any Known Attacks or parameter constraints. This structure is used by projects like the ZKProof Community Standards to create a common reference framework.

For blockchain developers, explicit documentation is essential when designing new consensus mechanisms or privacy layers like confidential transactions. If your protocol's security reduces to the assumption that "finding a hash collision is hard," you must document which hash function (e.g., SHA-256, Poseidon), the expected security level (e.g., 128 bits), and the adversary's capabilities. This allows auditors to verify that your implementation's parameters align with the assumption's requirements. Vague documentation is a major source of vulnerabilities in deployed systems.

The process also involves assumption management. As cryptanalysis advances, assumptions can be weakened or broken. Your documentation should include versioning and a reference to the academic literature. For instance, the SNARK security of many zk-rollups depends on pairing-friendly elliptic curves. Documenting this links your system to specific curve families (e.g., BN254, BLS12-381) and the associated pairing-based assumptions (e.g., q-SDH, Power Knowledge of Exponent). This creates a traceable chain of trust from your application code back to peer-reviewed cryptographic research.

Effective documentation requires a solid grasp of the underlying cryptographic primitives. You should be familiar with standard building blocks like digital signatures (ECDSA, EdDSA), hash functions (SHA-256, Keccak), and zero-knowledge proof systems (zk-SNARKs, zk-STARKs). Understanding the security properties of these primitives—such as collision resistance, pre-image resistance, and soundness—is essential for articulating what you are assuming about them. This knowledge is typically found in graduate-level cryptography textbooks or specialized courses.

The scope of your documentation is defined by the system's trust boundaries. You must clearly delineate what components are considered trusted (e.g., a specific smart contract, a hardware security module) versus what is part of the adversarial model. For example, in a rollup, you might assume the underlying L1 blockchain (like Ethereum) is secure for data availability and consensus, but the sequencer's execution is initially trusted until a fraud or validity proof is provided. Documenting this trust model prevents ambiguity about where security guarantees begin and end.

Finally, your documentation must be precise and testable. Avoid vague statements like "the system is secure." Instead, frame assumptions as falsifiable claims: "An adversary cannot produce a valid signature without the private key, assuming the elliptic curve discrete logarithm problem is hard." Reference established complexity assumptions (e.g., DDH, q-SDH) when possible. This precision allows for formal verification audits and provides clear failure conditions, which is critical for security reviews and building user trust in Web3 systems.

Cryptographic protocols are not built from first principles but rely on well-defined computational hardness assumptions. Documenting these assumptions is critical for security analysis, as it clarifies the exact trust model. For example, a protocol's security might depend on the Discrete Logarithm Problem (DLP) being hard in a specific elliptic curve group, or the RSA assumption for factoring large integers. A clear statement like "Security holds under the Computational Diffie-Hellman (CDH) assumption in group G" provides a precise benchmark for evaluation and attack surface analysis.

To document an assumption, first identify its category. Is it a general complexity assumption (e.g., P ≠ NP), a number-theoretic one (e.g., hardness of DLP), or a random oracle model idealization? Next, formalize it mathematically. Instead of "this signature is secure," specify: "The signature scheme is EUF-CMA secure under the Strong RSA assumption, where an adversary cannot forge a signature even after seeing signatures on q adaptively chosen messages." Reference the seminal paper that introduced the assumption, such as the Decisional Bilinear Diffie-Hellman (DBDH) assumption from Boneh and Franklin's 2001 identity-based encryption work.

In codebases and whitepapers, create a dedicated Assumptions section. List each assumption with its name, formal definition, known attacks or security bounds, and dependencies. For instance, the security of many zero-knowledge proof systems relies on the Knowledge-of-Exponent Assumption (KEA). Documenting this alerts reviewers to check for extractability. Use tools like Lean or Coq for formal verification to encode these assumptions as axioms, making the dependency explicit and machine-checkable within the proof structure.

Consider the real-world implications of each assumption. The Random Oracle Model (ROM) is a heuristic where hash functions are modeled as ideal random functions. While enabling efficient proofs, document that security in the ROM does not guarantee security when instantiated with a concrete hash like SHA-256. Similarly, note if an assumption is falsifiable (e.g., CDH) or not (e.g., KEA). This transparency is essential for risk assessment, as seen in debates around SNARKs relying on knowledge-of-exponent or pairing-product equation assumptions.

Finally, maintain your documentation. Assumptions can be broken or weakened by new research. For example, advances in quantum computing threaten factoring-based assumptions. Link to Cryptology ePrint Archive reports and NIST post-quantum cryptography updates. A well-documented assumption section is not static; it should be versioned and updated, serving as a living document that tracks the protocol's evolving security foundation and informs users and auditors of the inherent cryptographic risks.

Cryptographic assumptions are the bedrock of blockchain security, defining the mathematical problems a protocol relies on to be hard to solve. Common examples include the Elliptic Curve Discrete Logarithm Problem (ECDLP) for ECDSA signatures, the Decisional Diffie-Hellman (DDH) assumption for certain zero-knowledge proofs, and the Random Oracle Model (ROM) for hash function security. Explicitly documenting these assumptions is not academic; it's a critical security practice. It establishes a clear security model, allowing auditors to verify that protocol logic correctly maps to the underlying math and enabling future researchers to understand the system's trust boundaries.

Begin documentation by identifying and naming each assumption used in your system. For each, provide a formal definition. For instance, for the ECDLP, state: "Given a generator point G and a public key P = k*G on a specified elliptic curve (e.g., secp256k1), it is computationally infeasible to derive the private key k." Link this directly to its application, such as "This secures user account ownership in transaction signing." Reference the authoritative source, like a NIST standard or the original academic paper (e.g., "See the SEC 2 standard for secp256k1 parameters"). This creates a verifiable trail from specification to implementation.

Next, assess and document the implications if an assumption is broken. This is your system's risk analysis. For each assumption, describe the concrete impact: would it compromise user funds, allow double-spending, or break privacy guarantees? Quantify the risk where possible, noting if a break would require a network upgrade (hard fork) or could be mitigated with softer measures. This section should answer the question: "What happens to our protocol if the cryptography we use today is weakened tomorrow?" It forces explicit consideration of cryptographic agility and upgrade paths.

Finally, integrate this documentation into your technical specifications and code. Assumptions should be listed in a dedicated SECURITY.md or ASSUMPTIONS.md file in your repository. Use code comments to link on-chain logic, like a signature verification function, back to the documented assumption. For example, in a Solidity contract, a comment for ecrecover should reference the ECDLP assumption doc. Tools like Slither or formal verification frameworks can be configured to check that code adheres to these documented models, bridging the gap between theory and implementation.

Effective documentation of cryptographic assumptions is not a one-time task but a continuous practice that strengthens protocol security and research integrity. By formalizing assumptions—like the hardness of the Discrete Logarithm Problem (DLP) or the Random Oracle Model (ROM)—you create a clear, auditable foundation. This practice directly combats the "security by obscurity" anti-pattern and enables rigorous peer review. Teams should integrate assumption documentation into their standard development lifecycle, treating it with the same importance as code comments and test coverage.

To implement this, start by auditing an existing project. For each cryptographic component, ask: What is being assumed? and Where is this assumption stated? Use the template from this guide to create a living document. For example, a ZK-SNARK implementation should explicitly list its trusted setup requirement, the underlying elliptic curve (e.g., BN254), and the security reduction it relies on. Tools like Lean or Coq for formal verification can be used to encode these assumptions as machine-checkable properties, bridging the gap between documentation and proof.

The next step is to engage with the broader academic and developer community. Share your assumption documents in protocol repositories (e.g., GitHub) and research pre-prints (e.g., IACR ePrint). Participate in forums like the Crypto Stack Exchange to discuss edge cases. For deeper study, consult foundational papers such as "Foundations of Cryptography" by Oded Goldreich and follow the ongoing work by groups like the ZKProof Standardization Effort. Consistent, clear documentation elevates the entire field's security posture, turning individual diligence into a collective defense.

Finally, remember that assumptions evolve. A 128-bit security level considered strong today may be vulnerable to future quantum attacks. Your documentation should include a review schedule and a process for deprecating or updating assumptions based on new cryptanalysis. By making your cryptographic foundations explicit and maintainable, you build systems that are not only secure today but also adaptable for the challenges of tomorrow.