[QuantumExplorer]

Basic explanation

What this does: Drive stores each document type as a set of nested GroveDB trees: one for the documents and, for every index, a tree per indexed property and per value, down to where the index ends. Which kind of tree each one is depends on the index's keywords: a plain tree, a tree that counts or sums its entries, a ranked tree, and so on. Until now the only way to see this for a real contract was to read the insert code. This PR adds a function, document_type_layout, that computes the layout of any document type from the contract alone, using the same rules Drive uses when it inserts documents. It is exposed to JavaScript as documentTypeLayout(contract, documentTypeName, platformVersion) in wasm-sdk, and so in @dashevo/evo-sdk.

Value:

• App developers and reviewers can see how a document type is stored, and what an index keyword costs in storage and proofs, without reading Drive.
• The contract visualizer can show it per document type, and link each layer to the GroveDB structure viewer, where the general description of that kind of layer lives.
• A test holds the function to what Drive really writes: it inserts documents for 19 contracts and fails if any stored element differs from the computed layout, or if the layout names a layer Drive did not write. The layout cannot quietly go stale.

Risks: Low, and no consensus change.

• The insert, update and delete walkers are touched only to move three small decisions they already made into shared functions, so the walkers and the layout use the same code. Nothing else in them changes. The decisions and error messages are identical, and the rs-drive document tests pass.
• The layout follows the walkers of protocol version 14 (unreleased). For an earlier version, whose walkers pick other trees for some shapes, it refuses rather than return a layout Drive does not write.
• Three rule files now also compile under rs-drive's verify feature (the one wasm-sdk uses). No new crate enters the wasm build: grovedb already depends on grovedb-merk there.

Issue being fixed or feature implemented

The contract visualizer needs a way to show a document type's index structure. The GroveDB structure description (grovedb-structure.json) covers every document type at once, so its document layers are templates: "an index property" that can be any of 8 tree kinds. The rules that pick the kind for a given index (primary_key_tree_type, property_name_tree_type_and_ranked_axes_for_level, index_level_tree_types_with_continuation_demotion, terminal_member_tree_type, and the wrapper choice for continuation trees) were server-only, so no client could compute a concrete layout.

What was done?

