Skip to content

docs: keep the typewriter README to what app developers need - #119

Merged
kyscott18 merged 2 commits into
mainfrom
docs/readme-cleanup
Nov 5, 2026
Merged

kyscott18 merged 2 commits into
mainfrom
docs/readme-cleanup

Conversation

@kyscott18

@kyscott18 kyscott18 commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Rewrites the typewriter README so it documents what app developers use, and matches it to the runtime on main (after #131, #147).

Wrong behavior fixed

  • Authorization.expiration is uint40, in the struct and the EIP-712 type string (it said uint256).
  • There is no "enqueued" mutation status, isForceInclusion, queueIndex, or forceIncludedMutations: force-included mutations emit no events and get no rows.
  • The handle has no close; the runtime stops on SIGINT/SIGTERM.
  • Reorgs: a reorg that removes a block with the server's settlements or enqueues stops it (SettlementReorgedError / EnqueueReorgedError). Recovery is feat(typewriter): follow settlements and enqueues through reorgs #132.
  • Reverts: only a late landing is executed again (with a possibly new executionIndex); any other revert stops the server.
  • Restarts: handling of unfinalized mutations is undecided; startup fails with pending scheduler transactions or when the chain is ahead of the database (e.g. a forceExecute while the server was down).
  • Enqueues settle in the batch's transaction, after its mutations.

Missing or stale

  • hardfork config (required off Monad mainnet/testnet, including a self-started Anvil), database timeouts, default batchIntervalMs, batchOrder names and ordering of built-in/unlisted mutations.
  • execute() rejection errors and the expiration margin; all startup contract rules.
  • Examples: library-form mutation, FORCE_INCLUSION_DELAY constructor that calls Typewriter(scheduler), batchOrder with real mutation names, sync accounts reads, repo links (monad-developers/typewriter).
  • "single digit ms" → "within milliseconds".

Internals removed: revm, storage proxies, slot rehydration, keccak preimages, Ponder reorg algorithm, settlement gas formula, scheduler execute ABI.

Root README is again an exact copy of packages/typewriter/README.md (it still documented safe, confirmations, onFatalError, numeric id).

🤖 Generated with Claude Code

…ch it to the runtime

Drops runtime internals (revm, storage proxies, slot rehydration, gas
formula, scheduler ABI) and fixes what no longer matches the code:
uint40 authorization expiration, no "enqueued" event or force-inclusion
fields, no `close` on the handle, reorgs and unknown reverts stop the
server, restart reconciliation is undecided, enqueues settle in the
batch's transaction, `hardfork` and database timeouts, `execute()`
rejections, batchOrder names, example links, and the library-form
mutation and FORCE_INCLUSION_DELAY examples. The root README is again a
copy of the package README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyscott18
kyscott18 force-pushed the docs/readme-cleanup branch from ca30528 to 7a2da08 Compare November 5, 2026 21:30
Adds state, execute, and signing examples to Concepts, shortens accounts,
local development, and sequencing, and renames submission to "Submitting
transactions". Config details move to the createTypewriter() reference,
and the expiration rules move next to authorization verification.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyscott18
kyscott18 merged commit fe2f2ea into main Nov 5, 2026
7 checks passed
@kyscott18
kyscott18 deleted the docs/readme-cleanup branch November 5, 2026 22:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant