Ein Smart Contract (SC) auf Qubic ist eine einzelne C++-Datei, die mit der Qubic Public Interface (QPI) geschrieben wird. Der Code läuft nicht auf einem Server — er läuft gleichzeitig auf allen 676 Qubic-Computern (den sogenannten "Computors") im Netzwerk.

• Kein Server nötig — der Code ist immer online, solange das Qubic-Netzwerk läuft
• Unveränderlich — einmal deployed kann der Code nicht heimlich geändert werden
• Transparent — jeder kann den Code lesen und prüfen
• Kein Vertrauen nötig — der SC erzwingt die Regeln, kein Mensch entscheidet

A Smart Contract (SC) on Qubic is a single C++ file written using the Qubic Public Interface (QPI). The code does not run on a server — it runs simultaneously on all 676 Qubic computers ("Computors") in the network.

• No server needed — the code is always online as long as the Qubic network runs
• Immutable — once deployed, the code cannot be secretly changed
• Transparent — anyone can read and verify the code
• Trustless — the SC enforces the rules; no human decides

Das Herzstück von QubicShield ist die Rückzahlung des Deposits an legitime Nutzer. Das kostet auf anderen Blockchains Geld:

The core of QubicShield is the refund of the deposit to legitimate users. On other blockchains this costs money:

Die Grundidee — Rechenarbeit oder Zahlung als Schutz vor Missbrauch — ist nicht neu. Aber niemand hat sie bisher als vollständiges Webprodukt umgesetzt:

The core idea — work or payment as a barrier against abuse — is not new. But nobody has realized it as a complete web product:

Im Demo-Server gibt es eine Datei src/depositManager.ts. Die sieht professionell aus, aber sie ist ein Mock — alle Daten leben nur im RAM:

The demo server has a file src/depositManager.ts. It looks professional but it is a mock — all data lives only in RAM:

Jede Funktion im Mock hat ein Gegenstück im SC:

Every function in the mock has a counterpart in the SC:

In Qubic gibt es zwei Arten von Entry Points — der wichtigste Unterschied:

In Qubic there are two types of entry points — the most important distinction:

QPI ist kein normales C++. Die Einschränkungen sind Absicht — sie machen den SC sicher und deterministisch:

QPI is not regular C++. The constraints are intentional — they make the SC safe and deterministic:

Jedes Deposit wird als DepositEntry Struct gespeichert. Da es keinen string-Typ gibt, nutzen wir QPI-eigene Typen:

Every deposit is stored as a DepositEntry struct. Since there is no string type, we use QPI-native types:

Warum 512 Slots? Das ist die maximale Anzahl gleichzeitiger Sessions. Mehr kostet mehr Speicher auf jedem der 676 Nodes.

Why 512 slots? That is the maximum number of concurrent sessions. More costs more storage on each of the 676 nodes.

id ist ein QPI Built-in Typ — ein 60-Byte-Wert der typischerweise eine Wallet-Adresse oder einen Hash darstellt.

Wie wird der Session-Token erzeugt?

id is a QPI built-in type — a 60-byte value that typically represents a wallet address or hash.

How is the session token generated?

qpi.K12() ist Qubics eigene Hash-Funktion. Der Token ist:

• Einzigartig pro Wallet
• Nicht vorhersagbar von außen
• Verifizierbar — der Proxy prüft ihn mit ValidateSession()

qpi.K12() is Qubic's own hash function. The token is:

• Unique per wallet
• Unpredictable from outside
• Verifiable — the proxy checks it with ValidateSession()

Qubic hat keine Echtzeituhr. Stattdessen gibt es Ticks — einen globalen Zähler der vom Netzwerk hochgezählt wird.

• Aktuell mehr als 2 Ticks pro Sekunde (Intervall < 1 Sek)
• 3.600 Ticks ≈ weniger als 30 Minuten (je nach aktueller Tick-Rate)
• qpi.tick() gibt den aktuellen Tick zurück

Qubic has no real-time clock. Instead there are ticks — a global counter incremented by the network.

• Currently more than 2 ticks per second (interval < 1 sec)
• 3,600 ticks ≈ less than 30 minutes (depends on current tick rate)
• qpi.tick() returns the current tick

Qubic ruft diese Blöcke automatisch auf — kein externer Trigger nötig.

Qubic calls these blocks automatically — no external trigger needed.

Läuft ca. einmal pro Woche. Bei uns: Initialisierung des Operators beim ersten Deploy.

Runs approx. once per week. Here: operator initialization on first deploy.

Läuft aktuell mehr als 2× pro Sekunde (Intervall < 1 Sek). Bei uns: automatisches Expire abgelaufener Sessions.

Currently runs more than 2× per second (interval < 1 sec). Here: automatic expiry of stale sessions.

Beim Refund() müssen BEIDE Werte übereinstimmen:

For Refund() BOTH values must match:

