Skip to content

PLAN.md

Latest commit

 

History

History
506 lines (392 loc) · 20.3 KB

PLAN.md

File metadata and controls

506 lines (392 loc) · 20.3 KB
Raw

OpenSilver — Implementation Framework (v2)

The OpenZeppelin of Kaspa

A battle-tested library of standard covenant patterns for SilverScript

For OpenClaw / davoidd execution

CONTEXT FOR THE AGENT

You are building OpenSilver -- a library of audited, battle-tested SilverScript covenant patterns plus the developer tooling that makes them composable. This is the equivalent of OpenZeppelin Contracts for the Kaspa ecosystem.

Why this exists (validated by deep research): Toccata ships SilverScript as Kaspa's first real high-level smart contract language. There is no covenant pattern library. Michael Sutton himself stated publicly: "the compiler/scheme connection is still wip... For now, Silverscript's covenants/sdk folder is the best reference for how these pieces should meet." Kaspa Core has explicitly flagged "composability standards adopted across builders" and "dev tooling" as gating items for the broader programmability stack.

Governing philosophy: Security-by-Construction Direct quote from Sutton: "Approachability is not just improved syntax. It means making it easy to write covenants that correctly validate state transitions and making it difficult to accidentally deploy insecure schemes." OpenSilver is the implementation of this principle. Every pattern in the library makes the secure path the default path.

Strategic positioning:

  • This is infrastructure, not a product.
  • MIT licensed, open source from day one.
  • COMPLEMENTS existing community tools (SilverScript Studio IDE, KaspaCom wallet, kaspacom-defi-mcp) rather than competes with them.
  • The goal is to be cited in every serious Kaspa project's package.json and to power the templates in every covenant IDE and wallet.

Reference comparisons:

  • OpenZeppelin Contracts (Solidity / Ethereum)
  • Aiken Stdlib (Cardano)
  • CashScript Standard Library (the closest direct comparison since SilverScript is "CashScript-inspired")

EXISTING ECOSYSTEM (DO NOT REINVENT)

Before any code, understand the existing landscape:

Project Role Relationship to OpenSilver
kaspanet/silverscript Compiler + language by Ori Newman, Manyfest, IzioDev Upstream dependency. OpenSilver compiles to this.
Silverscript covenants/sdk folder Current "best reference" per Sutton Read this first. Patterns extend from here.
Kaspero Labs SilverScript Studio IDE (Remix-style) Target integration. Patterns appear in IDE pickers.
KaspaCom Wallet covenant templates End-user wallet UX Target integration. Patterns deployable from wallet.
KaspaCom kaspacom-defi-mcp DeFi-specific MCP Federate or coordinate. OpenSilver MCP is broader scope.
Hans Moog vProgs PRs Long-term vProgs node framework Forward-compatibility target. Patterns must not block vProgs migration.
Saefstroem Groth16 verifier PR ZK opcodes on Rusty Kaspa Foundation for ZK-aware patterns in OpenSilver.

Working rule: coordinate with these projects early and continuously, but do not block implementation on acknowledgements. Operating in good faith within the Kaspa community is non-negotiable, and outreach should run in parallel with delivery.

HARD CONSTRAINTS (NON-NEGOTIABLE)

  • All covenant code is SilverScript (.sil files), targeting TN12 first, mainnet after Toccata activation
  • All TypeScript glue / SDK code follows the existing KasBonds patterns
  • Raw SQL via (db as any).$client.execute() for any web tooling
  • Every pattern in the library ships with: source, tests, gas/cost benchmarks, audit notes, usage examples
  • Every pattern uses KIP-20 Covenant IDs for stateful contracts (not recursive lineage proofs)
  • No em dashes in code, comments, docs, or copy
  • MIT license, public from first commit
  • Semantic versioning, backward compatibility commitments
  • Every pattern includes a "WHEN NOT TO USE THIS" section in its docs
  • All patterns honor Sutton's "security-by-construction" principle

ARCHITECTURE OVERVIEW

+--------------------------------+
|  Developers (humans + agents)  |
+--------------------------------+
              |
              v
+--------------------------------+
|  Integration Surfaces          |
|  - opensilver CLI              |
|  - OpenSilver MCP Server       |
|  - SilverScript Studio integration |
|  - KaspaCom Wallet integration |
|  - Web Wizard UI               |
+--------------------------------+
              |
              v
