Solana Smart Legal Contracts (SLC)

This repository contains a Solana blockchain project implementing Smart Legal Contracts (SLC) - a system that combines smart contracts with legal contracts to enable dispute enforcement through defined legal instructions and a set of relied-on parties (neutrals and executors).

Key Components

1. SLC Core Program: This program holds the essential functions for a user to initialize and interact with an SLC.

   • Manages the creation and execution of smart legal contracts
   • Handles service requests and executions
   • Interacts with the SLC governance program for service requests

2. SLC Governance Program: This program holds all enabling components and functions that make SLCs possible.

   • Manages neutral judgment and executor enforcement
   • Handles staking and delegation mechanisms
   • Implements decision-making processes
   • Manages reward distribution

3. SLC Shared Module

   • Handles cross-program invocation (CPI)
   • Contains common constants and types

Key SLC Service Request Flows

After a Service Request is created, it passes different stages, as indicated by it's status. The different processes that take place along the way are visualized below in more detail.

Status Flow

stateDiagram-v2
    [*] --> Pending
    Pending --> Approved: When operation gets sufficient neutral approvals
    Approved --> PendingExecution: When operation is ready for execution
    PendingExecution --> Executed: After execute_service is called
    Executed --> RewardsDistributed: After distribute_rewards is called

Service Request Creation

sequenceDiagram
    participant User as User/Client
    participant SLC as SLC Program
    participant Governance as SLC Governance Program
    participant Neutrals as Random Neutrals

    User->>SLC: request_service(additional_info, system_nonce, service_fee, neutrals_number)
    SLC->>SLC: Validate request parameters
    SLC->>Governance: create_decision_module_cpi(...)
    Governance->>Governance: Select random neutrals using slot hashes as randomness seed
    Governance->>Governance: Initialize DecisionState with Status::Pending
    Governance->>Governance: Calculate neutrals_threshold (2/3 of selected neutrals)
    Governance->>Governance: Calculate executors_threshold (50% + 1 of executors)
    SLC->>SLC: Increment decision_instances_nonce
    SLC->>SLC: Emit ServiceRequested event
    Note over User, Neutrals: Decision module created for service request

Neutral Judgement Flow

sequenceDiagram
    participant Neutral as Neutral Signer
    participant Governance as SLC Governance Program
    participant Decision as DecisionState (Status::Pending)
    participant NeutralDecision as NeutralDecisionState
    participant Operation as OperationState

    Neutral->>Governance: approve_operation(system_nonce, decision_instance_nonce, operation_nonce)
    Governance->>Governance: Validate neutral is in selected_neutrals
    Governance->>Governance: Validate decision status is Pending
    Governance->>Operation: Increment neutrals_approvals
    
    alt Neutral had previously approved a different operation
        Governance->>Governance: Decrement previous operation's neutrals_approvals
    end
    
    Governance->>NeutralDecision: Update operation reference
    
    Note over Neutral, Operation: Neutral's approval recorded for the operation

Service Execution Flow

