Skip to content

Proposal/2025 07 flipper #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bellujrb wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Proposal/2025 07 flipper #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f485007
Proposal: HashStore contract for 32-byte hash storage
bellujrb Jul 8, 2025
e8dcc82
Proposal: Flipper contract for boolean storage and flipping
bellujrb Jul 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions SmartContracts/2025-07-08-FLIPPER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
107 changes: 107 additions & 0 deletions SmartContracts/2025-07-08-HashStore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<uint8, 32> hash;
};

struct SetHash_input { Array<uint8, 32> hash; };
struct SetHash_output {};

struct GetHash_input {};
struct GetHash_output { Array<uint8, 32> 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.