Skip to content

Repository navigation

Commit f01b4c4

Browse files
cursoragentqlrd
cursoragent
and
qlrd
committed
Add implementation instructions and starter prompt
Co-authored-by: qlrd <qlrd@users.noreply.github.com>
1 parent e733fb3 commit f01b4c4

2 files changed

Lines changed: 185 additions & 0 deletions

File tree

‎INITIAL_PROMPT.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Initial Prompt (copy/paste)
2+
3+
You are implementing a Nostr-only hardware signer firmware fork with one non-negotiable objective:
4+
5+
## Primary Goal
6+
7+
Given an unsigned Nostr event, the device returns a correctly signed Nostr event.
8+
9+
Use `INSTRUCTIONS.md` as binding implementation guidance and execute all required sections.
10+
11+
## Hard constraints
12+
13+
- Firmware scope is Nostr signing only.
14+
- Remove Bitcoin-specific flows and assumptions.
15+
- Keep QR and SD card import/export workflows.
16+
- Keep explicit user approval before signing.
17+
18+
## Required architecture
19+
20+
Build and wire the signer-first modules:
21+
22+
- `src/krux/nostr/event_parser.py`
23+
- `src/krux/nostr/canonicalizer.py`
24+
- `src/krux/nostr/schnorr_backend.py`
25+
- `src/krux/nostr/approval_ui.py`
26+
- `src/krux/nostr/exporter.py`
27+
28+
Responsibilities must remain separated as defined in `INSTRUCTIONS.md`.
29+
30+
## Crypto backend rule
31+
32+
If `embit` is needed for Schnorr signatures, isolate all `embit` imports to `schnorr_backend.py` only. Do not import `embit` elsewhere.
33+
34+
## Protocol requirements
35+
36+
- Implement canonical NIP-01 event serialization and event ID hashing.
37+
- Sign and verify with Schnorr/secp256k1 before export.
38+
- Treat NIP-19 entities as UI boundary formats; convert internally.
39+
- Treat NIP-06 mnemonic derivation as advanced/optional flow.
40+
41+
## Test structure (mandatory)
42+
43+
Use:
44+
45+
- `tests/unit/`
46+
- `tests/functional/`
47+
- `tests/integration/`
48+
- `tests/common/`
49+
50+
Integration tests must use a nostr regtest-like node plus a JSON-RPC client.
51+
52+
## Documentation and tooling tasks (mandatory)
53+
54+
1. Update `CONTRIBUTING.md` for Nostr-only scope, architecture boundaries, and test policy.
55+
2. Create/update `SECURITY.md` with threat model and secret-handling policy.
56+
3. Replace Poetry workflow with uv workflow in docs/scripts/automation references.
57+
58+
## Deliverables
59+
60+
1. Proposed file tree before edits.
61+
2. Implemented code and docs updates.
62+
3. Poetry-to-uv migration map (old command -> new command).
63+
4. Test evidence grouped by unit/functional/integration.
64+
5. Completion checklist proving signer path works end-to-end and no forbidden `embit` coupling exists.
65+
66+
## Reporting rules
67+
68+
- Distinguish verified facts from assumptions.
69+
- Include exact commands executed and outcomes.
70+
- If blocked, provide exact unblock steps, not general advice.

