Repository navigation
docs(sdk): bring the README up to date with the shipped SDK and indexer - #31
Merged
Merged
Conversation
It still said the indexer was being scaffolded, but it is built and running on testnet. Document the 16 public exports, the bigint and claim-link-fragment invariants, the list API routes, and the published release flow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
The README's status line said "the indexer is still being scaffolded." It is built, deployed, and serving testnet data. Anyone reading the repo before contributing gets the wrong picture of what exists, and the public API surface was undocumented outside
packages/sdk/API.md.Changes
@kinlock/sdkv0.3.0 and@kinlock/indexerboth shipped; live indexer URL in the header.createLock/release/refund/decline, each build-simulate-sign-submit), chain reads (getLock,getPayee), links (buildClaimLink/parseClaimLink/buildRequestLink/parseRequestLink),preflight(5 checks, 3 blocking / 2 warning,unknownnever passes as OK),verifyReceipt(tier 1 and 2; tier 3 pending the archive decision), and primitives (toBaseUnits,fromBaseUnits,generateSalt,computeRefHash,USDC_DECIMALS,KinlockError,NotImplementedError,Lock/Payee/Tranche).bigintin code and a decimal string in JSON, nevernumber; the claim reference and salt live only in the URL fragment, andref_hashis SHA-256 over the NFC-trimmed reference bytes then 16 raw salt bytes (ADR-0024).(tx_hash, event_index)idempotency,GapErrorstops rather than skipping, append-onlychain_events, and the routes (/healthreturns 503 when lagging,/locks,/locks/:id,/payees,/events/:txHash/:eventIndex). Explicit that these are list endpoints and money pages read chain.sdk-v*tag produces a GitHub Release with the.tgzattached (ADR-0026), not npm.Hard rules / invariants touched
2 (chain is truth), 5 (no personal data; the claim-link fragment never reaches a server), and the amount-typing rule from the SDK section of
ARCHITECTURE.md. Documenting existing behavior; no code changed.Tests
Docs only. Every export name and signature checked against
packages/sdk/src/index.ts; route list against the indexer's registered handlers; thepreflightcheck/block split against the preflight implementation; the version against the release tag. Nothing claimed from the v0.3 docs.Docs / ADR
README.mdonly;packages/sdk/API.mdremains the per-export reference and is linked. No ADR needed.Roadmap
No row changes. Changelog entry added (2026-10-08,
docs/readme-refresh, sdk).Assumptions and open questions
origin/main, so it does not carry the unmerged doc-sync commit. Rebase if that lands first.