Jede Procedure und Function muss mit einem fixen Index registriert werden. Der Index ist die "Telefonnummer" über die externe Aufrufer den Entry Point adressieren.

Every procedure and function must be registered with a fixed index. The index is the "phone number" external callers use to address the entry point.

Die beiden Projekte sind keine Konkurrenten — das eine ist das Protokoll, das andere ist die Infrastruktur. QubicShield läuft heute als Middleware direkt im Web-Server und funktioniert vollständig ohne einen Node.

The two projects are not competitors — one is the protocol, the other is the infrastructure. QubicShield runs today as middleware directly inside the web server and works fully without any node.

Forfeitierte QUBIC blieben bisher für immer im Contract. Die neue PUBLIC_PROCEDURE(WithdrawForfeited) erlaubt es dem Operator, dieses QUBIC auf seine Wallet zu transferieren.

Forfeited QUBIC previously stayed locked in the contract forever. The new PUBLIC_PROCEDURE(WithdrawForfeited) lets the operator transfer this QUBIC to their wallet.

Was ist qpi.contractBalance()?

Jeder SC hat eine eigene Wallet-Adresse auf der Blockchain. qpi.contractBalance() gibt den echten, aktuellen On-Chain-Saldo zurück — also das QUBIC das wirklich dort liegt.

What is qpi.contractBalance()?

Every SC has its own wallet address on the blockchain. qpi.contractBalance() returns the real, current on-chain balance — the QUBIC that is actually there.

Wenn QubicShield als echter Qubic Smart Contract veröffentlicht wird, durchläuft er eine Dutch Auction (IPO). Alle QUBIC aus dem IPO werden sofort verbrannt — das ist Protokoll. Der SC bekommt dabei genau 676 Anteile, einer für jeden der 676 Computors im Netzwerk.

When QubicShield is published as a real Qubic smart contract, it goes through a Dutch Auction (IPO). All QUBIC from the IPO is immediately burned — that is the protocol. The SC receives exactly 676 shares, one for each of the 676 Computors in the network.

Wenn ein Angreifer forfeitiert wird, soll sein Deposit so verteilt werden:

When an attacker is forfeited, their deposit will be distributed as follows:

Ein Struct (kurz für "Structure") ist ein Behälter für mehrere zusammengehörige Werte — wie eine Kiste mit beschrifteten Fächern. Alle Felder liegen hintereinander im Speicher.

A struct (short for "structure") is a container for multiple related values — like a box with labelled compartments. All fields are stored consecutively in memory.

Der QubicShield-Server ist ein einzelner Express-Prozess, der gleichzeitig das Frontend ausliefert und die API-Endpunkte bereitstellt. Es gibt keinen separaten Frontend-Server.

Server starten

cd qubicshield
npm run dev

Die Konsole zeigt dann:

QubicShield Demo Server running at http://localhost:3000
Backend: 🧪 In-Memory Mock

Routes:
  POST /api/deposit          – create deposit
  GET  /api/validate/:token  – validate token
  POST /api/refund           – refund deposit
  GET  /api/protected        – access protected resource
  GET  /api/stats            – system statistics
  GET  /                     – demo UI

Was du siehst

Der Server liefert drei Seiten unter http://localhost:3000:

Alle Seiten: DE / EN Sprachumschalter oben rechts · grüner Punkt = Server online · Navigation zwischen den Seiten über die Buttons Home / Simulation / Dashboard.

Typischer Ablauf

1. Deposit erstellen — beliebige Wallet-Adresse eingeben, Betrag wählen, Button klicken. Server gibt sessionId + accessToken zurück — werden automatisch in alle anderen Felder übertragen.
2. Token validieren — prüft ob der Token noch gültig ist (Ablaufzeit, Request-Zähler).
3. Protected Resource aufrufen — simuliert einen API-Aufruf unter dieser Session. Bei zu vielen Anfragen wird der Deposit einbehalten (DDoS-Erkennung).
4. Refund anfordern — gibt den Deposit zurück, solange kein Angriffsmuster erkannt wurde.
5. Stats abrufen — Übersicht aller Deposits, Forfeits und Gesamtzahlen.

Jede Karte zeigt außerdem den äquivalenten curl-Befehl zum Aufklappen — nach einem Deposit werden die echten Werte automatisch eingesetzt.

Grundprinzip

1 Deposit = 1 Session = 1 Token. Das ist die Sicherheitslogik — jeder API-Zugriff hat einen eigenen Einsatz. Mehrmals auf „Deposit erstellen" klicken erzeugt mehrere unabhängige Sessions mit je eigenem Token und heldAmount. Ein Token verfällt nach 30 Minuten — danach ist ein neuer Deposit nötig.

Mock-Modus vs. echter SC

Standardmäßig läuft alles im Mock-Modus — kein echtes Wallet nötig, Deposits leben nur im RAM (weg bei Neustart). Für den echten Smart Contract:

USE_REAL_SC=true npm run dev

The QubicShield server is a single Express process that simultaneously serves the frontend and provides the API endpoints. There is no separate frontend server.

Starting the server

cd qubicshield
npm run dev

The console will show:

QubicShield Demo Server running at http://localhost:3000
Backend: 🧪 In-Memory Mock

Routes:
  POST /api/deposit          – create deposit
  GET  /api/validate/:token  – validate token
  POST /api/refund           – refund deposit
  GET  /api/protected        – access protected resource
  GET  /api/stats            – system statistics
  GET  /                     – demo UI

What you see

The server serves three pages under http://localhost:3000:

All pages: DE / EN language toggle top right · green dot = server online · navigation between pages via the Home / Simulation / Dashboard buttons.

Typical workflow

1. Create deposit — enter any wallet address, choose an amount, click the button. The server returns a sessionId + accessToken — auto-filled into all other fields.
2. Validate token — checks if the token is still valid (expiry time, request counter).
3. Call protected resource — simulates an API call under this session. Too many requests trigger DDoS detection and the deposit is forfeited.
4. Request refund — returns the deposit as long as no attack pattern was detected.
5. Fetch stats — overview of all deposits, forfeits, and totals.

Each card also shows the equivalent curl command — click to expand. After a deposit, the real values are automatically substituted.

Core principle

1 Deposit = 1 Session = 1 Token. This is the security logic — every API access has its own stake. Clicking "Create Deposit" multiple times creates multiple independent sessions, each with its own token and heldAmount. A token expires after 30 minutes — a new deposit is required after that.

Mock mode vs. real SC

By default everything runs in mock mode — no real wallet needed, deposits live in RAM only (gone on restart). To use the real smart contract:

USE_REAL_SC=true npm run dev

QubicShield erkennt Angriffsmuster automatisch in zwei unabhängigen Schichten und behält den Deposit des Angreifers ein (forfeit). Der Angreifer verliert sein Geld — der Dienst bleibt verfügbar.

Schicht 1 — Rate Limiter Middleware

Datei: src/middleware/rateLimiter.ts

Implementiert ein Sliding Window pro Access-Token:

• Fenster: 60 Sekunden
• Schwellwert: 50 Anfragen → setzt isAttacking = true
• Setzt Response-Header: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window
• Blockt nicht sofort — gibt dem Route-Handler die Möglichkeit, den Deposit zuerst einzubehalten

Schicht 2 — DepositManager

Datei: src/depositManager.ts → Methode isAttacking()

Zweiter unabhängiger Zähler mit eigenem Schwellwert:

• Fenster: 60 Sekunden
• Schwellwert: 100 Anfragen → Deposit wird einbehalten
• Wird auch beim Refund-Versuch geprüft — wer angreift und dann Geld zurückfordert, verliert den Deposit trotzdem

Ablauf bei erkanntem Angriff

1. Request kommt rein → rateLimiter prüft (50 req/min)
2. Route: depositManager.isAttacking() prüft (100 req/min)
3. Bei Überschreitung → forfeitDeposit() → Deposit einbehalten
4. HTTP 403: "Attack pattern detected. Deposit has been forfeited."

Live-Demo im API Tester

Im API Tester (localhost:3000) gibt es die Karte „DDoS-Angriff simulieren". Ein Klick auf „Angriff starten" sendet automatisch 110 Anfragen in schneller Folge. Ein Fortschrittsbalken zeigt den Verlauf — sobald der Server den Angriff erkennt (typisch nach ~100 Anfragen), wird der Deposit einbehalten und der Balken springt auf rot.

QubicShield automatically detects attack patterns in two independent layers and forfeits the attacker's deposit. The attacker loses their money — the service stays available.

Layer 1 — Rate Limiter Middleware

File: src/middleware/rateLimiter.ts

Implements a sliding window per access token:

• Window: 60 seconds
• Threshold: 50 requests → sets isAttacking = true
• Sets response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window
• Does not block immediately — lets the route handler forfeit the deposit first

Layer 2 — DepositManager

File: src/depositManager.ts → method isAttacking()

Second independent counter with its own threshold:

• Window: 60 seconds
• Threshold: 100 requests → deposit is forfeited
• Also checked on refund attempts — an attacker trying to reclaim their deposit still loses it

Flow when attack is detected

1. Request arrives → rateLimiter checks (50 req/min)
2. Route: depositManager.isAttacking() checks (100 req/min)
3. Threshold exceeded → forfeitDeposit() → deposit held
4. HTTP 403: "Attack pattern detected. Deposit has been forfeited."

Live demo in the API Tester

The API Tester at localhost:3000 has a card "Simulate DDoS Attack". One click on "Start Attack" automatically fires 110 requests in rapid succession. A progress bar shows the progress — once the server detects the attack (typically after ~100 requests), the deposit is forfeited and the bar turns red.