diff --git a/SmartContracts/2025-07-08-FLIPPER.md b/SmartContracts/2025-07-08-FLIPPER.md new file mode 100644 index 0000000..3c3bb4b --- /dev/null +++ b/SmartContracts/2025-07-08-FLIPPER.md @@ -0,0 +1,101 @@ +# Smart Contract Proposal - FLIPPER - 2025-07-08 + +This proposal introduces the Smart Contract **FLIPPER**, designed to be deployed directly on QUBIC. +The contract is **complementary to the `HashStore` Smart Contract** and is part of a broader architecture to build an **EVM-based Layer 2 (L2)** system — where contracts are executed off-chain, and their final state is anchored on-chain through cryptographic hashes. + +## Proposal + +Approve the deployment of the Smart Contract **FLIPPER** on the QUBIC network. + +This contract will serve as a minimal logic unit for execution testing in external environments (L2), while allowing its result to be tracked on-chain through the `HashStore` contract. + +This is an **infrastructure-only contract**. +It does **not handle any value** and **does not generate revenue** for shareholders. +Any invocation fees are **burned**. + +### Voting Options + +> Option 1: Yes, allow +> Option 2: No + +--- + +## Background + +- The `FLIPPER` contract is deployed **on-chain in QUBIC**, and its source has already been proposed in: [Pull Request #14](https://github.com/qubic/proposal/pull/14) +- It complements the proposed `HashStore` contract, enabling the storage of 32-byte state hashes that represent contract execution performed outside of QUBIC. +- Together, these contracts establish the foundation of a **modular Layer 2** using external EVM-compatible logic with **QUBIC as the final settlement and validation layer**. + +--- + +## Contract Behavior + +- Stores a single boolean value (`bit`); +- The public function `flip()` toggles the current value; +- Returns the updated value as output; +- Minimal state and logic, ideal for proof-of-concept and testing. + +--- + +## Contract Code + +```cpp +// src/contracts/Flipper.h + +struct FLIPPER { + bit value; +}; + +struct Flip_input {}; +struct Flip_output { + bit value; +}; + +PUBLIC_FUNCTION(flip) +{ + state.value = !state.value; + output.value = state.value; +} + +void REGISTER_USER_FUNCTIONS_AND_PROCEDURES() { + REGISTER_USER_FUNCTION(flip, 1); +} +``` + +--- + +## Integration with HashStore and Off-Chain Execution + +FLIPPER is used within an external backend (e.g. EVM-compatible execution engine). +After running flip() in this off-chain environment, the new state is serialized, hashed (32 bytes), and submitted to the QUBIC HashStore contract. + +This creates a verifiable link between off-chain logic and QUBIC's immutable ledger — enabling settlement, auditability, and traceability. + +**The flow is:** +1. FLIPPER is executed off-chain in L2; +2. The backend computes the resulting state hash; +3. This hash is stored on QUBIC using HashStore; +4. Auditors or other users can verify this chain of execution. + +--- + +## Rationale + +- Establishes a minimal, auditable smart contract on QUBIC; +- Enables and demonstrates the integration with external L2 environments; +- Provides a foundation for execution verification using state hashes; +- Directly supports the L2 EVM architecture using QUBIC for state anchoring; +- Empowers developers to test, simulate, and audit contract logic modularly. + +--- + +## Conclusion + +Approving the FLIPPER contract enables: + +- A live demonstration of QUBIC-based state anchoring for external systems; +- The start of a modular, extensible EVM-compatible Layer 2 architecture; +- Transparent and immutable state tracking on QUBIC; +- A developer-friendly entry point for infrastructure experimentation. + +FLIPPER is the first practical step in enabling hybrid off-chain/on-chain execution models on QUBIC. \ No newline at end of file diff --git a/SmartContracts/2025-07-08-HashStore.md b/SmartContracts/2025-07-08-HashStore.md new file mode 100644 index 0000000..7d3a5f6 --- /dev/null +++ b/SmartContracts/2025-07-08-HashStore.md @@ -0,0 +1,107 @@ +# Smart Contract Proposal - L2 HashStore - 2025-07-08 + +To enable decentralized anchoring of off-chain computation states, this proposal suggests the deployment of a lightweight Smart Contract called **HashStore**. This contract stores 32-byte hashes on the QUBIC chain, representing external computation states. + +## Proposal + +Allow the deployment of the Smart Contract **HashStore** on QUBIC. +The contract enables external systems (e.g., Layer 2 EVM execution environments) to submit cryptographic proofs of state, ensuring auditability and traceability on-chain. + +This is an **infrastructure smart contract**. +It will **not generate any revenue** for shareholders. +All invocation rewards are **burned**. + +### Voting Options + +> Option 1: Yes, allow +> Option 2: No + +--- + +## Purpose + +This contract is part of a broader initiative to build an **EVM-compatible Layer 2** (L2) on top of QUBIC. While the contract logic runs off-chain, this Smart Contract allows developers to publicly anchor the final state of those executions. + +Use cases include: +- Anchoring state roots from off-chain EVM contract execution. +- Verifying state changes through audit trails. +- Using QUBIC as a **settlement layer**. + +--- + +## Contract Behavior + +- `SetHash`: Saves a 32-byte hash to contract state (overwriting the previous one). +- `GetHash`: Returns the currently stored hash. +- The contract keeps **only the most recent hash**, ensuring minimal on-chain storage. + +--- + +## Technical Implementation + +```cpp +struct HASHSTORE { + Array hash; +}; + +struct SetHash_input { Array hash; }; +struct SetHash_output {}; + +struct GetHash_input {}; +struct GetHash_output { Array hash; }; + +PUBLIC_PROCEDURE(SetHash) +{ + for (uint32 i = 0; i < 32; i += 1) { + state.hash[i] = input.hash[i]; + } +} + +PUBLIC_FUNCTION(GetHash) +{ + for (uint32 i = 0; i < 32; i += 1) { + output.hash[i] = state.hash[i]; + } +} + +void REGISTER_USER_FUNCTIONS_AND_PROCEDURES() { + REGISTER_USER_PROCEDURE(SetHash, 1); + REGISTER_USER_FUNCTION(GetHash, 2); +} +``` + +--- + +## Security and Design + +- Open to all users for writing hashes. +- No funds are stored or transferred — no financial risk. +- Each invocation requires a reward (e.g., 1 mio QUBIC) that is burned, preventing spam. +- Stateless beyond the last saved hash, enabling lightweight and efficient use. + +--- + +## Rationale + +This contract establishes a minimal yet critical foundation for off-chain proof anchoring and traceable settlement. It enables: + +- External EVM-based systems to record state transitions. +- Developers to build rollups, zk-based systems, or lightweight bridges. +- A future-proof design that integrates smoothly with decentralized compute infrastructure. + +--- + +## Possible Extensions (Future Proposals) + +- Store multiple hashes (ring buffer or historical log). +- Merkle Root storage for multiple contracts or accounts. +- Submit zero-knowledge or recursive proofs tied to state changes. + +--- + +## Example Use Case + +1. A user deploys the FLIPPER contract off-chain via a custom EVM backend (e.g., Express + JS engine). +2. The backend executes flip(), changing contract state. +3. It hashes the new EVM state and submits that hash via SetHash to the QUBIC HashStore. +4. The hash becomes publicly visible and anchored in the QUBIC ledger. \ No newline at end of file