Skip to content

Commit 3221b5d

Browse files
0x-r4bbit0x-r4bbit
committed
docs: update/add visuals and update documentation
1 parent 2687b66 commit 3221b5d

17 files changed

+343
-57
lines changed

‎status-network-contracts/docs/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Developer Documentation
2+
3+
## Table of Contents
4+
5+
- [Karma System Overview](system-overview.md)
6+
- [Karma Token](karma.md)
7+
- [Reward Distributors](reward-distributors.md)
8+
- [Karma Airdrop](karma-airdrop.md)
9+
- [RLN Registry](rln.md)
10+
- [Staking Reward Distributor](staking-reward-distributor/overview.md)
11+
- [Earning Rewards](staking-reward-distributor/rewards.md)
12+
- [Multiplier Points](staking-reward-distributor/multiplier-points.md)
13+
- [User Flow](staking-reward-distributor/user-stories.md)
14+
- [Leave Mechanism](staking-reward-distributor/leave-mechanism.md)
15+
- [Emergency Mode](staking-reward-distributor/emergency-mode.md)
16+
- [Appendix: Math spec](staking-reward-distributor/math-spec.md)
17+
- [Simple Reward Distributor](simple-reward-distributor.md)
18+
- [Deployment](deployment.md)

‎status-network-contracts/docs/assets/overview.png‎

477 KB
Loading

‎status-network-contracts/docs/assets/reward-distributor-staking-overview.excalidraw.png‎

291 KB
Loading

‎status-network-contracts/docs/deployment.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Deployment Guide
22