• drive::document::layout (new, server or verify):
  • document_type_layout(document_type, platform_version) -> DocumentTypeLayout walks the document type's IndexLevel structure. It refuses (UnknownVersionMismatch) a platform version whose index walkers are not v2, i.e. before protocol version 14. For each layer it gives:
    • the key: fixed (the type name, [0], a property name, a time-window grid key such as $createdAt#86400#3600, a flat indexOnly key) or a family of keys (the document id, a property's values, the window starts, an indexOnly entry's terminal components, the revision time);
    • the element: the tree type, or Item / ItemWithSumItem / Reference / ReferenceWithSumItem;
    • the zero-contribution wrapper (NonCounted, NotSummed, NotCountedOrSummed), and the ranking axes of an indexed tree;
    • the indexes that use the layer;
    • conditions as notes: indexOnly, nullSearchable, contested, skipIfAbsent, preallocated, time-window overlap and TTL. skipIfAbsent is noted only on a property that can be absent: an optional, non-system property of an indexOnly type, the only case where Drive skips the entry.
  • A unique index's [0] records its alternative: the tree of members Drive writes instead when a value is null. The alternative does not repeat the [0]'s indexes and notes.
  • Each layer names the node of the structure description it is an instance of (structure_node()), for linking to the viewer.
  • to_value() gives the JSON shape the SDK returns. A layer that has no wrapper or no alternative leaves the key out, and time-window seconds are plain numbers (not BigInts) in JavaScript.
  • For Rust callers, ZeroContributionWrapper is re-exported from layout, and LayoutRole::name and LayoutNote::code (the codes to_value emits) are public.
• Shared rules:
  • primary_key_tree_type, ranked_index_tree_type and index_level_tree_types compile under verify as well as server, taking TreeType from grovedb-merk (a new optional direct dependency of rs-drive, enabled by both features). time_range_index_keys, which needs server-only key types, stays server-only.
  • The wrapper matrix of LowLevelDriveOperation::for_known_path_key_empty_tree_contributing_zero_to_parent moved into zero_contribution_wrapper, which returns a typed refusal; the dispatcher maps each refusal to its existing error text.
  • The condition "does this continuation tree contribute zero to its parent value tree", inlined in the v2 index walker, the preallocation path and the v1 update walker, moved into continuation_contributes_zero and level_counts_continuations.
  • The skipIfAbsent condition of the v2 top-level insert and delete walkers ("an unrequired property of an indexOnly type") moved into index_only_level_skips_when_absent, which the layout's note uses too.
• wasm-sdk: documentTypeLayout(contract, documentTypeName, platformVersion), with a DocumentTypeLayout TypeScript type. evo-sdk re-exports it. It borrows the contract through a new AsRef<DataContract> for wasm-dpp2's DataContractWasm, rather than cloning it.
• Docs: a One document type's layout section in the book's GroveDB structure chapter, and a How a document type is stored section in the evo-sdk README.

In-place changes to shipped generations

• add_indices_for_index_level_for_contract_operations v2 and the preallocation path now call continuation_contributes_zero(parent_value_tree_type, parent_counts_continuations, sub_level). The function returns exactly what the inlined condition did: !matches!(parent_value_tree_type, TreeType::NormalTree) && (!parent_counts_continuations || sub_level.count_exempt_branch()). level_counts_continuations(level) is the inlined level.ranked_count_grouping() || level.count_propagating().
• for_known_path_key_empty_tree_contributing_zero_to_parent now matches on zero_contribution_wrapper, a direct transcription of its former match:
  • same arms, same helper for each (NonCounted, NotCountedOrSummed, NotSummed, or the unwrapped insert);
  • same four NotSupported errors, with the same text.
• update_document_for_contract_operations v1 (the update walker protocol version 14 selects) now calls the same two functions: at its two continuation dispatches (plain and bucketed) and at the four places it tracks whether a level counts its continuations. Each matches!(parent_value_tree_type, TreeType::NormalTree) || (parent_counts_continuations && !level.count_exempt_branch()) is !continuation_contributes_zero(parent_value_tree_type, parent_counts_continuations, level), and each level.ranked_count_grouping() || level.count_propagating() is level_counts_continuations(level).
• add_indices_for_top_index_level_for_contract_operations v2 and remove_indices_for_top_index_level_for_contract_operations v2 now skip with index_only_level_skips_when_absent(document_type, property_name), which returns exactly the inlined document_type.index_only() && !document_type.required_fields().contains(property_name).
• These are used by the v2 walkers and the v1 update walker, which only protocol version 14 (unreleased) selects. The refactor cannot change what is written for any input, and the rs-drive document tests, whose index tests insert, update and delete through these paths, pass unchanged.

Before and after

The marketplace example's listing type (byShop over shopId, $createdAt countable; byCategoryPrice; newListings, a daily window stepping hourly over $createdAt, countable; documentsCountable):

• Before: the structure viewer shows index_property → value → members / next_property, each "one of" several tree kinds. Which kind listing gets is only in the insert code.
• After: documentTypeLayout(contract, 'listing', v14), printed as a tree:

listing  Tree
├─ PrimaryKey  CountTree
│  └─ <documentId>  Item
├─ $createdAt#86400#3600  Tree  [newListings]
│  └─ <$createdAt window>  CountTree  [newListings]
│     └─ Members  CountTree  [newListings]
│        └─ <documentId>  Reference
├─ category  Tree  [byCategoryPrice]
│  └─ <category>  Tree  [byCategoryPrice]
│     └─ price  Tree  [byCategoryPrice]
│        └─ <price>  Tree  [byCategoryPrice]
│           └─ Members  Tree  [byCategoryPrice]
│              └─ <documentId>  Reference
└─ shopId  Tree  [byShop]
   └─ <shopId>  Tree  [byShop]
      └─ $createdAt  Tree  [byShop]
         └─ <$createdAt>  CountTree  [byShop]
            └─ Members  CountTree  [byShop]
               └─ <documentId>  Reference

An indexOnly type with a ranked, summed index (the Drive test contract's tip), and DPNS's unique name index with its fallback:

tip  Tree
├─ $ownerId  Tree  [byTipperAmount]
│  └─ <$ownerId>  Tree  [byTipperAmount]
│     └─ amount  Tree  [byTipperAmount]
│        └─ <amount>  Tree  [byTipperAmount]
│           └─ Members  Tree  [byTipperAmount]
│              └─ <postId>  Item
└─ postId  ProvableCountProvableSumIndexedTree ranked by count,sum  [byPost]
   └─ <postId>  ProvableCountProvableSumTree  [byPost]
      └─ Members  ProvableCountProvableSumTree  [byPost]
         └─ <$ownerId>  ItemWithSumItem

domain  Tree
├─ PrimaryKey  Tree
│  └─ <documentId>  Item
├─ normalizedParentDomainName  Tree  [parentNameAndLabel]
│  └─ <normalizedParentDomainName>  Tree  [parentNameAndLabel]
│     └─ normalizedLabel  Tree  [parentNameAndLabel]
│        └─ <normalizedLabel>  Tree  [parentNameAndLabel]
│           └─ Unique reference  Reference  [parentNameAndLabel]
│                 (when an indexed value of the document is null: Tree of <documentId> Reference)
└─ records.identity  Tree  [identityId]
   └─ ...

How Has This Been Tested?

• cargo test -p drive --lib drive::document::layout: 5 tests.
  • should_lay_out_what_drive_writes applies 19 contracts from tests/supporting_files: family (plain, optional fields, countable, with history), dashpay, references, restaurants, trending (with the sibling variant), the Yappr likes (plain and two preallocated variants), the Yappr feed, index-only scalar terminal, tally, tip-jar, and grades (plain, ranked, compound ranked).
  • It inserts 7 random documents per type; two leave out the optional properties of unique indexes, so the null fallback is written. It then walks GroveDB under every document type and compares every element's kind and wrapper with the layout. It also checks the other way: every layer the layout names under a tree Drive wrote must have been written, except where a document may leave it empty (a terminal with nullSearchable: false, a preallocated terminal's entries, a skipIfAbsent level's values). It also requires the fixtures to reach every layer role, at least one wrapper, one ranked tree, one time window, one index entry and one null fallback.
  • Summed properties get small values, because random integers ignore the schema's bounds and overflow a provable sum tree.
  • Mutation checks: making the layout's terminal trees always plain fails the test, with messages like Terminal "Members" ... Drive wrote CountTree where the layout says Tree. Giving indexOnly types a primary key tree fails it with the layout has PrimaryKey "PrimaryKey" but Drive wrote nothing there.
  • should_name_a_node_of_the_structure_description_for_every_layer checks each role's structure_node() against drive_structure().
  • should_store_each_document_of_a_type_with_history_as_a_tree_of_revisions.
  • should_refuse_a_version_that_selects_other_index_walkers: protocol version 13 (v1 walkers) is refused, the latest is not.
  • should_skip_only_an_optional_property_of_an_index_only_type_when_absent: in the Yappr likes contract, the required mark.a and the system $ownerId carry no skip note, the optional mark.b does, and tip (not skipping) has none.
• cargo test -p drive --lib: 3947 passed, 6 ignored, 0 failed.
• cargo clippy -p drive --all-targets, cargo clippy -p drive --no-default-features --features verify, and cargo clippy -p wasm-sdk -p wasm-dpp2 --target wasm32-unknown-unknown: clean. cargo fmt: clean.
• yarn workspace @dashevo/wasm-sdk build, then mocha tests/unit/document-type-layout.spec.ts: 7 passing. The spec covers:
  • the document type and primary key;
  • a time window level, with its grid key and its window, range and step seconds as numbers;
  • a countable terminal and a shared prefix, whose continuation is wrapped in NonCounted;
  • a unique reference with its null fallback;
  • a ranked ProvableCountIndexedTree with a count axis;
  • an indexOnly member key;
  • an unknown type refused.
• eslint on the new spec: clean.
• Not run locally: the Karma browser run of the wasm-sdk spec, and drive-abci (it does not use the changed crate-private functions).

Breaking Changes

None.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · f3e69c4

• Bots — coderabbitai not yet · thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
• Self-review — post /self-reviewed once the bots are done
• Within your 5 open PRs — this one is beyond the limit; it waits until one merges
• Build running
• Approvals
  • files with no dedicated owner — you own it
  • js-wasm-sdk (packages/js-evo-sdk/README.md, packages/wasm-sdk/src/document_type_layout.rs, packages/wasm-sdk/src/lib.rs and 1 more) — shumkov
  • rs-drive — you own it

When every box is checked the PR Hygiene check passes and this can merge.

Summary by CodeRabbit

• New Features
  • Added the documentTypeLayout API, which locally shows how a document type is stored, including its indexes, tree and element types, and conditional layout choices.
  • Added layout documentation and examples.
• Bug Fixes
  • Improved consistency in how empty index continuation trees contribute to parent counts and sums.

[github-actions]

📖 Book Preview built successfully.

Download the preview from the workflow artifacts.
To view locally: download the artifact, unzip, and open index.html.

Updated at 2026-09-28T20:28:38.302Z

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: dashpay/platform/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: f45de5c1-2374-44e5-b471-92a1d84f5500

📥 Commits

Reviewing files that changed from the base of the PR and between 1464314 and dd60f0b.

📒 Files selected for processing (14)

• book/src/drive/grovedb-structure.md
• packages/js-evo-sdk/README.md
• packages/rs-drive/Cargo.toml
• packages/rs-drive/src/drive/document/index_level_tree_types.rs
• packages/rs-drive/src/drive/document/insert/add_indices_for_index_level_for_contract_operations/v2/mod.rs
• packages/rs-drive/src/drive/document/insert/add_preallocated_index_tree_operations/mod.rs
• packages/rs-drive/src/drive/document/layout.rs
• packages/rs-drive/src/drive/document/mod.rs
• packages/rs-drive/src/drive/document/primary_key_tree_type.rs
• packages/rs-drive/src/drive/document/ranked_index_tree_type.rs
• packages/rs-drive/src/fees/op.rs
• packages/wasm-sdk/src/document_type_layout.rs
• packages/wasm-sdk/src/lib.rs
• packages/wasm-sdk/tests/unit/document-type-layout.spec.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Drive now builds a recursive layout for a document type from its contract and platform version. The layout records tree and element details, keys, wrappers, indexes, and conditional alternatives. The WASM SDK exposes this layout through documentTypeLayout, with Rust and JavaScript tests covering its structure.

Changes

Document Type Layout

Layer / File(s)	Summary
Shared continuation and wrapper decisions packages/rs-drive/Cargo.toml, packages/rs-drive/src/drive/document/..., packages/rs-drive/src/fees/op.rs	Shared helpers select continuation contribution behavior and zero-contribution wrappers. Index insertion, preallocation, and fee operations use these helpers.
Drive layout model and validation packages/rs-drive/src/drive/document/layout.rs, packages/rs-drive/src/drive/document/mod.rs, book/src/drive/grovedb-structure.md	Drive builds and serializes a recursive document-type layout, including index paths, time-range buckets, wrappers, and alternatives. Tests compare modeled layouts with stored elements. The layout module is available with server or verify.
WASM API and SDK coverage packages/wasm-sdk/src/document_type_layout.rs, packages/wasm-sdk/src/lib.rs, packages/wasm-sdk/tests/unit/document-type-layout.spec.ts, packages/js-evo-sdk/README.md	The WASM SDK exposes documentTypeLayout and its TypeScript result shape. Unit tests cover layout features and missing document types; the SDK README documents the API.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant JavaScriptCaller
  participant WasmDocumentTypeLayout
  participant DriveDocumentTypeLayout
  JavaScriptCaller->>WasmDocumentTypeLayout: contract, document type name, platform version
  WasmDocumentTypeLayout->>DriveDocumentTypeLayout: compute document type layout
  DriveDocumentTypeLayout-->>WasmDocumentTypeLayout: layout model
  WasmDocumentTypeLayout-->>JavaScriptCaller: serialized layout object

Loading

Suggested reviewers: shumkov, pastapastapasta

Merge Risk: ⚪ Minimal · up to dd60f

No actionable issue is established before merge. The verify-only configuration still needs validation when its dependency is available.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to dd60f

The new layout API does not appear to expose stored documents or grant storage access. A separate change can alter which index trees are written for some document values, so its compatibility across versions needs confirmation before treating the change as storage-neutral.

Retained concerns

• Medium · security · inferred: The new width check can skip persistent preallocated index trees that the base insertion path would attempt to create. If an accepted contract permits a wider referenced property, identical document insertion across versions may yield different storage state; no version gate is visible in this changed path.

Security review details

Security Blast Radius

• inferred — The potential state-integrity effect is limited to document inserts using a preallocation binding with a referenced value wider than its referring property. Its reachable contract and deployment scope are not established.

Security Findings and Attack Paths

• inferred — If an accepted binding allows different property widths, a document author can supply a value within the referenced property's allowance but beyond the referring property's maximum. The head path skips that binding; the base path did not perform this skip. Whether this input is accepted and can produce cross-version state divergence remains unverified.

Trust Boundaries and Controls

• observed — The layout API converts caller-provided inputs and looks up the requested type before calculating the result. It does not itself authorize access to a store; no independent host resource limit was established by the inspected path.

Resilience and Maintainability Implications

• observed — The shared continuation helpers are pure predicates, and the inspected writer retains its zero-wrapper and if-not-exists insertion branches with transaction and batch arguments. This counters a separate concern that extracting those predicates changed insertion ordering or authority.

Hardening Proposals

• proposed — Establish whether accepted bindings can have unequal encoded widths, then compare base and head storage outcomes for such an insert under the intended protocol and rollback rules.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 56.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 51 functions across 11 files. (3 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: computing a document type's GroveDB layout for the SDKs.

Full details: Docstring Coverage

Explanation

Docstring coverage is 56.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 51 functions across 11 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

🕓 Queued for automated review — 1st in line, estimated start in ~25 min (commit f3e69c4)
Estimated review time once started: ~55 min (two-phase automated review; median of recent runs).

• Request priority review — click to move this review to the front of the queue.

[QuantumExplorer]

Approved