Writing a whitepaper: where the logic of a blockchain project breaks
We assemble the picture we see most often: sections come from different sources — a marketing product description, an economics draft from the founder, a technical note from engineers, and a separate investor presentation.
Each fragment reads convincingly on its own, but together they describe different projects: in one document the token is needed for access, in another for rewards, in a third for voting.
It breaks on the very first substantive question. How are rewards accrued when activity drops? What happens to locked funds when a participant exits? Who changes the system parameters, and on what basis?
If the answer has to be pieced together from three files, and it still does not add up, technical review by an investor or partner stops — not because the idea is weak, but because the logic is not assembled.
That is why we start writing a whitepaper not with text but with a model: we describe participant roles, value flows, system states, and edge cases, and check them against the prototype and contract logic.
Only after that do we assemble the structure of the whitepaper — product and problem, architecture and roles of components, economic mechanics, security and governance, roadmap and risks.
This is how a blockchain project's technical document becomes verifiable: every thesis is derived from the mechanics, not from a presentation, and is confirmed by a calculation, diagram, or reference to the implementation.
Then the same core goes into preparing an investor document — without rewriting for each audience and without discrepancies between versions.
Below we examine exactly where a project's logic gets lost and how we restore it before the document reaches an external reader.
What a well-developed document gives the team and investors
A well-developed document is written as the technical foundation of the project, not as a box-ticking exercise — and it saves the most expensive thing: engineers' and lawyers' time on explanations.
When the token model, holder rights, and smart contract logic are fixed in one text, clarifying questions on these points almost disappear: the answer lies in a specific section, not in someone's head.
The framework of such a text was set by Bitcoin — a description of the problem, mechanics, economics, and risks. We maintain this order in every project: it forces the team to answer uncomfortable questions before an investor asks them.
Terminology alignment is a separate workstream.
In blockchain projects, the same words mean different things: "emission" means different entities to a developer and a lawyer, "unlock" is confused with a share, "custodial" is interpreted in one's own way.
We fix definitions once in a glossary, and after that developers and lawyers read the same wording rather than arguing over interpretations on every call.
Documentation for an investment round works as the first filter: the fund's analyst and technical consultant use it to check the coherence of the model, the distribution of rights, and the risks.
If the sections align with each other, the first wave of discussions ends with 2-3 times fewer revisions — the version is not rewritten after every conversation but supplemented.
For the team, the effect is no smaller: a new developer or lawyer joins the project through the document, not through retellings.
This noticeably reduces the number of clarifying questions and the cost of onboarding — and keeps everyone in one terminology from the first draft to release.
Document formats: from concept to technical specification
The document format is determined not by volume but by what decision is made based on it. An investor looks for the logic of the economics, an engineer for the data model and the order of signing operations, a listing venue for evidence of feasibility. One file does not cover these roles.
Before choosing, we fix the reader and the question they must be able to answer after reading: volume is calculated from that.
| Format | When it fits | Limitations |
|---|---|---|
| Short project concept | First contact with an investor or partner: explain the task, the role of the token, and the revenue model | Does not disclose the architecture — technical review leaves questions unanswered |
| Extended whitepaper version | Listing, audit, fundraising: economics, allocation distribution, stage timelines | Discrepancy between the described logic and implemented rules — a common reason venues reject |
| Technical specification | Development and audit: data schemas, emission rules, failure handling, key requirements | Excessive for an external reader and contains details that should not be published |
Formats inherit from one another: the concept sets the frame, the whitepaper expands it into verifiable statements, and the specification fixes what the team commits to implementing.
If the public version diverges from the specification, we correct the document rather than leave the contradiction.
We also select volume for the channel: we keep the concept within 8–12 pages so it is read in full, the public version at under forty, and the specification with no upper limit, since it is read selectively by sections. We analyze which set of documents your project needs.
Stages of writing a whitepaper: from audit to handover
We fix the work order before the start: the document is assembled not from ready-made text but from a verified technical base. Therefore the first stages are collection and verification of facts, and only then wording.
At each step it is clear what has already been done and what data is still needed from the project team.
- Audit of project materials. We review repositories, token economics descriptions, distribution schemes, presentations, and correspondence with partners. We note contradictions and places where numbers do not align with each other.
- Interviews with the team. We clarify roles, system design, limitations, and the development plan. Here we also close gaps that cannot be determined from documents.
- Document logic outline. Before the text, we assemble the framework: sections, order of arguments, what is proven in each. This is noticeably cheaper than revisions in already written sections.
- Text assembly. We write according to the outline, maintaining a unified glossary and consistent notation across all parts of the document.
- Consistency check. We verify numbers, definitions, and statements across sections — the version in the economic part must match the technical one.
- Final handover to the team. We provide source files in an editable format, the structure, the glossary, and a list of data that should be updated as the project develops.
This is how the document remains alive: the team can edit it themselves without losing the logic or breaking connections between sections.
What the package includes: diagrams, models, regulations
A project's public document is not just text. We deliver a package by which the engineering team, lawyers, and investors read the same picture: the document itself, architecture diagrams, a description of the economic model, and rules for working with the text going forward. Below is what exactly is included in the deliverable.
- Document text — from the problem statement and participant roles to consensus logic, transaction route, and the boundaries the system does not cross.
- Project architecture diagrams — network layers, node roles, data flows, and integration points with external services; labels in the diagrams match the terms in the text.
- Model description — issuance and circulation rules, distribution of rights, conditions for changing parameters, and consequences for already issued obligations.
- Roles and access matrix — who initiates an operation, who confirms it, and who has the right to cancel it.
- Glossary of terms — one term has one meaning across all sections, without "as preferred" synonyms.
- Document update policy — who makes edits, how often review is performed, how changes are agreed, and who approves them.
- Versioning procedure — revision numbering, change log, and archive of previous approved versions with the ability to return to any of them.
- Appendices — model calculations, data sources, and open questions with an owner for each.
We provide source files in an editable format together with the approved version so the document can be developed without us. We separately record a discrepancy checklist: if after edits a diagram no longer matches the model text, this is visible before publication, not after.
Case: reworking a document before a discussion round
Before reworking
The team came with an already assembled White Paper: the protocol's technical logic was described in detail, while token distribution, holder rights, and the unlocking procedure were smeared across the text.
Investors spent up to two weeks on the first review of materials, and brought the same list of questions to every meeting — from emission to who can change the rules and how.
We started the rework not with text but with a map of questions: we collected more than thirty written clarifications from correspondence with funds and sorted them by section.
The distribution model was moved into a separate block with an allocation table and an unlocking chart, and next to it we described governance roles and decision-making thresholds.
The economic mechanics were compressed into three scenarios instead of a vague description, and the logic of smart contracts on Solidity — into behavior: what happens on early withdrawal and when parameters change.
After reworking
Written clarifications dropped to six instead of thirty-plus, and these are questions about the terms of a specific round, not about the project's design.
The "explain the basic mechanics" class disappeared entirely — it is answered by the section with the chart and table. Time for the first review of materials fell from two weeks to two–three days, and the team stopped repeating the same thing at every meeting.
At the same time, we fixed document versions: the investor edition, the technical appendix, and a two-page summary for first contact.
From then on, the document works as a source of truth — edits to tokenomics or roles are made in one place and do not diverge across presentations.
How a concept document differs from technical documentation
A concept document, or whitepaper, and technical documentation answer different questions and are read by different people. The first explains why the project exists and why its mechanics work; the second explains how everything is assembled and what to do in case of failure.
Mixing them into one text means either scaring the reader away with details or leaving the team without working documentation.
The public part includes the problem statement, protocol operating principles, participant roles, economic rules, and trust boundaries: what is guaranteed by code and what rests on organizational agreements.
Remaining risks are also stated here — verifiable claims convince more strongly than loud promises, because the reader can open the network and compare what is claimed with the actual state.
The closed part is the project's internal documentation: contract specifications, threat model, release and rollback policies, key management procedures, and access rights.
These materials are shared with auditors and partners under a non-disclosure agreement but are not published: they do not add trust for the reader, while directly helping someone looking for an attack vector.
Information disclosure boundaries are set by a simple rule: we publish what is already verifiable on the network, and we hold back what gives an attacker an advantage.
Reasonable omission does not undermine trust if it is stated explicitly — what undermines it is a discrepancy between promise and code. Therefore, in a separate section we record what is moved to the internal perimeter and why: this removes questions before they become claims.
Technical doubts worth resolving before starting
A document is almost always prepared before the network parameters, token economics, and governance model are fixed. Therefore questions at this stage are not about formatting but about how to describe a decision that does not yet exist and what to do with the document next.
We answer them before work starts: this prevents rewriting sections at the stage when the text has already been approved by all parties.
Who writes the document — the project's engineers or the author?
A combination works: your engineers provide the substance — architecture, consensus mechanism, economics — and the author translates it into structure and coherent exposition.
Sections on the protocol and tokenomics cannot be written from the outside, while it is useful to take the narrative logic outside the team. This keeps the document accurate and at the same time readable for an investor and auditor.
Some decisions are not yet fixed — what should be written in these sections?
We mark such places as preliminary: we indicate the working range, what the final choice depends on, and by what criterion it is made. This is more honest than guessing and does not force rewriting the document after every model change. Once a decision is made, the section is edited locally, without reassembling the structure.
How is the document updated after the network launch?
The structure is designed to be extensible from the start: numerical parameters are kept in separate blocks so they can be changed independently of the architecture description.
We return to updates as new protocol versions are released, and the change history is maintained directly in the file.
How confidential are the materials provided?
Diagrams, economic calculations, and unreleased parts of the architecture remain under a non-disclosure agreement, with access only for the engineers working on the document.
Drafts are not published or shared with third parties, and once work is complete, you can also restrict our storage of copies.
Let's discuss the task and come back with a work plan
To discuss the task substantively, you do not need a ready document with dozens of pages of description — initial inputs are enough to show the essence of the project and the boundaries of the future text. We clarify the rest in conversation, not through two weeks of correspondence.
- project idea in 5–10 sentences: what problem the product solves, for whom it is created, and what already works;
- current state: whether there is a prototype, code, economic calculations, or so far only a concept;
- audience of the document — investors, partners, a regulator, or the technical community: section depth and language depend on it;
- what has already been written: drafts, presentations, internal notes — we take them as source material, so nothing has to be retold from scratch;
- requirements of the venue or client for which the document is being prepared: mandatory sections, volume, language, delivery format;
- desired deadline and points where your approval is needed during the work.
Based on these inputs, we build a work plan for the document: section structure, which engineers and analysts lead each block, the approval sequence, and the timeline.
The plan immediately shows which data you already have and which still needs to be collected — we go over this on the first call. We provide layout source files so the document can be edited and updated on your own.
Describe the task in free form — we will come back with an estimate and plan and say what to take into work first.