0xMiden / 0xMiden/note-transport-service

README and intro docs still describe fetch_notes pagination as timestamp-based

Open Beginner friendly
#155 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
3
Forks
10
Avg merge
2h 23m
Merged PRs (30d)
4

Description

### Problem

Two documentation entries still describe `fetch_notes` pagination as timestamp-based, but the current implementation uses the server-assigned monotonic `seq` cursor.

File evidence:
- `docs/src/index.md` says the node labels notes with an increasing cursor that is "currently a timestamp".
- `crates/node/README.md` says `fetch_notes()` uses pagination based on a timestamp.

The current implementation and external docs describe `seq`-based pagination instead:
- `docs/external/src/design.md` documents `FetchNotes` as `seq > cursor` ordered by `seq`.
- `crates/node/src/database/sqlite/mod.rs` filters by the SQLite `seq` column and only treats very large timestamp-like cursors as legacy values.

### Why this matters

Clients should persist and resend the cursor returned by the server. Timestamp-based wording is stale after the `seq` cursor migration and can lead implementers to infer the wrong cursor semantics.

### Suggested fix

Update the README and intro docs to describe `fetch_notes` pagination as based on the server-assigned `seq` cursor, and mention the legacy timestamp reset only where relevant.

Contributor guide

Open the contributing guide

Research direction

The issue points to two files: `docs/src/index.md` and `crates/node/README.md`. Read the current `seq`-based pagination description in `docs/external/src/design.md` and the implementation in `crates/node/src/database/sqlite/mod.rs`. Update the two documentation files to reflect the correct cursor semantics, mentioning legacy timestamp handling only where appropriate. Verify the changes by checking the updated documentation locally.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.