+--------------------------------+
|  OpenSilver Pattern Library    |
|  (.sil files + TypeScript glue)|
|  - Access Control              |
|  - Vaults                      |
|  - Escrows                     |
|  - Token Standards (KRC-20)    |
|  - Streaming Payments          |
|  - Recovery Patterns           |
|  - Atomic Swap Patterns        |
|  - Subscription / Vesting      |
|  - Oracle / Randomness         |
|  - Governance Patterns         |
|  - ZK-aware Patterns (Groth16) |
|  - Freelance / Payroll         |
+--------------------------------+
              |
              v
+--------------------------------+
|  SilverScript Compiler         |
|  (upstream from kaspanet/silverscript)|
|  + covenants/sdk folder        |
+--------------------------------+
              |
              v
+--------------------------------+
|  Kaspa L1 (Toccata + KIP-20)   |
+--------------------------------+

PHASE 0 — ECOSYSTEM COORDINATION (NEW)

Start coordination immediately, but run it in parallel with reconnaissance and scaffolding so the project does not stall waiting on outside responses.

Task 0.1 — Read everything

  • Read the entire kaspanet/silverscript repo end to end
  • Pay special attention to the covenants/sdk folder Sutton flagged as current best reference
  • Read KIP-17, KIP-20, KIP-16, KIP-21 in full
  • Read Sutton's "Kaspa Covenants++ Toccata Hard-Fork Outlook" Medium post
  • Read Kaspero Labs' SilverScript Studio docs
  • Inspect KaspaCom's covenant wallet code on GitHub
  • Read the kaspacom-defi-mcp source code

Task 0.2 — Reach out Send brief, technical, no-fluff messages to:

  • Michael Sutton (@michaelsuttonil) -- Share the OpenSilver thesis. Ask for feedback on whether it duplicates planned core work or fills a gap. Reference his security-by-construction post directly.
  • Ori Newman (@OriNewman) -- Author of SilverScript. Coordinate to ensure OpenSilver evolves with the language.
  • Manyfest (@manyfest_) -- SilverScript contributor. Share patterns being planned.
  • IzioDev -- SilverScript contributor.
  • Kaspero Labs team -- Discuss whether OpenSilver patterns can appear in SilverScript Studio as a default library.
  • KaspaCom team -- Discuss whether OpenSilver patterns can power the wallet's template selector.

Goal of outreach: not permission, but coordination. Find out what's already planned, what conflicts, what overlaps, what gaps exist.

Task 0.3 — Output ECOSYSTEM_COORDINATION.md Document:

  • What's already covered in covenants/sdk
  • Specific feedback received from each contact
  • Confirmed gaps OpenSilver fills
  • Confirmed overlaps and how to handle them
  • Letters of support or explicit "no objection" responses

Output of Phase 0: Documented coordination state. Outreach remains strongly recommended, but lack of acknowledgement is not a blocker for Phase 1 or Phase 2.

PHASE 1 — RECONNAISSANCE

