diff --git a/contracts/origin-mdk-reconciliation/DESIGN.md b/contracts/origin-mdk-reconciliation/DESIGN.md new file mode 100644 index 0000000..56f4239 --- /dev/null +++ b/contracts/origin-mdk-reconciliation/DESIGN.md @@ -0,0 +1,250 @@ +# origin-mdk-reconciliation β€” Design Study (Slice 3.6) + +**Documento**: `contracts/origin-mdk-reconciliation/DESIGN.md` +**VersiΓ³n**: 1.0 DRAFT (Slice 3.6 design study, v0.0.46) +**Autores**: Charon βš“ (Pilar 4 Origin Chain) + propuesta canonical para Marihan πŸ’Ž (OMC + MDK authority) cross-pillar coord +**Filed**: 2026-05-27 +**Estado**: DRAFT β€” pending Marihan endorsement + cross-pillar coord design contract +**ClasificaciΓ³n**: L3 cross-cutting / Boundary architecture / Contract Atelier integration + +--- + +## Β§0 β€” Por quΓ© Slice 3.6 es DESIGN STUDY (NO contract deployable) + +Slices 3.2-3.5 entregaron contract templates ink! v6 deployable directos via pallet-revive Index 11. Slice 3.6 es diferente: explora la **boundary arquitectural** entre dos sistemas WASM distintos que coexisten en Origin Metaverse, NO un contract template canonical. + +**Dos sistemas WASM distintos**: + +1. **ink! v6 contracts (this template library)**: + - Run inside `pallet-revive` (PolkaVM RISC-V execution) + - ABI: pallet-revive defined (constructors + messages + events) + - Lifecycle: on-chain (deploy via upload_code + instantiate) + - State: stored en Origin Chain canonical storage + - Gas metering: pallet-revive fuel + storage deposits + - Caller context: AccountId + Balance + Block info via pallet env + +2. **origin-mdk skills (Marihan's MDK β€” skill-wasm-stdlib)**: + - Run inside `wasmtime` sandbox (host-side, NOT on-chain) + - ABI: OMC v1.0 SEALED (7 exports: omc_tick + alloc + state + memory) + - Lifecycle: off-chain (deploy via Atelier Marihan + distributed via .origin bundles P2P) + - State: ephemeral en interpreter session OR persisted via SoulSnapshot + - Resource limits: fuel 1M units + 100ms epoch + 512KB memory + - Caller context: SemanticGraph postcard input via OMC interpreter + +**Pregunta canonical**: ΒΏcΓ³mo coexisten + interactΓΊan estos dos sistemas? + +--- + +## Β§1 β€” Problema arquitectural canonical + +### Β§1.1 β€” Use cases que requieren bridge + +| Use case | Origin de la action | Target requerido | +|----------|---------------------|------------------| +| **Atelier skill becomes NFT** | Marihan skill `physics.faraday_law` shipped | ink! NFT mint contract (this library 3.2) | +| **Skill execution receipt on-chain** | OMC interpreter runs skill | ink! receipt contract (proof of execution + cognitive_gain) | +| **Chain attestation in skill** | Skill validates on-chain credential | ink! credential verify (this library 3.4) | +| **Cross-pillar fee schedule** | Skill checks fee_for_action canonical | Mathi OitFeeSchedule (off-chain) + pallet-origin-fees (chain) | +| **Skill marketplace purchase** | Atelier user buys skill bundle | ink! marketplace contract + skill bundle download | +| **AGI commercial reputation slash** | Daimonion fraud detected en M2M escrow | ink! reputation slash contract (this library 3.5) | +| **Soul TOML on-chain anchor** | Marihan soul.toml gets BLAKE3 attested | ink! provenance attest contract | + +### Β§1.2 β€” CuΓ‘l NO es el problema + +NO necesitamos: +- Run ink! contracts dentro del OMC interpreter (different VMs canonical) +- Run origin-mdk skills dentro de pallet-revive (different ABI canonical) +- Unified single-VM rewrite (mantenemos boundary canonical) + +Lo que SÍ necesitamos: +- **MensajerΓ­a entre sistemas**: ΒΏcΓ³mo origin-mdk skill invoca ink! contract method? +- **State synchronization**: ΒΏcΓ³mo skill state recordable on-chain? +- **Authentication**: ΒΏcΓ³mo skill auth queries identify caller on-chain? +- **Event coordination**: ΒΏcΓ³mo ink! event triggers skill execution off-chain? + +--- + +## Β§2 β€” Tres patrones canonical propuestos + +### Β§2.1 β€” Pattern A: Off-chain β†’ On-chain (RPC client) + +**Direction**: origin-mdk skill (off-chain) β†’ ink! contract (on-chain) + +**Mechanism**: Origin Navigator (host del interpreter) expone RPC client canonical que skill puede invocar (via host import canonical OMC v2.0 future addition). + +```rust +// En skill ink! v6 host abstraction (futuro OMC ABI v2.0 host import canonical) +extern "C" { + /// Invoke ink! contract method canonical via Origin Navigator RPC. + /// Returns transaction hash + result data postcard-serialized. + fn host_invoke_chain_contract( + contract_addr_h160_ptr: u32, // H160 EVM address mapped from AccountId32 + method_selector_ptr: u32, + args_postcard_ptr: u32, + result_buf_ptr: u32, + ) -> u32; +} +``` + +**Use cases canonical Pattern A**: +- Skill running locally observa "cognitive_gain HIGH" β†’ invoca on-chain ink! attestation contract +- Skill marketplace purchase flow β†’ skill bundle download triggers NFT mint contract +- Skill validates user identity β†’ invoca on-chain credential verify contract + +**Trade-offs**: +- βœ… Skill remains lightweight (OMC ABI sealed unchanged) β€” host import canonical extension +- βœ… Skill author NO needs Substrate/ink! knowledge β€” abstracted via host +- βœ… Async natural (skill waits OR fire-and-forget) +- ⚠️ Network latency: skill suspended hasta TX confirmation (~6-12s Origin Chain finality) +- ⚠️ Origin Navigator MUST be online + wallet authorized para skill RPC + +### Β§2.2 β€” Pattern B: On-chain β†’ Off-chain (Event subscription) + +**Direction**: ink! contract (on-chain event) β†’ origin-mdk skill (off-chain reaction) + +**Mechanism**: ink! contract emite events canonical. Origin Navigator subscribe canonical via Substrate events RPC. Triggered events activate skill execution canonical (in OMC interpreter). + +```rust +// En ink! contract (esta library) +#[ink(event)] +pub struct SkillExecutionRequest { + #[ink(topic)] + pub skill_id_hash: [u8; 32], // BLAKE3 del skill_id canonical + #[ink(topic)] + pub caller: AccountId, + pub semantic_graph_postcard: Vec, // serialized SemanticGraph +} + +// En Origin Navigator (host) +// Subscribe to SkillExecutionRequest events via Substrate WebSocket RPC +// Trigger interpreter.tick(skill_id, semantic_graph) canonical +``` + +**Use cases canonical Pattern B**: +- Pago on-chain β†’ trigger skill execution canonical (commerce purchase) +- DAO vote approved β†’ trigger Atelier skill module compilation canonical +- NFT minted β†’ trigger skill bundle distribution canonical via Hypercore + +**Trade-offs**: +- βœ… Decoupled async: ink! contract NO espera skill canonical completion +- βœ… Standard Substrate event subscription pattern canonical +- ⚠️ Eventual consistency: skill execution latency post-event +- ⚠️ Origin Navigator MUST be subscribed canonical (offline = missed events) + +### Β§2.3 β€” Pattern C: Shared state via Hash Anchoring (loose coupling) + +**Direction**: Bidirectional via inmutable hash anchors + +**Mechanism**: Estados canonical en ambos sistemas anclados via BLAKE3 hashes. Skill state hash β†’ on-chain canonical immutable record. ink! contract storage hash β†’ off-chain canonical Hypercore replicated. + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ink! contract canonical β”‚ β”‚ origin-mdk skill canonical β”‚ +β”‚ (on-chain pallet-revive) β”‚ β”‚ (off-chain OMC interpreter) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ storage: β”‚ β”‚ state: β”‚ +β”‚ skill_state_hash: [u8; 32] β”‚ ◄────── β”‚ BLAKE3(skill_state) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ storage: β”‚ β”‚ external read: β”‚ +β”‚ BLAKE3(contract_state) β”‚ ──────► β”‚ contract_state_hash β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + └───────────── verify hash β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + cross-system canonical integrity +``` + +**Use cases canonical Pattern C**: +- Atelier skill version hash β†’ on-chain version registry (provenance) +- ink! NFT collection state hash β†’ off-chain Hypercore mirror canonical +- Cross-system audit canonical: verify state coherence + +**Trade-offs**: +- βœ… Minimal coupling: ambos sistemas operate independently canonical +- βœ… Inmutable canonical attestation (Inmutable #26) +- ⚠️ NO real-time interaction (read hash, verify, act later) +- ⚠️ Reconciliation logic canonical en host (Origin Navigator OR Atelier) + +--- + +## Β§3 β€” RecomendaciΓ³n canonical per use case + +| Use case | Pattern recomendado | Rationale | +|----------|---------------------|-----------| +| Atelier skill becomes NFT | **B** (event subscription) | NFT mint triggered desde skill publish action | +| Skill execution receipt | **A** (RPC client) | Skill post-execution invoca attestation directamente | +| Chain credential verify in skill | **A** (RPC client) | Skill queries credential pre-execution | +| Cross-pillar fee schedule | **A** (RPC client) | Skill queries `fee_for_action(HardwareTier)` | +| Skill marketplace purchase | **B** (event subscription) | Purchase event triggers skill download | +| AGI reputation slash | **A** (RPC client) | Daimonion fraud detection calls slash directly | +| Soul TOML on-chain anchor | **C** (hash anchoring) | Inmutable canonical record sin real-time interaction | + +--- + +## Β§4 β€” Implementation roadmap canonical + +### Fase 1 (Q4 2026 β€” pre-MVP) +- **Cross-pillar Design Contract** opens canonical: `ORIGIN_MDK_PALLET_REVIVE_BOUNDARY_V1` + - Co-authors: Charon (pallet-revive ABI) + Marihan (OMC ABI v1.0 SEALED) + Sussi (Ethos attestation) + Ergon (architectural review) + - Ratification target: 2026-12 +- **OMC ABI v2.0 spec draft canonical**: extension canonical para new host imports + - `host_invoke_chain_contract` (Pattern A) + - `host_query_chain_storage` (Pattern A read-only) + - `host_subscribe_chain_event` (Pattern B) + - **Backwards compat**: skills v1.0 sigan funcionando canonical sin breakage + +### Fase 2 (Q1 2027 β€” MVP integration) +- Origin Navigator implementa RPC bridge canonical (Pattern A + B) +- Atelier Marihan integra "Anchor skill to chain" UI canonical (Pattern C) +- Reference example canonical: skill `physics.faraday_law` con on-chain attestation post-execution +- E2E test: skill execution β†’ ink! attestation contract β†’ verification cross-system canonical + +### Fase 3 (Q2-Q3 2027 β€” productionizaciΓ³n) +- Origin Contract Atelier integra "Bridge designer" canonical visual UI (per Charon Atelier propuesta David 2026-05-27) +- Patterns A/B/C selectable canonical per template +- Charon copilot validates cross-system coherence canonical pre-deploy + +### Fase 4 (Q4 2027+ β€” ecosystem maturity) +- Standard library canonical de bridge primitives (skill `bridge.attest`, `bridge.invoke_contract`) +- Daimonion auto-suggest bridge pattern canonical based on skill intent +- Cross-pillar metrics canonical: bridge usage analytics OCC Capacity #2 VPS Fleet + +--- + +## Β§5 β€” Open questions pending cross-pillar coord + +| Question | Stakeholder | Resolution path | +|----------|-------------|-----------------| +| OMC ABI v2.0 host imports β€” backwards compat strategy? | Marihan | Design Contract Fase 1 | +| Origin Navigator wallet authorization per-skill canonical? | Marihan + Mathi (Consent Gate) | Design Contract Fase 1 | +| ink! contract event subscription canonical scaling? | Charon + Ergon (architecture) | Empirical test Fase 2 | +| Hash anchoring on-chain storage cost canonical (DepositPerItem)? | Charon (pallet-revive tuning) | Phase 3.x deposit refinement | +| Cross-Origin coordination (skill on Chain A β†’ contract on Chain B)? | Ergon (cross-pillar L0 vision) | Future canonical Phase 8 mainnet | + +--- + +## Β§6 β€” KG triples canonical + +- `(origin_mdk_reconciliation_design_v1, parent_doc, origin_contract_atelier_v1)` +- `(origin_mdk_reconciliation_design_v1, authored_by, agent:charon)` +- `(origin_mdk_reconciliation_design_v1, endorser_pending, agent:marihan)` +- `(origin_mdk_reconciliation_design_v1, pattern_a_canonical, off_chain_to_on_chain_rpc)` +- `(origin_mdk_reconciliation_design_v1, pattern_b_canonical, on_chain_to_off_chain_event)` +- `(origin_mdk_reconciliation_design_v1, pattern_c_canonical, shared_state_hash_anchoring)` +- `(origin_mdk_reconciliation_design_v1, requires_dc, origin_mdk_pallet_revive_boundary_v1)` +- `(origin_mdk_reconciliation_design_v1, filed_at, 2026-05-27)` + +--- + +## Β§7 β€” Cierre canonical + +Slice 3.6 cierra Phase 3 templates library canonical con un **design study** (NO contract template deployable) reconociendo que la integraciΓ³n profunda entre ink! v6 (pallet-revive on-chain) y origin-mdk WASM (OMC interpreter off-chain) es un **cross-pillar architectural problem** que require coord formal con Marihan + ratification via Design Contract canonical. + +Pattern A (RPC) + Pattern B (events) + Pattern C (hashes) son 3 propuestas viables que cubren todos los use cases canonical conocidos. RecomendaciΓ³n canonical por use case mapped per Β§3. + +Roadmap canonical 4-fase Q4 2026 β†’ Q4 2027 entrega integraciΓ³n productionizada cuando cargo-contract v6 + Atelier MVP + Origin Navigator bridge canonical convergen. + +**Charon Atelier canonical** (Capacidad #10 OCC propuesta David 2026-05-27) servirΓ‘ como visual canvas para bridge designer Fase 3 β€” humans (David + team) configure visualmente quΓ© pattern usar per contract + Charon copilot validates cross-system coherence canonical pre-deploy. + +βš“ Templates library 5/5 canonical SCAFFOLD COMPLETE. La nave smart contracts armada + boundary design study filed. Mission Phase 3 Slices 3.1-3.6 entregadas end-to-end canonical. + +β€” Charon βš“ (Pilar 4, Slice 3.6 design study filed 2026-05-27)