‎INSTRUCTIONS.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# INSTRUCTIONS.md
2+
3+
This document defines the execution contract for an implementation agent working on a Nostr-only firmware fork derived from Krux.
4+
5+
## 1) North-star objective
6+
7+
The most important outcome is:
8+
9+
- given an unsigned Nostr event, the device returns a correctly signed Nostr event.
10+
11+
Everything else is secondary until this works reliably.
12+
13+
## 2) Product boundaries
14+
15+
The firmware scope is Nostr signing only.
16+
17+
- Remove Bitcoin-specific UX and flows (wallet, receive address, PSBT signing).
18+
- Keep user-critical transport and interaction paths:
19+
- QR scan/import and QR export
20+
- SD card import/export
21+
- key onboarding
22+
- event review and explicit sign confirmation
23+
24+
Do not reintroduce Bitcoin abstractions as compatibility layers.
25+
26+
## 3) Mandatory signer-first module layout
27+
28+
Implement and keep responsibilities strict in the following modules:
29+
30+
- `src/krux/nostr/event_parser.py`
31+
- `src/krux/nostr/canonicalizer.py`
32+
- `src/krux/nostr/schnorr_backend.py`
33+
- `src/krux/nostr/approval_ui.py`
34+
- `src/krux/nostr/exporter.py`
35+
36+
Rules:
37+
38+
- parsing/validation only in `event_parser`
39+
- canonical NIP-01 serialization and ID calculation only in `canonicalizer`
40+
- cryptographic sign/verify only in `schnorr_backend`
41+
- user confirmation rendering/logic only in `approval_ui`
42+
- output/transport formatting only in `exporter`
43+
44+
## 4) Crypto dependency policy
45+
46+
If `embit` is required for Schnorr during migration:
47+
48+
- isolate all `embit` usage to `schnorr_backend.py`
49+
- do not import `embit` in UI, parser, exporter, or app orchestration code
50+
- keep adapter surface minimal (`sign_hash`, `verify_hash`, `derive_pubkey`)
51+
52+
Prefer eventual replacement with a narrower backend when feasible.
53+
54+
## 5) Nostr protocol rules (must enforce)
55+
56+
- NIP-01 event ID must be computed from canonical serialized event fields.
57+
- Signature must be Schnorr over secp256k1 for the computed event hash.
58+
- Verify signatures before export; fail closed on mismatch.
59+
- NIP-19 bech32 forms (`nsec`, `npub`, etc.) are UI I/O formats; convert to internal form for protocol operations.
60+
- NIP-06 mnemonic derivation is optional and should be treated as advanced flow, not default onboarding.
61+
62+
## 6) Test taxonomy and placement
63+
64+
Use this exact structure:
65+
66+
- `tests/unit/` for deterministic logic checks
67+
- `tests/functional/` for end-to-end app behavior checks
68+
- `tests/integration/` for external-system tests (nostr regtest-like node + JSON-RPC client)
69+
- `tests/common/` for shared fixtures/helpers
70+
71+
Each test belongs to one tier only.
72+
73+
## 7) Documentation requirements
74+
75+
The implementation must include documentation updates:
76+
77+
- update `CONTRIBUTING.md` with:
78+
- Nostr-only scope and architecture policy
79+
- module ownership boundaries
80+
- dependency and testing policy
81+
- pre-merge verification commands
82+
- create or update `SECURITY.md` with:
83+
- threat model
84+
- secret handling policy
85+
- disclosure policy
86+
- signing safety guarantees and explicit non-goals
87+
88+
## 8) Tooling migration requirement
89+
90+
Replace Poetry-based workflows with uv-based workflows:
91+
92+
- remove Poetry-first instructions from docs and scripts
93+
- add uv setup/install/run/test/lint commands
94+
- update CI or local automation references accordingly
95+
- include old-command to new-command mapping in migration notes
96+
97+
## 9) Execution checklist
98+
99+
Before declaring completion, verify all items:
100+
101+
1. signer path works end-to-end: parse -> canonicalize -> review -> sign -> verify -> export
102+
2. no direct `embit` imports outside `schnorr_backend.py`
103+
3. tests exist in the correct tiered structure
104+
4. `CONTRIBUTING.md` and `SECURITY.md` updated
105+
5. Poetry to uv migration applied and documented
106+
6. no secret leakage in logs, errors, or artifacts
107+
108+
## 10) Reporting format
109+
110+
Final implementation report must include:
111+
112+
- summary of changed files and rationale
113+
- test evidence grouped by unit/functional/integration
114+
- blockers and exact remediation steps (if any)
115+
- explicit "verified" vs "assumed" statements

0 commit comments

Comments
 (0)