Task 1.1 — Pull and study upstream SilverScript

  • Clone https://github.com/kaspanet/silverscript
  • Read TUTORIAL.md, DECL.md, KCC20 book
  • Run every example in silverscript-lang/tests/examples/
  • Specifically deep-dive covenants/sdk folder (per Sutton's recommendation)
  • Compile each example to native Kaspa Script and inspect output
  • Document each language primitive, opcode, and limitation

Task 1.2 — KIP deep-dive

  • KIP-17: extended script opcodes
  • KIP-20: Covenant IDs (critical -- the foundation for all stateful patterns)
  • KIP-16: ZK opcodes with verifier precompile subsystem
  • KIP-21: sequencing commitments
  • Output: KIP_REFERENCE.md

Task 1.3 — Audit existing covenant work

  • Review KasBonds contracts/ directory
  • Identify which patterns can be promoted to OpenSilver
  • Note what was learned and what should be improved

Task 1.4 — Survey pattern catalogs from neighboring ecosystems

  • OpenZeppelin Contracts (Solidity)
  • Aiken Stdlib (Cardano UTXO model)
  • CashScript Standard Library (most direct comparison since SilverScript is CashScript-inspired)
  • Map every relevant pattern to a SilverScript equivalent
  • Output: PATTERN_MAPPING.md

Output of Phase 1: Three reference docs (KIP_REFERENCE.md, PATTERN_MAPPING.md, language deep-dive). Use these to guide Phase 2 scaffolding and Phase 3 implementation.

PHASE 2 — REPO SCAFFOLD

Task 2.1 — Initialize

  • Create opensilver/ monorepo
  • Top-level structure: 
    opensilver/
├── contracts/         # .sil pattern source
├── sdk/               # TypeScript bindings + tooling
├── cli/               # opensilver CLI
├── mcp/               # MCP server for AI agents
├── wizard/            # web-based wizard
├── integrations/      # SilverScript Studio + KaspaCom Wallet adapters
├── docs/              # pattern docs + tutorials
├── examples/          # working integrations using each pattern
├── tests/             # cross-pattern integration tests
└── benchmarks/        # gas/size benchmarks per pattern

Task 2.2 — Tooling

  • TypeScript with strict mode
  • Vitest for testing
  • Vendor the SilverScript compiler if needed for self-contained dev
  • Set up CI to compile every .sil and run every test on every commit

Task 2.3 — Documentation framework

  • Use Docusaurus or similar
  • Every pattern documented with: description, parameters, security considerations, KIP-20 Covenant ID handling, gas/size, example usage, audit status

Output of Phase 2: Buildable monorepo, CI green on empty patterns, docs site scaffolded.

PHASE 3 — CORE PATTERN LIBRARY (V1)

Build twelve core patterns. Each must include: source, tests, docs, benchmarks, example integration. Every stateful pattern uses KIP-20 Covenant IDs.

Pattern 3.1 — Ownable

  • Single-owner pattern, owner can transfer ownership
  • Foundation for all access-controlled patterns

Pattern 3.2 — MultiSig

  • N-of-M signature validation
  • Configurable threshold
  • Public key rotation

Pattern 3.3 — TimeLock

  • UTXO locked until timestamp / block height
  • Two flavors: hard timelock (no early exit) and soft timelock (owner can cancel)

Pattern 3.4 — Vault

  • Combines Ownable + TimeLock + MultiSig
  • Reference enterprise treasury pattern
  • Recovery path documented

Pattern 3.5 — Escrow (bilateral)

  • Two-party escrow with arbiter
  • Buyer locks funds, seller delivers, arbiter releases
  • Auto-refund on timeout

Pattern 3.6 — Escrow (milestone)

  • Multi-stage escrow with N milestones
  • Each milestone releases on verifier signature
  • Pulls from KasBonds learnings
  • Demonstrates KIP-20 Covenant ID lineage across milestones

Pattern 3.7 — Streaming Payment

  • KAS streams to recipient at fixed rate
  • Recipient withdraws anytime
  • Sender cancels, recovers unstreamed remainder

Pattern 3.8 — Vesting

  • KAS unlocks on schedule
  • Cliff + linear curves
  • Compatible with KRC-20

Pattern 3.9 — Dead Man's Switch

  • KAS released to fallback if owner doesn't ping by deadline
  • Inheritance pattern

Pattern 3.10 — Social Recovery

  • Owner replaceable by quorum of designated guardians
  • Time-delayed activation prevents hijack
  • Guardians rotatable

Pattern 3.11 — Atomic Swap (HTLC)

  • Cross-chain or cross-UTXO atomic exchange
  • Hash-locked timeout
  • KAS-to-KAS and KAS-to-other-asset variants

Pattern 3.12 — Freelance / Payroll Contract

  • The Kaspero Labs demo use-case, but as a battle-tested library entry
  • Configurable: client, worker, arbiter
  • Four spend paths: standard release, arbiter refund, arbiter payout, timeout reclaim
  • High-impact because community has already shown demand

For each pattern:

  • contracts/<name>/Pattern.sil
  • contracts/<name>/Pattern.test.sil
  • sdk/<name>/index.ts
  • docs/patterns/<name>.md
  • examples/<name>/
  • benchmarks/<name>.json

Output of Phase 3: 12 patterns, fully documented, all tests green on TN12.

PHASE 4 — KRC-20 TOKEN STANDARD LIBRARY

KRC-20 ships at Toccata as a base-layer feature. Reference implementations needed.

Pattern 4.1 — KRC-20 Reference Implementation

Pattern 4.2 — KRC-20 Ownable

Pattern 4.3 — KRC-20 Pausable

Pattern 4.4 — KRC-20 Capped

Pattern 4.5 — KRC-20 Vesting

Pattern 4.6 — KRC-20 Snapshot (for governance voting)

Output of Phase 4: 6 token patterns. Every Kaspa token project has a battle-tested starting point.

PHASE 5 — ZK-AWARE PATTERNS (NEW)

With Saefstroem's Groth16 verifier merged into Rusty Kaspa and ZK opcodes shipping in Toccata, the library must include ZK-aware patterns. This positions OpenSilver ahead of the curve.

Pattern 5.1 — Verified Computation

  • Covenant releases funds only on submission of valid Groth16 proof
  • Reference implementation for stake-secured re-execution (ERC-8004 Validation Registry pattern)

Pattern 5.2 — Private Asset Transfer

  • Confidential transfer with ZK-proof of correctness
  • Bridge to vProgs sovereignty model

Pattern 5.3 — ZK-Verified Oracle

  • Oracle data fed into covenant via ZK proof of correct computation
  • Connects with QUEX or other TEE-secured oracle work

Pattern 5.4 — Proof-Stitched Multi-Pattern

  • Demonstrates composition: multiple covenant patterns sharing a single ZK proof
  • Forward path to vProgs composability model

Output of Phase 5: 4 ZK-aware patterns. OpenSilver is the only library shipping with these at launch.

PHASE 6 — DEVELOPER CLI

opensilver new <pattern>           # scaffold a project using a pattern
opensilver list                    # list all available patterns
opensilver doc <pattern>           # open pattern documentation
opensilver compile <file.sil>      # compile to Kaspa Script
opensilver test                    # run pattern tests
opensilver benchmark <file.sil>    # cost/size analysis
opensilver verify <utxo>           # verify on-chain covenant matches a pattern
opensilver migrate <utxo>          # check forward compatibility with vProgs

Publish @opensilver/cli and @opensilver/patterns to npm. Make installation a one-liner.

Output of Phase 6: CLI live on npm.

PHASE 7 — MCP SERVER (AI-FIRST)

Task 7.1 — MCP server implementation Tools exposed:

  • list_patterns(category)
  • get_pattern(name) -- full source + docs
  • generate_covenant(spec) -- AI describes intent, MCP returns recommended pattern + config
  • validate_covenant(sil_source) -- check OpenSilver best practices compliance
  • audit_covenant(sil_source) -- automated security checks (security-by-construction)
  • check_kip20_compliance(sil_source) -- verify Covenant ID handling
  • estimate_costs(sil_source) -- gas/size estimation

Task 7.2 — Coordinate with kaspacom-defi-mcp

  • KaspaCom has DeFi-specific MCP. Confirm OpenSilver MCP is complementary (general patterns vs DeFi specific).
  • Where possible, federate so agents can pull from both.

Task 7.3 — Distribution

  • Host at mcp.opensilver.dev
  • Config snippets for Claude Desktop, Cursor, OpenClaw, Claude Code
  • Document MCP-aware agent integration

Output of Phase 7: OpenSilver MCP live. Coordination with KaspaCom's MCP documented.

PHASE 8 — INTEGRATIONS (NEW)

Pattern library only matters if devs can find it where they're already working.

Task 8.1 — SilverScript Studio integration

  • Work with Kaspero Labs to add OpenSilver as a default library in the IDE
  • Patterns appear in the "import" picker
  • One-click pattern usage

Task 8.2 — KaspaCom Wallet integration

  • Work with KaspaCom to expose OpenSilver patterns in the wallet template selector
  • Users deploying covenants from the wallet get audited library patterns by default

Task 8.3 — Web Wizard UI

  • Hosted at wizard.opensilver.dev
  • Pick a pattern from a dropdown, configure parameters via UI, live SilverScript preview, one-click download or deploy-to-TN12
  • Embeddable as an iframe in the Kaspa docs site

Output of Phase 8: OpenSilver patterns visible in three major dev surfaces.

PHASE 9 — TESTNET VERIFICATION

Task 9.1 — End-to-end test suite For each of the 22 patterns:

  1. Deploy to TN12
  2. Execute happy path
  3. Execute every failure path
  4. Confirm gas costs match benchmarks
  5. Document TN12 transaction hashes

Task 9.2 — KIP-20 compliance tests

  • Every stateful pattern verified to handle Covenant IDs correctly
  • Lineage tracking tested across multiple state transitions

Task 9.3 — Cross-pattern composability

  • Vault containing a Vesting schedule
  • Escrow secured by MultiSig
  • Streaming Payment with TimeLock cap
  • ZK-Verified Oracle feeding into a Freelance contract
  • All composable combinations exercised

Output of Phase 9: TESTNET_VERIFICATION.md with 150+ on-chain transaction hashes.

PHASE 10 — AUDIT PREP

Task 10.1 — Internal review

  • Cross-review every pattern
  • Document every assumption explicitly
  • Apply Sutton's security-by-construction principle as a review checklist

Task 10.2 — External audit outreach

  • Identify SilverScript-capable auditors (limited pool initially)
  • Reach out to Ori Newman, Manyfest, IzioDev for review
  • Coordinate with one professional audit firm if available

Task 10.3 — Bug bounty program

  • KasBonds-secured bug bounty (eat your own dog food)
  • 10,000 KAS reward pool for critical findings

Output of Phase 10: Audit report or detailed reviews complete. Findings remediated.

PHASE 11 — MAINNET LAUNCH

Ship on Toccata activation day.

Task 11.1 — Mainnet verification

  • Compile every pattern against mainnet
  • Run small-amount mainnet deployment of each pattern
  • Confirm cost + behavior matches TN12

Task 11.2 — Public launch

  • Patterns published to npm production
  • Docs at opensilver.dev
  • MCP at mcp.opensilver.dev
  • Wizard at wizard.opensilver.dev

Task 11.3 — Ecosystem distribution

  • Submit PR to https://github.com/aspectron/awesome-kaspa
  • Submit PR to kaspa.org/build adding OpenSilver to recommended libraries
  • Coordinate with SilverScript Studio + KaspaCom Wallet on integration launch
  • Update KasBonds to use OpenSilver internally (dogfooding proof)
  • DM Olaf Weller offering KasPact integration support
  • Technical blog post: "Security-by-construction on Kaspa: introducing OpenSilver"
  • X thread timed to Toccata activation

Output of Phase 11: Live on mainnet. Integrated with SilverScript Studio + KaspaCom Wallet. Ecosystem outreach complete.

STATUS REPORTING

After each phase:

PHASE_N_STATUS: COMPLETE | BLOCKED | IN_PROGRESS
PATTERNS_COMPLETE: <count>/<total>
TESTNET_TXS: <list of TN12 transaction hashes>
DOCS_PAGES: <count>
TESTS_PASSING: <count>/<total>
ECOSYSTEM_COORDINATION: <up to date status>
BLOCKERS: <any, or NONE>
NEXT_PHASE: <phase>

End each successful run:

TASK_STATUS: COMPLETE
COMMIT: <hash>
DEPLOYED: <url or N/A>
PATTERNS_LIVE: <count>

RULES OF ENGAGEMENT

  1. Phase 0 is a parallel workstream, not a hard gate. Document outreach and feedback as it arrives, but continue implementation unless concrete upstream conflicts are discovered.
  2. Sutton's security-by-construction principle is the governing philosophy. Every pattern is reviewed against it.
  3. KIP-20 Covenant IDs are the foundation. Every stateful pattern uses them. Recursive lineage proofs are an anti-pattern.
  4. Every pattern is dogfooded. OpenSilver patterns must be used by KasBonds first as proof of fitness.
  5. No marketing claims without audit. "Battle-tested" requires either external audit or 30 days of mainnet usage with no critical findings.
  6. Document failure modes. Every pattern doc has a "WHEN NOT TO USE THIS" section.
  7. Backward compatibility from v1. Public interfaces frozen at v1. Breaking changes require v2.
  8. MIT licensed always. Patterns are public goods.
  9. Coordinate, do not compete. SilverScript Studio (IDE), KaspaCom Wallet (UX), kaspacom-defi-mcp (DeFi MCP) are partners, not competitors. OpenSilver is the library that powers them.
  10. Race the launch window. Toccata activation is the marketing event. Ship on activation day.

Begin with Phase 0. Toccata activation is approximately two weeks away. Time is the binding constraint, but ecosystem coordination is more important than speed.