SATP Demo Progress

Milestones

• 1. Shell, style tokens, navigation, site introduction
• 2. Shared primitives with scratch harness
• 3. Protocol-map transcription, Chapter 1, and reference table
• 4. Chapter 2 static lane diagram, animation, and controls
• 5. Chapter 2 ledger states, captions, and scroll linkage
• 6. Chapter 3 diagram, message cards, and field annotations
• 7. Hash chain, signatures, rejection path, accessibility, polish, and docs
• 8. Review pass: scroll and framing fixes, hoverable step names, user/operator hand-off in Stage 0, draft version note, extra references
• 9. Chapter on the API1 (client application to gateway) interaction: the business API surface, how an application opens a session and activates a transfer, what it polls or receives back, and where that sits relative to Stage 0
• 10. Chapter on the adapter (bridge) layer: how a gateway talks to a specific ledger, leaf/bridge plugins, and a worked example taken from the cacti-demos subrepo
• 11. Chapter tying it all together: the Cacti CBDC demo end to end, two applications, two gateways, two ledgers, one transfer, plus the recovery/rollback story

After each milestone, record changed files, checks performed, browser pages exercised, console errors, and unresolved questions. Stop after the requested milestone.

Scaffold

• Status: complete
• Files: standalone page shell, style tokens, JavaScript entry points, primitive factory contracts, data placeholders, spec-derived seed values, icon sprite, and harness
• Open question: exact Cacti v02 message objects must be transcribed from upstream source before populating messages or field annotations

Milestone 1 — shell, style tokens, navigation, site introduction

• Status: complete
• Changed files:
  • satp-demo/index.html — page metadata and social tags, navbar/footer mirrors of _includes/navbar.html and _includes/footer.html, chapter navigation, theme toggle markup, full site introduction (what the page is, the transfer path it follows, how to read it, illustrative-data and accessibility expectations), and concept-first chapter headings with placeholder mount points
  • satp-demo/assets/css/satp-tutorial.css — complete “Light Organic Editorial” token set in one :root block (surfaces, ink, semantic stage/role/network accents, radius, shadow, spacing ramp, type scale, motion), “Night Paper” dark variant under both prefers-color-scheme: dark and [data-theme="dark"], paper texture washes, header and chapter-nav styling, introduction layout, footer, focus rings, responsive rules down to 380px, and prefers-reduced-motion handling
  • satp-demo/assets/js/satp-tutorial.js — theme cycling (system → light → night) with localStorage persistence and updated ARIA labels, IntersectionObserver chapter-nav highlighting, and chapter-controller mounting when controllers exist
  • satp-demo/plans/progress.md — this record
• Verification:
  • HTML, CSS and JavaScript syntax checked with locally available tools
  • Page opened over file:// and served locally; no console errors, no network requests to third parties
  • JavaScript disabled: introduction, chapter headings, navigation, banner and footer all render and remain readable; theme toggle is hidden because it cannot function
  • Checked at 380px, 768px and 1440px widths; light, dark and forced-theme rendering
• Open questions:
  • none for this milestone

Notes

• No fonts are loaded from a CDN; Fraunces / IBM Plex Sans are requested by name and fall back to system serif and sans faces.
• The navbar and footer here are static copies. When _includes/navbar.html or _includes/footer.html change, update satp-demo/index.html to match.

Milestone 8 — review pass

• Status: complete
• Changed files:
  • assets/css/satp-tutorial.css — Chapter 2 narration is now a framed, independently scrollable panel matched to the diagram box height; sticky columns are bounded so they cannot be cut off; hover/focus tooltips for step names; Chapter 3 hash-chain block spans both columns; .stage-note and prologue arrow styling
  • assets/js/chapter-02-stages.js — Alice (user) lane and the two pre-protocol hand-offs (user to application, application to gateway); stage badge no longer carries the Cacti-extension caveat, which moved to a note under it; narration height sync and scroll observation rooted in the narration panel
  • assets/js/primitives/lane-diagram.js — optional prologue hops drawn left of the first protocol column, with the column grid shifted to make room
  • assets/js/chapter-01-table.js — step names are hoverable and focusable with a tooltip describing the step; caption links SATP_PROTOCOL_MAP to types/satp-protocol.ts upstream
  • assets/js/chapter-03-messages.js — illustrative-data notice removed
  • index.html / build-index.py — states that the modelled protocol is draft version 3 as implemented by SATP Hermes, describes the operator hand-off in Chapter 2, and adds the SATP Hermes talk and Cacti workshop recordings to the references