sequenceDiagram
    participant Executor as Executor
    participant Governance as SLC Governance Program
    participant SLC as SLC Program
    participant Accounts as Target Accounts

    Executor->>Governance: review_decision(system_nonce, decision_instance_nonce, operation_nonce, decision)
    
    Note over Governance: Account Validations:
    Note over Governance: 1. Check executor_info.is_active
    Note over Governance: 2. Verify decision_state.status is Pending or Approved
    Note over Governance: 3. Verify operation_state.neutrals_approvals >= neutrals_threshold
    Note over Governance: 4. Check executor_decision_state.decision is None
    
    Governance->>Governance: Record executor's review
    Governance->>Governance: Update operation_state.executors_yes/no
    
    alt executors_yes >= executors_threshold
        Governance->>Governance: Set status to PendingExecution
        Governance->>SLC: execute_service_cpi(
        
        SLC->>SLC: Verify decision_state is signer
        SLC->>SLC: Create PDA seeds for core_state
        
        loop For each instruction in instruction_data
            SLC->>Accounts: invoke_signed(instruction, accounts, seeds)
        end
        
        SLC-->>Governance: Return execution result
        Governance->>Governance: Set status to Executed
        Governance->>Governance: Emit OperationExecuted event
    else executors_no >= executors_threshold
        Governance->>Governance: Increment operation_cycle
    end
    
    Note over Executor, Accounts: Service execution is triggered by the last executor review when sufficient approvals are reached

Rewards Distribution Flow

flowchart TD
    A[Start: Distribute Rewards] --> B{Check Decision Status}
    B -->|Status::Executed| C[Set Status to RewardsDistributed]
    B -->|Other Status| X[Error: InvalidStatus]
    
    C --> D[Calculate Reward Distributions]
    D --> E[executors_reward_amount]
    D --> F[neutrals_reward_amount]
    D --> G[dao_reward_amount]
    
    E --> H[Update Executors Reward Pool]
    F --> I[For each selected neutral]
    G --> J[Send to DAO Treasury]
    
    I --> K[Find Neutral Reward Pool]
    K --> L[Update Neutral Reward Pool]
    L --> M[Distribute rewards to neutral and delegators]
    
    M --> N[Neutral's Portion]
    M --> O[Delegators' Portion based on shares]
    
    N --> P["Claim by Neutral: claim_neutral_reward()"]
    O --> Q["Claim by Delegator: claim_delegator_reward()"]
    H --> R["Claim by Executor: claim_executor_reward()"]
    
    P --> S[End: All Rewards Distributed]
    Q --> S
    R --> S
    J --> S

Slashing Flow

sequenceDiagram
    participant User
    participant DAO SLC Core
    participant SLC Program
    participant SLC Governance
    participant Neutrals
    participant Executors

    User->>DAO SLC Core: Request Slashing
    DAO SLC Core->>SLC Program: Handle request
    Note over SLC Program: Validate request parameters
    SLC Program->>SLC Governance: Create Decision Module
    Note over SLC Governance: Select random neutrals using slot hashes
    Note over SLC Governance: Initialize DecisionState (Status::Pending)
    Note over SLC Governance: Calculate thresholds (2/3 neutrals, 50%+1 executors)
    SLC Program->>SLC Program: Increment decision_instances_nonce

    loop For each selected Neutral
        Neutrals->>SLC Governance: Create Neutral Decision State
        Neutrals->>SLC Governance: Create Operation
        Note over SLC Governance: Initialize OperationState with slashing instruction data
        Neutrals->>SLC Governance: Approve Operation
        Note over SLC Governance: Increment neutrals_approvals
        Note over SLC Governance: Update NeutralDecisionState.operation
    end

    Note over SLC Governance: Check if neutrals_approvals >= neutrals_threshold
    Note over SLC Governance: Update DecisionState.status to Approved

    loop For majority of Executors
        Executors->>SLC Governance: Create Executor Decision State
        Executors->>SLC Governance: Review Decision (true)
        Note over SLC Governance: Increment executors_yes
    end

    Note over SLC Governance: Check if executors_yes >= executors_threshold
    Note over SLC Governance: Update DecisionState.status to PendingExecution

    SLC Governance->>DAO SLC Core: Verify DAO SLC Core (nonce 0)
    Note over SLC Governance: Execute slashing operation

    alt Executor Slashing
        Note over SLC Governance: Verify slashing amount <= executor's self_stake
        Note over SLC Governance: Reduce executor's self_stake
        Note over SLC Governance: Remove reward shares
        Note over SLC Governance: If self_stake < min_stake: Remove from executors list
    else Neutral Slashing
        Note over SLC Governance: Verify slashing amount <= neutral's self_stake
        Note over SLC Governance: Reduce neutral's self_stake
        Note over SLC Governance: If self_stake < min_stake: Remove from neutrals list
        Note over SLC Governance: Transfer tokens to slashing_recipient
    end

    Note over SLC Governance: Update DecisionState.status to Executed
    Note over SLC Governance: Distribute rewards to neutrals and executors
    Note over SLC Governance: Update DecisionState.rewards_distributed = true

Executor Approval Flow

    sequenceDiagram
    participant User
    participant DAO SLC Core
    participant SLC Program
    participant SLC Governance
    participant Neutrals
    participant Executors

    User->>DAO SLC Core: Request Approval for Executor
    DAO SLC Core->>SLC Program: Handle request
    Note over SLC Program: Validate request parameters
    SLC Program->>SLC Governance: Create Decision Module
    Note over SLC Governance: Select random neutrals using slot hashes
    Note over SLC Governance: Initialize DecisionState (Status::Pending)
    Note over SLC Governance: Calculate thresholds (2/3 neutrals, 50%+1 executors)
    SLC Program->>SLC Program: Increment decision_instances_nonce

    loop For each selected Neutral
        Neutrals->>SLC Governance: Create Neutral Decision State
        Neutrals->>SLC Governance: Create Operation
        Note over SLC Governance: Initialize OperationState with instruction data
        Neutrals->>SLC Governance: Approve Operation
        Note over SLC Governance: Increment neutrals_approvals
        Note over SLC Governance: Update NeutralDecisionState.operation
    end

    Note over SLC Governance: Check if neutrals_approvals >= neutrals_threshold
    Note over SLC Governance: Update DecisionState.status to Approved

    loop For majority of Executors
        Executors->>SLC Governance: Create Executor Decision State
        Executors->>SLC Governance: Review Decision (true)
        Note over SLC Governance: Increment executors_yes
    end

    Note over SLC Governance: Check if executors_yes >= executors_threshold
    Note over SLC Governance: Update DecisionState.status to PendingExecution

    SLC Governance->>DAO SLC Core: Verify DAO SLC Core
    Note over SLC Governance: Execute operation instructions
    Note over SLC Governance: Update DecisionState.status to Executed

    Note over SLC Governance: Distribute rewards to neutrals and executors
    Note over SLC Governance: Update DecisionState.rewards_distributed = true