SYSTEM_DESIGN.md

Reputation System Design

Related Documentation:

• API Standards - API endpoints and data formats
• Security - Security considerations for onchain operations
• Operations - Performance requirements and monitoring

Table of Contents

1. Core Concepts
   • Snapshots
     • States
     • Lifecycle
     • Structure
   • Workflows
     • Temporal Integration
     • Search Attributes
     • Workflow Structure
   • Scores
     • Structure
2. Onchain Commitment
   • Process
   • Commitment Process
     • Score Finalization
     • Merkle Tree Generation
     • Onchain Submission
     • Verification
   • Smart Contract Interface
3. Strategy System
   • Versioning
   • Structure
   • Parameter Validation
   • Error Handling
4. Data Flow
   • Snapshot Creation
   • Execution
   • Commitment
   • Verification
   • Workflow Execution
     • Main Workflow
     • Child Workflows
     • Error Recovery
   • Data Storage
     • Workflow Data
     • Score Data
     • Commitment Data

1. Core Concepts

Snapshots

A snapshot represents a configuration for calculating reputation scores at a specific point in time.

States

• draft: Initial state, can be modified and executed multiple times
• committed: A workflow's results have been committed, making the snapshot immutable

Lifecycle

1. Create snapshot in draft state
2. Execute multiple workflows for testing while in draft
3. User selects a specific workflow's results to commit
4. Onchain commitment is made for the selected workflow's results
5. Snapshot becomes committed and immutable
6. No further workflows can be executed for this snapshot

Structure

{
  "id": "snap_123",
  "name": "Q1 2025 Governance Snapshot",
  "status": "draft",
  "created_at": "2025-06-01T12:00:00Z",
  "commit": {
    "workflow_id": null, // ID of the workflow whose results were committed
    "timestamp": null, // When the commitment was made
    "transaction": null, // Transaction ID of the onchain commitment
    "block_number": null, // Block number of the commitment transaction
    "merkle_root": null // Merkle root hash of the committed scores
  },
  "strategies": [
    {
      "strategy": {
        "name": "token-weighted-voting",
        "version": "1.0.0",
        "hash": "0x1234..." // Keccak-256 hash of strategy code
      },
      "weight": 1.0,
      "parameters": {
        "start_block": 0,
        "end_block": 12345678,
        "min_balance": 100
      }
    }
  ]
}

Workflows

The system uses Temporal for workflow management, leveraging its robust workflow engine and state management capabilities. Each snapshot has a single main workflow that orchestrates the execution of child workflows for each strategy.

Temporal Integration

• Workflow states and status are managed by Temporal
• Workflow execution history is stored in Temporal
• Workflow progress and status are tracked by Temporal
• Workflow timeouts and retries are handled by Temporal
• Child workflows execute strategies in parallel
• Only one workflow can be committed per snapshot

Search Attributes

Custom search attributes are used to link workflows with snapshots:

{
  "snapshot_id": "snap_123" // Custom search attribute to link workflow to snapshot
}

The workflow API proxies requests to Temporal, allowing querying of all workflows associated with a snapshot.

Workflow Structure

• Main workflow (snapshot):

  • Orchestrates the execution of child workflows
  • Manages the overall snapshot lifecycle
  • Handles commitment process
  • Tracks progress of all strategies

• Child workflows (strategies):

  • Execute individual strategy calculations
  • Run in parallel for better performance
  • Report progress to parent workflow
  • Handle strategy-specific errors

Each snapshot can have multiple workflow executions while in draft state. Once a workflow's results are committed, the snapshot becomes immutable and no further workflows can be executed.

Scores

Scores represent the calculated reputation values for subjects, tied to specific workflow executions.

Structure

{
  "workflow_id": "work_123",
  "snapshot_id": "snap_123",
  "sub_id": "0x123...",
  "strategy_scores": [
    {
      "strategy": {
        "name": "token-weighted-voting",
        "version": "1.0.0",
        "hash": "0x1234..."
      },
      "score": 85.0,
      "rank": 42,
      "child_workflow_id": "work_124" // ID of the strategy's child workflow
    }
  ],
  "weighted_score": 87.1,
  "weighted_rank": 35,
  "calculated_at": "2025-06-01T12:00:00Z"
}

2. Onchain Commitment

Process

1. Calculate final scores for all subjects
2. Generate Merkle tree of scores
3. Submit root hash to smart contract
4. Verify onchain commitment
5. Update snapshot status to committed

Commitment Process

1. Score Finalization

   • All child workflows must complete successfully
   • Scores are aggregated and weighted
   • Final scores are sorted and ranked

2. Merkle Tree Generation

   • Each subject's score is hashed
   • Leaves are sorted by subject ID
   • Tree is built bottom-up
   • Root hash is generated

3. Onchain Submission

   • Root hash is submitted to smart contract
   • Transaction is monitored for confirmation
   • Commitment is verified onchain

4. Verification

   • Merkle proofs can be generated for any score
   • Proofs are verified against onchain root
   • Historical commitments are preserved

Smart Contract Interface

interface IReputationSystem {
    function commitSnapshot(
        bytes32 snapshotId,
        bytes32 merkleRoot,
        uint256 blockNumber
    ) external;

    function verifyScore(
        bytes32 snapshotId,
        address subject,
        uint256 score,
        bytes32[] calldata proof
    ) external view returns (bool);
}

3. Strategy System

Versioning

• Semantic versioning (MAJOR.MINOR.PATCH)
• Code hashing using Keccak-256
• Version registry in smart contract

Structure

{
  "name": "token-weighted-voting",
  "version": "1.0.0",
  "hash": "0x1234...",
  "parameters": {
    "start_block": "uint256",
    "end_block": "uint256",
    "min_balance": "uint256"
  }
}

Parameter Validation

• Parameters are validated against strategy schema
• Type checking is enforced
• Range validation for numeric parameters
• Required parameters must be provided
• Default values are applied when appropriate

Error Handling

• Strategy execution errors are captured
• Failed strategies are retried automatically
• Maximum retry attempts are configurable
• Error details are logged for debugging
• Parent workflow is notified of failures

4. Data Flow

1. Snapshot Creation

   • User creates snapshot with strategies
   • System validates configuration
   • Snapshot stored in draft state

2. Execution

   • User triggers execution
   • System creates workflow
   • Strategies execute in parallel
   • Progress tracked per strategy
   • Scores calculated and stored

3. Commitment

   • User reviews results
   • System generates Merkle tree
   • Root hash committed onchain
   • Snapshot becomes immutable

4. Verification

   • Anyone can verify scores
   • Merkle proofs generated on demand
   • Smart contract verifies proofs

Workflow Execution

1. Main Workflow

   • Validates snapshot configuration
   • Creates child workflows for strategies
   • Monitors child workflow progress
   • Aggregates results
   • Handles commitment process

2. Child Workflows

   • Execute strategy calculations
   • Report progress to parent
   • Handle retries on failure
   • Store intermediate results
   • Clean up temporary data

3. Error Recovery

   • Automatic retries for transient failures
   • Manual intervention for persistent issues
   • Error reporting and logging
   • State recovery mechanisms

Data Storage

1. Workflow Data

   • Stored in Temporal
   • Includes execution history
   • Contains progress information
   • Preserves error details

2. Score Data

   • Stored in database
   • Indexed by snapshot and subject
   • Includes Merkle proof data
   • Preserves historical records

3. Commitment Data

   • Stored onchain
   • Includes Merkle roots
   • Preserves transaction details
   • Enables verification