• Verification: rebuilt index.html, opened over file://, no console errors, no third-party requests beyond the Google Fonts stylesheet; checked scrolling of both chapters at 1280x900 and at 420px

Milestone 9 — chapter reorder and second review pass

• Status: complete
• Changed files:
  • index.html — chapters reordered: Chapter 1 (why it is hard) now ends with the hash-chain explainer “What ties the four messages together”; Chapter 2 is the Stage 1 message explorer; Chapter 3 is the whole-conversation flow diagram plus the 36-step reference table; new scaffold chapters 4 (API1) and 5 (adapter layer); chapter nav updated to five entries; Stage 0 is described as being specified in draft-avrilionis-satp-setup-stage instead of “not part of the core draft”
  • assets/js/chapter-01-table.js — wire message names are hoverable/focusable with a placeholder message-format tooltip (common envelope + payload); caption updated
  • assets/js/chapter-02-stages.js — shorter actor role captions so the gateway boxes no longer overflow their rounded rectangles; stage note links the IETF setup-stage draft
  • assets/js/chapter-03-messages.js — hash-chain block can be mounted into a separate container (#hash-chain-anatomy in Chapter 1)
  • assets/js/satp-tutorial.js — passes the Chapter 1 hash-chain container
  • assets/css/satp-tutorial.css — “The transfer we are following” column is no longer sticky (it used to run past the viewport and cover the prose below); styles for in-chapter section headings and the message-format tooltip
  • assets/data/satp-stages.json — Stage 0 note points at the IETF setup-stage draft
• Verification: opened the built page over file:// at 1280x1400, no console errors; checked the reordered chapters, the table hover tooltips, the actor boxes and the previously overlapping scenario card

Milestone 10 — Chapter 4: API1 visual explainer

• Status: complete
• Changes: replaced the API1 scaffold with an intent-transformation explainer. An editable transfer form drives four synchronized views: the exact TransactRequest shape, enriched private SessionData, Stage 0 setup messages and the signed Stage 1 proposal. Empty or invalid required values stop the transformation before SATP, generated/default values are distinguished from application input, and every view links to its controlling Cacti source. The no-JavaScript fallback describes the same path and notes that the current endpoint awaits manager.transfer(session) before returning sessionID and status.
• Files: index.html, assets/js/chapter-04-api1.js, assets/js/satp-tutorial.js, assets/css/satp-tutorial.css
• Verification: JavaScript syntax and editor diagnostics clean; git diff --check clean; browser checks at 1280×900 and 420×900 confirmed four selectable views, validation blocking, Stage 0 rendering and no horizontal overflow.

Milestone 11 — Chapter 5: adapter layer explanation

• Status: complete
• Changes: replaced ledger-adapter scaffold with source-grounded API3 hook walkthrough for Stage 1 TransferProposalRequest; reused lane and packet primitives with explicit actor endpoints; added four configured before/after bindings, 13-step execution table, raw payload inspector, event log and human-operated hook clients connected to both gateways. Gateway 1 reviews 100 Digital Pound from Alice on Besu to Bob on Fabric and returns outbound HTTP success/error; Gateway 2 acknowledges notification, then posts approve/reject decision before proposal validation. Success returns INIT_RECEIPT; sender HTTP failure and receiver rejection stop before Stage 2. No timeout UI or timer-driven workflow is present.
• Source note: supplied Cacti demo YAML configures Stage 0 newSessionRequest; chapter clearly labels its equivalent Stage 1 configuration as an adaptation. Runtime sequence follows current stage1-handler.ts: sender transferProposalRequest before/after, receiver checkTransferProposalRequestMessage before, then transferProposalResponse after. There is no receiver validation after-hook in current handler.
• Files: index.html, assets/js/chapter-05-adapters.js, assets/js/primitives/lane-diagram.js, assets/js/satp-tutorial.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: JavaScript syntax, diagnostics, Jekyll build and git diff --check clean; browser checks covered visible packet motion, full five-action success path, sender HTTP error, receiver rejection, replay, reduced motion, 13 rows, four actors and operator transfer summary. Chapter 2 retained 36 protocol rows and original gateway geometry. At 390px adapter canvas scrolls inside its viewport; observed page overflow belongs to pre-existing Chapter 1 table.

Milestone 12 — Stage 3 hand-off, Chapter 6 scaffold, blockchain-style hash chain

• Status: complete
• Changes: Stage 3 now shows the receiving gateway notifying Bob’s application after ACK_COMMIT_FINAL (drawn as an “after SATP” hand-off to the right of the flow, mirroring the Stage 0 prologue); new Chapter 6 scaffold for the end-to-end CBDC integration with its todo list; the “What ties the four messages together” illustration now reads as a chain of blocks with a block index, a monotonically increasing sequence_number under common.hash_previous_message, and drawn connectors between consecutive blocks.
• Files: assets/js/primitives/lane-diagram.js, assets/js/chapter-02-stages.js, assets/js/chapter-03-messages.js, assets/css/satp-tutorial.css, assets/data/satp-stages.json, index.html, plans/progress.md
• Open question: Chapter 6 needs the exact CBDC demo package paths and run commands from the Cacti repository before the prose can stop being a scaffold.

Follow-up — application hand-offs in the message flow

• Status: complete
• Changes: the right-hand flow panel is titled “Message flow” and now starts with the user’s UI choice and the application’s API1 POST /transfer request, including placeholder request fields; protocol numbering continues after those entries and ends with Gateway 2 notifying Bob’s application, including placeholder result fields. The diagram labels the first two arrows as Stage 0/API1 and changes the caption to “earlier” during later stages. In the reference table, the Stage 1 label now uses the same colour as “Message on the wire”.
• Files: assets/js/primitives/step-list.js, assets/js/primitives/lane-diagram.js, assets/js/chapter-02-stages.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: JavaScript syntax checked with node --check; reloaded the served page at 1280×900 and 420×900; confirmed 39 numbered flow entries, the Stage 3 “Stage 0 · earlier” caption, matching Stage 1/wire-message colours, stacked mobile columns, no horizontal overflow, no editor diagnostics, and no browser console errors.

Follow-up — Stage 1 message-detail framing

• Status: complete
• Changes: the selected message details to the right of “The transfer we are following” now occupy a keyboard-focusable scroll region whose desktop height tracks the scenario and message picker on the left. On single-column layouts the details return to normal document flow.
• Files: assets/js/chapter-03-messages.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: at 1280×900 the left column measured 445.9px and the right scroll region 446px, with 1840px of scrollable content; exercised a 400px scroll offset. At 420×900 the detail panel returned to normal flow with no horizontal page overflow. node --check, editor diagnostics and the browser console were clean.

Follow-up — application hand-off animations

• Status: complete
• Changes: all 39 message-flow rows now share one selectable playback index. Reset and autoplay begin with the user’s UI request, continue through the API1 /transfer call, then enter the gateway protocol at newSessionRequest. The two Stage 0 hand-offs and the final Gateway 2-to-Bob’s-app result now expose packet geometry, active-arrow state and click targets in the lane diagram.
• Files: assets/js/primitives/lane-diagram.js, assets/js/chapter-02-stages.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: a Playwright regression check confirmed reset at step 1 with rows 1 and 2 interactive; reduced-motion geometry checks produced four distinct packet paths for steps 1, 2, 3 and 39; 2× autoplay reached step 3 in order; reset remained stable after 1.2 seconds. JavaScript syntax, editor diagnostics, browser console and horizontal overflow checks were clean.

Follow-up — source provenance in the step reference

• Status: complete
• Changes: “Message defined in” links each wire message and its corresponding validation step to the exact declaration in service/stage_0.proto through service/stage_3.proto; the four ledger-only rows say “No wire message”. A separate “Implemented in” column links all 36 steps to their actual client/server stage-service methods at pinned Cacti commit 9195eccc0a1b81112107e3e5be325c85efb95b72. Three boxes above the table introduce the Stage 1–3 CommonSatp envelope, shared Error enum and persisted SessionData. Source chips support commit refs and show their exact line anchors.
• Files: assets/js/util.js, assets/js/chapter-01-table.js, assets/js/primitives/source-chip.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: fetched the six authoritative v02 proto files and checked all declaration line numbers, then fetched all eight client/server stage-service files at the pinned commit and checked every method declaration. The supplied newSessionResponse example points to newSessionErrorResponse at line 537; the table points to the actual newSessionResponse declaration at line 428. node --check passed for all changed JavaScript files. At 1280px the page rendered 36 pinned, line-anchored implementation links with no page overflow. At 420px the schema boxes collapsed to one column, the table scrolled inside its frame, and the browser console and editor diagnostics were clean.
• Open questions: none.

Follow-up — Core 15 message links and formats

• Status: complete
• Changes: wire-message labels and their step descriptions now link to the corresponding draft-ietf-satp-core-15 section. Stage 1 maps to Sections 8.3, 8.4, 8.6 and 8.7; Stage 2 to 9.1 and 9.2; Stage 3 to 10.1 through 10.5. Links use the exact named anchors in the archived Core 15 HTML. Cacti’s Stage 0 messages are not linked because their concrete definitions are outside Core 15; the Cacti-only transfer-complete response shares Section 10.5 with its request. Message-format tooltips contain only the exact proto definition link and symbolic/numeric message ID. Each wire-message cell visibly shows its linked Core §… destination; Stage 0 cells say “Not defined in Core 15”. The table’s “Kind” filter and column are labelled “Message type”, and a composable “Acting gateway” filter selects client or server steps. Draft metadata and the embedded file:// fallback use Core 15.
• Files: assets/js/chapter-01-table.js, assets/css/satp-tutorial.css, assets/data/satp-stages.json, assets/data/stage1-messages.json, index.html, prompt.md, plans/progress.md
• Verification: JavaScript and JSON syntax checks passed. At 1280px the rendered table had 24 visible Core-linked messages and 24 linked descriptions, all using named archive anchors, with no links on Stage 0 rows. Acting-gateway filtering produced 18 client rows; combining Stage 3, wire message and client produced the expected three rows. There were no console errors. The earlier direct file:// check at 420px kept table overflow inside its frame and had no console errors.
• Open questions: none.

Follow-up — explicit Core sections inside message hovers

• Status: complete
• Changes: every wire-message hover now spells out SATP Core section N before the proto definition and message ID. The Core reference was removed from native title attributes and from the separate always-visible badge, so the custom hover/focus panel is the single explanatory surface. Cacti’s four Stage 0 message types explicitly point to the Core 15 Section 7 overview and note that concrete setup messages are outside that draft’s scope; Core 15 has no Section 7.2.
• Files: assets/js/chapter-01-table.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: at 1280px all 32 message hover triggers had no title, all 32 hover panels contained an explicit Core section, all Stage 0 panels included the scope caveat, and the page had no horizontal overflow or console errors. At 420px keyboard focus opened the same custom panel, table overflow stayed inside its frame, and the console remained clean.
• Open questions: none.

Follow-up — wrapper-contract definitions for ledger writes

• Status: complete
• Changes: the four ledger-write rows now use “Message defined in” to link directly to their SATPWrapperContract.sol entrypoints: lock at line 203, mint at line 296, burn at line 341 and assign at line 389. Smart-contract payload examples now match the Solidity ABI: tokenId, assetAttribute, and, for assign, an EVM receiver_account. Incorrect lockAsset / mintAsset / burnAsset / assignAsset contract names, generic amount, and distinguished-name receiver were removed. Notes explain onlyOwner, boolean success, fungible amount semantics and wrapper balances.
• Files: assets/js/chapter-01-table.js, assets/data/satp-stages.json, index.html, plans/progress.md
• Verification: fetched current wrapper Solidity and bridge leaf implementations; checked exact ABI declaration lines and bridge argument order. JavaScript and JSON syntax and editor diagnostics passed. At 1280px all four ledger rows rendered exact contract links and corrected payloads with no console errors or page overflow. At 420px the direct file:// fallback retained all four definitions, kept overflow inside the table and had no console errors.
• Open questions: destination example still narrates Fabric elsewhere, while this table now explicitly presents the Solidity wrapper ABI requested here; Fabric chaincode uses the same operation names and argument order but accepts receiver as a string.

Follow-up — progressive hash-chain creation

• Status: complete
• Changes: only block 0 begins fully opaque; blocks 1–3 begin muted. Hovering or focusing the newest created block animates its border and brightens the connector to the next block for one second, then leaves that next block fully opaque. Repeating the interaction creates blocks 2 and 3 in order. Blocks are keyboard focusable and reduced-motion mode suppresses edge and connector animation while preserving progression.
• Files: assets/js/chapter-03-messages.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: JavaScript syntax and editor diagnostics passed.
• Open questions: none.

Follow-up — exact function links in message flow

• Status: complete
• Changes: every source chip in the Stage 0–3 animated message-flow narration and Stage 1 four-message explorer now links to the exact proto or stage-service function declaration, pinned to Cacti commit 9195eccc0a1b81112107e3e5be325c85efb95b72. StepList maps each flow function tag to its line; the message explorer maps each source role to its proto, sender, or receiver function line. Labels expose the line number.
• Files: assets/js/primitives/step-list.js, assets/js/primitives/message-card.js, assets/js/chapter-03-messages.js, plans/progress.md
• Verification: JavaScript syntax and editor diagnostics passed.
• Open questions: none.

Follow-up — whole-conversation animation recheck

• Status: complete
• Changes: the settlement timeline now starts with a visible custody: client marker before playback. Each source or destination ledger write shows its own compact 3-second clock on that chain after the packet lands; the countdown clears before playback advances. The clock hand uses the chain colour and stops rotating when reduced motion is requested.
• Files: assets/js/chapter-02-stages.js, assets/js/primitives/lane-diagram.js, assets/js/primitives/ledger-band.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: JavaScript syntax, editor diagnostics, diff whitespace, initial custody DOM, ledger finality lifecycle, served assets, and reduced-motion styling passed.
• Open questions: none.

Follow-up — session record and settlement states

• Status: complete
• Changes: the SATP error schema card now uses the error red and the SessionData gateway-record card uses neutral gray. SessionData includes a keyboard-accessible button that opens one representative full 69-field v02 session record in a modal. CommonSatp has a separate modal example covering all 16 envelope fields, including its full payload profile, and Error has an out-of-sequence failure example. All three follow the Stage 1 message explorer’s structure: type line, descriptive heading, plain summary, nested field rows, and an explanation beside every value. Raw JSON blocks were removed; controls use unique ARIA relationships. During Stage 0, the Besu and Fabric rows now follow session opening and transfer negotiation without implying an on-chain asset change. The Settlement row defaults to “custody of asset”. Each confirmed blockchain transaction appends a persistent datapoint: client custody at lockAsset, separate shared-custody points at mintAsset and burnAsset, and server custody at assignAsset. A neutral-grey pointer marks the latest confirmation. Ledger-write arrows run from the acting gateway to the correct network; Fabric operations mintAsset and assignAsset use destination green.
• Files: assets/js/chapter-01-table.js, assets/js/chapter-02-stages.js, assets/js/primitives/lane-diagram.js, assets/js/primitives/ledger-band.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: node --check passed for all changed JavaScript. Browser checks at 1280×900 and 420×900 confirmed all Stage 0 labels, the four-point custody history, grey current-state pointer, backward-navigation contraction, three ledger rows, source/destination arrow geometry and colors, the modal 69-field session example, the complete 16-field CommonSatp example, the SATP error example, unique control targets, internal modal scrolling, focus restoration, no raw JSON blocks, no horizontal overflow, no console errors, and no editor diagnostics.
• Open questions: none.

Follow-up — ledger finality wait

• Status: complete
• Changes: autoplay now finishes each blockchain transaction animation, shows a clock labelled “Finalizing” with a 3-second countdown, then continues to the next protocol step. Pause, reset and manual navigation cancel the pending wait.
• Files: index.html, assets/js/chapter-02-stages.js, assets/css/satp-tutorial.css, plans/progress.md
• Verification: deterministic browser-clock checks confirmed 3s, 2s, 1s, then advancement after lockAsset, mintAsset, burnAsset and assignAsset; pause held the active ledger step after five simulated seconds. No horizontal overflow.
• Open questions: none.

Follow-up — diagram-owned playback focus

• Status: complete
• Changes: Reset now returns the flow and message queue to their first step, then focuses the diagram viewport. Arrow, Home and End playback shortcuts are scoped to that viewport and no longer intercept keyboard input in the message queue.
• Files: assets/js/chapter-02-stages.js, assets/js/primitives/lane-diagram.js, plans/progress.md
• Verification: node --check passed for both changed JavaScript files; git diff --check passed and VS Code reported no diagnostics in either file.
• Open questions: none.

TBD:

• In the protocol step table, you can consider shading rows corresponding to the various stages in different colors, so the stage shifts are made more apparent.