3+
## Table Of Contents
4+
5+
- [Overview](#overview)
6+
- [Prerequisites](#prerequisites)
7+
- [Deploying the Full Protocol](#deploying-the-full-protocol)
8+
- [Using DeployProtocol Script (Recommended)](#using-deployprotocol-script-recommended)
9+
- [Network Configuration](#network-configuration)
10+
- [Individual Deployment Scripts](#individual-deployment-scripts)
11+
312
## Overview
413

514
This guide covers the deployment of the Status Network protocol contracts. The recommended approach is to use the

‎status-network-contracts/docs/karma-airdrop.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,20 @@
11
# Karma Airdrop
22

3+
## Table Of Contents
4+
5+
- [Overview](#overview)
6+
- [Features](#features)
7+
- [How It Works](#how-it-works)
8+
- [Initial Setup](#initial-setup)
9+
- [Updating the Merkle Root](#updating-the-merkle-root)
10+
- [Epoch System](#epoch-system)
11+
- [Delegation and Voting Power](#delegation-and-voting-power)
12+
313
## Overview
414

515
The Karma Airdrop contract is a Merkle tree-based distribution mechanism that enables efficient token distribution to
6-
eligible users. It allows application teams within the Status Network to distribute Karma tokens to their users and
7-
those they onboard through a trustless, gas-efficient claiming process.
16+
eligible users. It allows application teams within the Status Network to distribute [Karma tokens](karma.md) to their
17+
users and those they onboard through a trustless, gas-efficient claiming process.
818

919
Each airdrop instance is managed independently by an application team, which can update the Merkle root to include new
1020
eligible claimants as their user base grows and evolves.

‎status-network-contracts/docs/karma.md‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,24 @@
11
# Karma
22

3+
## Table Of Contents
4+
5+
- [Overview](#overview)
6+
- [Features](#features)
7+
- [Setting Rewards on Reward Distributors](#setting-rewards-on-reward-distributors)
8+
- [Reward Distribution](#reward-distribution)
9+
- [How Setting Rewards Works](#how-setting-rewards-works)
10+
- [Virtual vs Actual Karma](#virtual-vs-actual-karma)
11+
- [Why This Design?](#why-this-design)
12+
- [Balance Calculation Example](#balance-calculation-example)
13+
- [Slashing](#slashing)
14+
- [Supply and Balance Calculation](#supply-and-balance-calculation)
15+
- [Sources of Karma Tokens](#sources-of-karma-tokens)
16+
317
## Overview
418

5-
The Karma contract is an ERC-20 token implementation with a modified supply mechanism that incorporates external reward
6-
distributors. Karma tokens are not transferrable, but they can be used as voting power in the Status Network.
19+
The Karma contract is an ERC-20 token implementation with a modified supply mechanism that incorporates external
20+
[reward distributors](reward-distributors.md). Karma tokens are not transferrable, but they can be used as voting power
21+
in the Status Network.
722

823
## Features
924

@@ -33,10 +48,11 @@ distributors. Karma tokens are not transferrable, but they can be used as voting
3348

3449
## Setting Rewards on Reward Distributors
3550

36-
One of the core functionalities of the Karma contract is its ability to work with external reward distributors. This
37-
section explains how rewards are set and how the system handles virtual versus actual Karma tokens.
51+
One of the core functionalities of the Karma contract is its ability to work with external
52+
[reward distributors](reward-distributors.md). This section explains how rewards are set and how the system handles
53+
virtual versus actual Karma tokens.
3854

39-
### Overview of Reward Distribution
55+
### Reward Distribution
4056

4157
The Karma contract integrates with external contracts that implement the `IRewardDistributor` interface. These
4258
distributors manage their own reward mechanisms (such as staking rewards) and track "virtual" Karma balances for
@@ -97,7 +113,8 @@ The contract provides separate functions to query actual token balances versus t
97113
## Slashing
98114

99115
The Karma contract includes a slashing mechanism that allows authorized accounts to reduce an account's Karma balance as
100-
a penalty for certain behaviors. This section explains how slashing works and its implications.
116+
a penalty for certain behaviors, through the [RLN Registry](rln.md). This section explains how slashing works and its
117+
implications.
101118

102119
### Overview of Slashing
103120

@@ -188,5 +205,5 @@ increase, even though no token transfers occur until rewards are explicitly rede
188205

189206
## Sources of Karma Tokens
190207

191-
One of the sources for the generation of Karma tokens is the [staking protocol](system-overview.md), with more sources
192-
planned in the future.
208+
One of the sources for the generation of Karma tokens is the
209+
[staking protocol](staking/-reward-distributor/overview.md), with more sources planned in the future.

‎status-network-contracts/docs/reward-distributors.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Reward Distributors
22

3+
## Table of Contents
4+
5+
- [Overview](#overview)
6+
- [Purpose and Design Goals](#purpose-and-design-goals)
7+
- [Virtual vs Actual Karma](#virtual-vs-actual-karma)
8+
- [Redeeming rewards](#redeeming-rewards)
9+
310
## Overview
411

512
Reward distributors are contracts that integrate with the Karma token system to enable flexible and efficient reward
@@ -30,8 +37,8 @@ We refer to "actual" Karma as the ERC-20 tokens that exist in the Karma contract
3037
by actual Karma and can be converted to actual tokens any time. Reward distributors implement their own logic for
3138
determining how virtual rewards accrue to accounts (staking, activity, time-based).
3239

33-
The [staking system](system-overview.md) is one such reward distributor, distributing Karma based on staked SNT and
34-
Multiplier Points (MP).
40+
The [staking system](staking-reward-distributor/overview.md) is one such reward distributor, distributing Karma based on
41+
staked SNT and Multiplier Points (MP).
3542

3643
### Redeeming rewards
3744

‎status-network-contracts/docs/rln.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,21 @@
11
# RLN (Rate-Limiting Nullifier)
22

3+
## Table Of Contents
4+
5+
- [Overview](#overview)
6+
- [Features](#features)
7+
- [Identity Registration](#identity-registration)
8+
- [Registration Process](#registration-process)
9+
- [Identity Commitment Generation](#identity-commitment-generation)
10+
- [Registry Capacity](#registry-capacity)
11+
- [Commit-Reveal Slashing Mechanism](#commit-reveal-slashing-mechanism)
12+
- [Why Commit-Reveal?](#why-commit-reveal)
13+
- [Step 1: Commit Phase](#step-1-commit-phase)
14+
- [Step 2: Reveal Phase](#step-2-reveal-phase)
15+
- [Reveal Window Timing](#reveal-window-timing)
16+
- [Direct Slash (Emergency)](#direct-slash-emergency)
17+
- [Access Control](#access-control)
18+
319
## Overview
420

521
The RLN (Rate-Limiting Nullifier) contract is a privacy-preserving identity registry that manages a set of identity
@@ -39,8 +55,6 @@ Network protocol. commit-reveal scheme that prevents front-running attacks.
3955
- Slashing burns a percentage of the user's total Karma balance (both actual and virtual tokens).
4056
- [Slashing rewards](./karma.md#slashing) are minted to a recipient specified as parameter.
4157

42-
- **Upgradeability**
43-
4458
The contract can be upgraded by users with the ADMIN role.
4559

4660
## Identity Registration

‎status-network-contracts/docs/simple-reward-distributor.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Simple Reward Distributor
2+
3+
## Overview
4+
5+
The `SimpleKarmaDistributor` is a [reward distributor](reward-distributors.md) that enables off-chain services to
6+
distribute Karma tokens based on custom criteria. Unlike the [StakeManager](staking-reward-distributor/overview.md)
7+
which calculates rewards on-chain based on staking positions, this distributor allows operators to mint virtual Karma
8+
rewards for accounts based on conditions verified off-chain.
9+
10+
## Use Cases
11+
12+
This distributor is designed for reward programs where eligibility or reward amounts are determined outside the
13+
blockchain:
14+
15+
- **Proof of Humanity**: Reward verified human users
16+
- **Community Contributions**: Reward forum activity, content creation, or other platform participation
17+
- **Campaign Rewards**: Distribute rewards for completing specific tasks or achievements
18+
- **Off-chain Integrations**: Reward actions from external systems (social media, other chains, etc.)
19+
20+
## How It Works
21+
22+
### Basic Flow
23+
24+
1. **Supply**: The Karma contract supplies the distributor with Karma tokens
25+
2. **Mint**: Operators mint virtual Karma for accounts based on off-chain verification
26+
3. **Redeem**: Users redeem their virtual Karma to receive actual tokens
27+
28+
```
29+
Off-chain Service
30+
|
31+
| Verifies conditions
32+
| (e.g., proof of humanity)
33+
↓
34+
Operator mints virtual Karma
35+
|
36+
↓
37+
Virtual Karma → User redeems → Actual Karma Tokens
38+
```
39+
40+
### Virtual Balance System
41+
42+
Like all reward distributors, this contract tracks "virtual" Karma balances:
43+
44+
- **Virtual Karma**: Tracked internally, fully backed by actual Karma held by the distributor
45+
- **Actual Karma**: ERC-20 tokens received after redemption
46+
- Virtual balances count towards voting power and total supply in the Karma contract
47+
48+
## Supply Management
49+
50+
The contract maintains three supply counters:
51+
52+
- **Available Supply**: Karma that can be minted as virtual rewards
53+
- **Minted Supply**: Virtual Karma that has been allocated but not yet redeemed
54+
- **Redeemed**: Karma that has been converted to actual tokens and transferred to users
55+
56+
Operators cannot mint more than the available supply, ensuring virtual rewards are always backed 1:1 by actual Karma
57+
held by the distributor.

‎status-network-contracts/docs/staking-reward-distributor/emergency-mode.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Emergency Mode
2+
3+
## Table Of Contents
4+
5+
- [Overview](#overview)
6+
- [Key Characteristics](#key-characteristics)
7+
- [One-Way Activation](#one-way-activation)
8+
- [Bypasses All Lock-Ups](#bypasses-all-lock-ups)
9+
- [Minimal Accounting Updates](#minimal-accounting-updates)
10+
- [Restricted Operations](#restricted-operations)
11+
- [When Emergency Mode Is Used](#when-emergency-mode-is-used)
12+
- [Relationship with Leave Mechanism](#relationship-with-leave-mechanism)
13+
14+
## Overview
15+
16+
Emergency mode is a critical safety mechanism built into the staking system that allows users to immediately exit and
17+
recover their funds in exceptional circumstances. When enabled, it bypasses normal operational constraints including
18+
lock-up periods, providing an unconditional exit path for all stakers.
19+
20+
This mechanism exists as a last-resort protection against catastrophic scenarios such as security vulnerabilities,
21+
malicious contract upgrades, or critical system failures.
22+
23+
## Key Characteristics
24+
25+
### One-Way Activation
26+
27+
Emergency mode is **irreversible**. Once enabled by an admin or guardian, it cannot be disabled. This ensures that if
28+
the system is compromised, malicious actors cannot prevent users from exiting by toggling emergency mode off.
29+
30+
### Bypasses All Lock-Ups
31+
32+
Unlike the user's capablity to [leave](leave-mechanism.md) the system, which respects lock-up periods, emergency exit
33+
allows users to withdraw their funds immediately regardless of when their lock period expires. This ensures that users
34+
can always access their funds in a true emergency.
35+
36+
### Minimal Accounting Updates
37+
38+
When users perform an emergency exit, the StakeManager's internal accounting is **not updated**. This design choice
39+
ensures that:
40+
41+
- Users can exit even if the StakeManager is broken or malicious
42+
- Exits cannot be blocked by reverting transactions
43+
- The function remains simple and reliable under all circumstances
44+
45+
The trade-off is that the StakeManager's state becomes stale, but this is acceptable since emergency mode is terminal
46+
for the contract.
47+
48+
### Restricted Operations
49+
50+
Once emergency mode is enabled, most staking operations are blocked to prevent further interactions with a potentially
51+
compromised system. The allowed operations are [formally verified](../../PROPERTIES.md) to ensure user safety.
52+
53+
## When Emergency Mode Is Used
54+
55+
- If a critical security vulnerability is discovered that puts user funds at risk, emergency mode provides an immediate
56+
exit path before the vulnerability can be exploited.
57+
- If the StakeManager is upgraded to a malicious or broken implementation, guardians can enable emergency mode to allow
58+
users to exit before interacting with the compromised contract.
59+
- If the staking system experiences a failure that makes normal operations unsafe or impossible, emergency mode ensures
60+
users can still recover their funds.
61+
62+
## Relationship with Leave Mechanism
63+
64+
Emergency mode is distinct from the normal [leave mechanism](leave-mechanism.md):
65+
66+
| Feature | Leave | Emergency Exit |
67+
| ------------------ | ------------------------------- | -------------------------------- |
68+
| Respects locks | Yes, locked funds stay in vault | No, bypasses all locks |
69+
| Updates accounting | Yes, full accounting update | No, accounting not updated |
70+
| Claims rewards | Yes, transfers accrued rewards | No, only staking tokens |
71+
| When available | Always | Only when emergency mode enabled |
72+
| Purpose | Graceful exit from system | Emergency fund recovery |
73+
74+
Users should use `leave()` for normal exits (or unstake) and `emergencyExit()` only when emergency mode has been
75+
enabled.

0 commit comments

Comments
 (0)