Solidus Protocol Specification

Version: 1.0.0-draft Status: Draft Date: 2026-03-11 Authors: Solidus Core Team

Table of Contents

1. Introduction
2. Cryptographic Primitives
3. DID Method Specification
4. Verifiable Credentials
5. Verification Protocol
6. Zero-Knowledge Proofs
7. Consensus: HotStuff-Inspired BFT with Identity-Anchored Validators
8. Programmability and State
9. Authentication SDK
10. Network Layer
11. Governance: Solidus Improvement Proposals
12. Fee Schedule
13. Security Considerations

1. Introduction

Solidus is a decentralized identity and verifiable credentials protocol. It provides a trust layer for the internet by combining decentralized identifiers (DIDs), W3C-compliant verifiable credentials, zero-knowledge proofs, and a purpose-built Layer 1 blockchain running a HotStuff-inspired Byzantine Fault Tolerant (BFT) consensus engine whose validator set is anchored to verified human identity (the “Proof of Identity” eligibility model).

The protocol enables applications to verify claims about users — age, profession, location, reputation — without exposing the underlying personal data. Developers interact with Solidus through an SDK that behaves identically to conventional authentication providers such as Firebase Auth or Auth0, while the underlying verification is decentralized and privacy-preserving.

1.1 Design Principles

• Self-sovereignty. Users own and control their identity. No central authority can revoke access to a DID.
• Privacy by default. Selective disclosure and zero-knowledge proofs ensure that only the minimum necessary information is revealed.
• Developer ergonomics. The Auth SDK abstracts all protocol complexity behind familiar login() / verifyToken() interfaces.
• Sybil resistance. The identity-anchored validator model (“Proof of Identity”) ties validator eligibility to verified human identity, preventing stake-grinding and bot-driven attacks.
• Deterministic finality. The HotStuff-inspired BFT engine reaches finality via a 3-chain commit rule; blocks and verification results finalize in under two seconds.

1.2 Terminology

2. Cryptographic Primitives

All cryptographic operations in Solidus are built on the following primitives. Algorithm choices are immutable and cannot be changed through governance.

2.1 Digital Signatures

Algorithm: Ed25519 (RFC 8032)

Ed25519 is the primary signature scheme. All DID operations, credential issuance, and validator attestations use Ed25519 signatures. The scheme provides 128-bit security, fast verification, and deterministic signing.

2.2 Encryption

Algorithm: Curve25519-XSalsa20-Poly1305 (NaCl crypto_box)

Used for encrypted peer-to-peer communication between DID controllers and for encrypting credential payloads in transit.

2.3 Hashing

Algorithm: BLAKE3

BLAKE3 is the primary hash function for address derivation, Merkle trees, and content addressing. BLAKE3 supersedes BLAKE2b with significantly higher throughput and a simpler design. Where interoperability with external systems requires it, SHA-256 is used as a secondary hash (notably in commitment schemes and credential hash registration).

Address derivation uses HASH160, defined as:

HASH160(data) = RIPEMD-160(BLAKE3-256(data))

2.4 Selective Disclosure & Zero-Knowledge Proof Systems

2.5 Commitment Schemes

• Pedersen commitments for hiding values in ZK circuits.
• SHA-256 commitments for credential hash registration on-chain.

2.6 Key Derivation

Solidus uses hierarchical deterministic key derivation following established standards:

1. Generate a BIP39 mnemonic (12 or 24 words).
2. Derive a BIP32 master key from the mnemonic seed.
3. Derive child keys for distinct DIDs, each at a unique derivation path.

mnemonic (BIP39)
    |
    v
master_seed (PBKDF2)
    |
    v
master_key (BIP32)
   / \
  v   v
DID_0  DID_1  ...  (child derivation paths)

2.7 Key Rotation

Key rotation allows a DID controller to replace their active key pair without changing their DID.

1. Generate a new Ed25519 key pair.
2. Sign a key rotation transaction with the current (old) key.
3. Submit the rotation transaction to the network.
4. A 7-day grace period begins. During this period, both old and new keys are valid.
5. After the grace period, the old key is deactivated.

The grace period protects against accidental lockout and allows services to update cached key material.

2.8 Social Recovery

If a user loses access to their keys, social recovery provides a non-custodial fallback.

• The user designates N guardians (other DIDs) during setup.
• The master key is split using Shamir Secret Sharing into N shares.
• Recovery requires M-of-N guardians to submit their shares.
• The reconstructed key is used to perform a key rotation to a new key pair.

The threshold M and total N are chosen by the user. A typical configuration is 3-of-5.

3. DID Method Specification

3.1 Method Name

The Solidus DID method uses the method name solidus. It is currently under W3C DID Method Registry review (first approval received) — not yet merged; we never describe it as “registered.”

3.2 DID Syntax

did:solidus:<network>:<identifier>

Identifier derivation:

identifier = Base58(HASH160(Ed25519_public_key))

Where HASH160 is defined in Section 2.3.

Example DID (mainnet):

did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs

Example DID (testnet):

did:solidus:testnet:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs

3.3 DID Document

A resolved DID document conforms to the W3C DID Core specification and contains the following sections.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://solidus.network/ns/did/v1"
  ],
  "id": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
  "controller": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
  "verificationMethod": [
    {
      "id": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
      "publicKeyMultibase": "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    }
  ],
  "authentication": [
    "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs#key-1"
  ],
  "assertionMethod": [
    "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs#key-1"
  ],
  "service": [
    {
      "id": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs#solid-pod",
      "type": "SolidPod",
      "serviceEndpoint": "https://pod.solidus.network/5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs"
    }
  ]
}

3.4 DID Operations

3.4.1 Create

Register a new DID on the Solidus network.

• Fee: 0.001 SLDS
• Input: Ed25519 public key, optional service endpoints, signed transaction.
• Process: The network computes the identifier from the public key, constructs the initial DID document, and stores it on-chain.
• Idempotency: Creating a DID that already exists is rejected.

3.4.2 Update

Modify a DID document (add/remove keys, update service endpoints).

• Fee: 0.0001 SLDS
• Authorization: The transaction must be signed by a key listed in the document’s authentication array.
• Scope: Any field in the DID document may be updated except the id.

3.4.3 Deactivate

Permanently deactivate a DID. This operation is irreversible.

• Fee: 0.0001 SLDS
• Authorization: Signed by an authentication key.
• Effect: The DID document is marked as deactivated. Resolution returns the document with deactivated: true in metadata. The DID can never be reactivated or reassigned.

3.5 DID Resolution

DIDs are resolved via a RESTful endpoint.

Request:

GET /1.0/identifiers/did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs
Accept: application/did+ld+json

Response:

{
  "didDocument": {
    "@context": ["https://www.w3.org/ns/did/v1"],
    "id": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
    "verificationMethod": ["..."],
    "authentication": ["..."],
    "assertionMethod": ["..."],
    "service": ["..."]
  },
  "didDocumentMetadata": {
    "created": "2026-01-15T10:30:00Z",
    "updated": "2026-02-20T14:22:00Z",
    "deactivated": false,
    "versionId": "3",
    "nextUpdate": "",
    "equivalentId": []
  },
  "didResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "duration": 42,
    "retrieved": "2026-03-11T08:00:00Z"
  }
}

4. Verifiable Credentials

Solidus implements W3C Verifiable Credentials Data Model v2.0 with protocol-specific extensions for on-chain registration, multi-signature issuance, and zero-knowledge selective disclosure.

4.1 Credential Types

4.2 Credential Schema

A Solidus verifiable credential follows the W3C VC structure with additional fields for multi-validator issuance and on-chain anchoring.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://solidus.network/ns/credentials/v1"
  ],
  "id": "urn:solidus:credential:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": ["VerifiableCredential", "KYCCredential"],
  "issuer": {
    "id": "did:solidus:1:validatorSetMultisig",
    "name": "Solidus Validator Consortium"
  },
  "issuanceDate": "2026-03-01T12:00:00Z",
  "expirationDate": "2027-03-01T12:00:00Z",
  "credentialSubject": {
    "id": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
    "kycLevel": 2,
    "verifiedAttributes": ["name", "dateOfBirth", "governmentId", "address"],
    "jurisdiction": "US"
  },
  "credentialStatus": {
    "id": "https://solidus.network/revocation/list/42#94567",
    "type": "RevocationList2020Status",
    "revocationListIndex": "94567",
    "revocationListCredential": "https://solidus.network/revocation/list/42"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-03-01T12:00:00Z",
    "verificationMethod": "did:solidus:1:validatorSetMultisig#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic76UMkqESTgrlCHjMGTow..."
  },
  "solidusExtensions": {
    "onChainHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
    "validatorSignatures": [
      {
        "validator": "did:solidus:1:validator1addr",
        "signature": "z3hY7k..."
      },
      {
        "validator": "did:solidus:1:validator2addr",
        "signature": "z9pQ2m..."
      }
    ],
    "consensusRound": 148203
  }
}

4.3 Issuance Flow

Credential issuance follows a multi-validator consensus process:

1. Request. The user (credential subject) submits a credential request to the network, specifying the desired credential type and providing supporting evidence.

2. Validator selection. The network selects a validator set for the request using VRF (see Section 7).

3. Verification. Each selected validator independently verifies the submitted evidence against the requirements for the credential type.

4. Consensus. Validators submit their attestations. A 2/3 supermajority (14 of 21 validators) must agree that the evidence is valid.

5. Issuance. Upon reaching consensus, a multi-signature credential is constructed. The credential is signed by the validator consortium key.

6. Delivery. The issued credential is delivered to the user’s SolidPod.

7. On-chain registration. A SHA-256 hash of the credential is registered on-chain, providing a tamper-evident anchor without storing personal data on the ledger.

4.4 Revocation

Solidus uses the RevocationList2020 scheme for credential revocation.

• Each revocation list is a compressed bitstring stored on-chain.
• Each credential references a specific index within a revocation list.
• To revoke a credential, the issuer (or governance action) sets the corresponding bit.
• Verifiers check the revocation list during credential validation.
• Revocation is permanent. A revoked credential cannot be un-revoked.

The bitstring is compressed using zlib deflation to minimize on-chain storage. A single revocation list supports up to 131,072 credentials (16 KiB bitfield).

5. Verification Protocol

The verification protocol defines how a relying party requests and receives proof of claims about a subject.

5.1 Verification Request

A relying party constructs a verification request specifying the claims it needs.

{
  "version": "1.0",
  "requestId": "req-7f8e9d0c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "timestamp": "2026-03-11T10:00:00Z",
  "requester": {
    "did": "did:solidus:1:appServiceDid123",
    "purpose": "Age-gated content access"
  },
  "subject": {
    "did": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs"
  },
  "requiredClaims": [
    {
      "type": "AgeVerificationCredential",
      "constraints": {
        "minimumAge": 18
      },
      "acceptZKProof": true
    },
    {
      "type": "EmailVerificationCredential",
      "constraints": {},
      "acceptZKProof": false
    }
  ],
  "signature": "z3hY7kLmNpQrStUvWxYz...",
  "fee": "0.005"
}

5.2 Verification Response

{
  "version": "1.0",
  "requestId": "req-7f8e9d0c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "timestamp": "2026-03-11T10:00:01Z",
  "verified": true,
  "claims": [
    {
      "type": "AgeVerificationCredential",
      "satisfied": true,
      "issuer": "did:solidus:1:validatorSetMultisig",
      "issuanceDate": "2026-02-15T08:00:00Z",
      "expirationDate": "2027-02-15T08:00:00Z",
      "proofType": "zk-snark",
      "zkProofReference": "0xabc123..."
    },
    {
      "type": "EmailVerificationCredential",
      "satisfied": true,
      "issuer": "did:solidus:1:validatorSetMultisig",
      "issuanceDate": "2026-01-10T12:00:00Z",
      "expirationDate": "2027-01-10T12:00:00Z",
      "proofType": "direct"
    }
  ],
  "validatorSignatures": [
    {
      "validator": "did:solidus:1:validator1addr",
      "signature": "z9pQ2m..."
    },
    {
      "validator": "did:solidus:1:validator2addr",
      "signature": "zKw4Rx..."
    }
  ],
  "consensusProof": {
    "totalValidators": 21,
    "agreedValidators": 19,
    "threshold": 14,
    "roundId": 148210
  }
}

5.3 Verification Algorithm

The verification algorithm is executed independently by each selected validator:

VERIFY(request):
  1. Parse the verification request.
  2. Validate the requester's signature and fee payment.
  3. Resolve the subject's DID document.
  4. For each required claim in request.requiredClaims:
     a. Retrieve the relevant credential from the subject's SolidPod
        or from on-chain references.
     b. Verify the credential signature against the issuer's DID document.
     c. Check that the credential has not expired (current time < expirationDate).
     d. Query the revocation registry; reject if the credential's bit is set.
     e. Evaluate constraint satisfaction:
        - If acceptZKProof is true, verify the ZK proof against public inputs.
        - If acceptZKProof is false, verify claim values directly.
     f. Record the claim result (satisfied or unsatisfied) with metadata.
  5. Aggregate per-claim results into a final verified boolean.
     - verified = true only if ALL required claims are satisfied.
  6. Sign the verification result.
  7. Submit the signed result to the consensus round.

After all validators have submitted, the network aggregates results. If at least 14 of 21 validators agree on the outcome, the consensus proof is constructed and the response is returned to the requester.

6. Zero-Knowledge Proofs (Roadmap)

Zero-knowledge proofs allow a subject to prove a claim is true without revealing the underlying data. Solidus selective-disclosure today uses BBS+ signatures (live on testnet); the Groth16-based predicate-proof circuits described in this section are roadmap, not yet shipped.

6.1 Age Verification (ZK-SNARK, Roadmap)

The age verification circuit proves that a subject’s age exceeds a threshold without revealing the actual date of birth.

Circuit definition (Groth16):

Public inputs:

• commitment: Pedersen commitment to the birthdate.
• ageThreshold: The minimum age required (e.g., 18).
• currentDate: The date at which the proof is generated.

Private inputs (witness):

• birthdate: The actual date of birth.
• randomness: The blinding factor used in the Pedersen commitment.

Constraints:

1. Pedersen(birthdate, randomness) == commitment
2. currentDate - birthdate >= ageThreshold * 365.25 days
3. birthdate is a valid calendar date

The verifier checks the proof against the public inputs. If the proof is valid, the subject’s age meets the threshold. The verifier never learns the actual birthdate.

6.2 Location Verification (ZK-SNARK)

The location verification circuit proves that a subject is within a defined geographic region without revealing their exact coordinates.

Public inputs:

• commitment: Pedersen commitment to the coordinates.
• regionPolygon: A set of vertices defining the accepted geographic region.

Private inputs (witness):

• latitude: Actual latitude.
• longitude: Actual longitude.
• randomness: Blinding factor.

Constraints:

1. Pedersen((latitude, longitude), randomness) == commitment
2. point_in_polygon((latitude, longitude), regionPolygon) == true

6.3 BLS Signature Aggregation (shipped in consensus)

Validators hold a BLS12-381 key alongside their Ed25519 identity key and sign their consensus votes with it. When a 2/3 supermajority votes for a block, the individual BLS signatures are aggregated (Boneh-Lynn-Shacham) into a single compact multi-signature — the quorum certificate (§7.4). This is live on testnet and is the core of the consensus engine, not roadmap; it also reduces on-chain storage and verification cost wherever multi-validator attestations are recorded.

An aggregated signature from 14 validators is verified in constant time, regardless of the number of signers.

6.4 Bulletproofs for Range Proofs

Bulletproofs are used for general-purpose range proofs where a full ZK-SNARK circuit would be excessive. Typical uses include:

• Proving a reputation score is above a threshold.
• Proving an account balance exceeds a minimum without revealing the exact balance.
• Proving a credential was issued within a date range.

Bulletproofs require no trusted setup, unlike Groth16 SNARKs.

7. Consensus: HotStuff-Inspired BFT with Identity-Anchored Validators

The Solidus network runs a HotStuff-inspired Byzantine Fault Tolerant (BFT) consensus engine, built from first principles in Rust — a purpose-built Layer 1, not a fork of any existing chain. Layered on top is the “Proof of Identity” (PoI) validator-eligibility model, which roots Sybil resistance in verified human identity. PoI is not a separate consensus algorithm; it governs who may validate, while the BFT engine governs how blocks are agreed.

7.1 Properties

7.2 Validator Eligibility

Solidus uses stake-weighted validator tiers. Each tier has a different minimum stake and recommended hardware; all tiers run the same full node and participate in consensus — the tier sets stake weight, not a different consensus role.

All tiers require:

The KYC requirement ensures that each validator corresponds to a unique verified human. This prevents a single entity from running multiple validators (Sybil attack) regardless of capital.

Note on uptime: The 95% minimum (≈36 hours/month tolerance) applies to decentralized validator nodes. Solidus-operated infrastructure (auth gateway, API endpoints) targets a 99.5% SLO, but this is a service-level commitment for centralized infrastructure, not a decentralized network requirement.

7.3 Validator Selection

For each verification request or block proposal, a committee of 21 validators is selected from the eligible validator pool of up to 100 validators per subnet. The 21-validator committee is the per-round active committee; the 100-validator cap is the maximum eligible pool per subnet from which committee members are drawn.

Selection mechanism: Verifiable Random Function (VRF).

Each eligible validator evaluates the VRF using their private key and the current round seed. The 21 validators with the lowest VRF outputs are selected. The VRF output serves as a cryptographic proof of selection that any observer can verify.

vrf_output, vrf_proof = VRF_evaluate(validator_private_key, round_seed)
selected = (vrf_output < selection_threshold)

The round seed is derived from the previous block hash, ensuring unpredictability.

7.4 BFT Consensus Algorithm

The consensus engine is HotStuff-inspired: a leader-based protocol with BLS-aggregated votes, quorum certificates (QCs), and a 3-chain commit rule for deterministic finality.

PROPOSE
  - The round leader (selected by VRF, see 7.3) speculatively executes
    the block's transactions, commits to the resulting state root in the
    header, and broadcasts the proposal (carrying the parent QC).

VOTE
  - Each committee validator re-executes the block, verifies the state
    root and the leader's VRF proof, checks the locked-QC safety rule,
    then broadcasts a BLS-signed vote on the block hash.

QUORUM CERTIFICATE (QC)
  - When a validator collects votes from a 2/3 supermajority (14 of 21),
    it aggregates the BLS signatures into a single QC certifying the block.
    The QC becomes the parent QC for the next round, forming a chain.

3-CHAIN COMMIT
  - A block is finalized once it is extended by a chain of QCs two rounds
    deep (round + 2 ≤ highest certified round). On commit the block and
    its receipts are persisted and finality is irreversible.

View changes (pacemaker): If a round does not produce a QC within the pacemaker timeout, validators broadcast BLS-signed timeout votes; a 2/3 quorum of these forms a Timeout Certificate (TC) that advances the view to the next leader in VRF order. The pacemaker uses exponential backoff on the timeout to recover liveness under bad networks.

7.5 Slashing Conditions

Validators that violate protocol rules are penalized by slashing a percentage of their staked SLDS.

Slashed fund distribution:

• 50% of slashed SLDS is burned (removed from total supply).
• 50% is awarded to the reporter who submitted the slashing evidence.

7.6 Consensus Threshold

The 2/3 supermajority (14 of 21) threshold applies to all consensus decisions:

• Block finalization.
• Verification result agreement.
• Credential issuance agreement.

This threshold ensures safety under the assumption that fewer than 1/3 of the committee is Byzantine.

8. Programmability and State

8.1 State Model (shipped)

Solidus today has no general-purpose contract VM. State transitions are native and typed: the protocol ships a fixed set of transaction payloads — Transfer, DID operations (DidCreate/DidUpdate/DidDeactivate), credential operations (CredentialIssue, BBS+ issuance, revocation), and staking (Stake/Unstake) — each dispatched to a dedicated Rust handler. There is no untrusted bytecode in the consensus-critical path.

The world state is a Sparse Merkle Tree (SMT) keyed by BLAKE3, persisted over RocksDB (multiple column families: accounts, committed accounts, DIDs, credentials, blocks, receipts, Merkle nodes, staking, and more). Each block commits to the post-execution SMT root in its header; validators re-execute and verify the root before voting. Execution is currently a deterministic serial loop; parallel execution (Block-STM) is on the performance roadmap.

8.2 Programmability roadmap (EVM via subnet)

General-purpose smart contracts are delivered on the roadmap as an EVM subnet (REVM execution engine) that shares the L1 validator set under an Avalanche-style subnet pattern — not a WASM VM bolted onto the L1, and not an EVM on the base layer. The L1 hot path stays untouched by contract bytecode; identity primitives are exposed to Solidity through precompiles that verify inclusion proofs against the L1’s finalized DID/credential roots. The remainder of this section (§8.3–§8.5) describes the roadmap programmability surface; it is design intent, not shipped behavior.

8.3 Identity Host Functions (roadmap)

The contract runtime exposes identity-aware host functions (EVM precompiles in the subnet model). These allow contracts to verify claims about transaction participants without accessing the underlying credential documents.

Data isolation principle: Contracts receive vc_hash, issuer_did, schema_id, and zk_proof_reference. They never receive the full credential document, the subject’s personal data, or any information beyond what is needed to evaluate the claim.

8.4 Gas Metering (roadmap)

In the EVM subnet, execution is metered in gas: each opcode and precompile call has a predefined cost, and the total consumed by a call must not exceed the sender’s gas limit. Identity precompiles cost more than basic opcodes to reflect the inclusion-proof verification and state lookups they require.

8.5 Example: Access Control by Credential (roadmap)

The following illustrative contract — written against the roadmap identity-precompile surface — restricts a function to holders of a valid doctor license credential:

use solidus_sdk::prelude::*;
 
#[solidus_contract]
impl MedicalRecords {
    /// Only callable by a DID that holds a valid doctor_license credential.
    #[access_control]
    pub fn view_patient_record(&self, patient_id: PatientId) -> Result<Record, Error> {
        // The #[access_control] macro expands to:
        //   if !ctx.has_claim("doctor_license_valid") {
        //       return Err(Error::Unauthorized);
        //   }
 
        let record = self.storage.get(&patient_id)?;
        Ok(record)
    }
 
    /// Manual claim check example (without macro).
    pub fn prescribe_medication(
        &self,
        ctx: &Context,
        patient_id: PatientId,
        medication: Medication,
    ) -> Result<PrescriptionId, Error> {
        if !ctx.has_claim("doctor_license_valid") {
            return Err(Error::Unauthorized("Valid doctor license required"));
        }
        if !ctx.has_claim("prescribing_authority") {
            return Err(Error::Unauthorized("Prescribing authority required"));
        }
 
        let prescription = Prescription::new(patient_id, medication, ctx.sender_did());
        self.storage.insert(prescription.id(), &prescription)?;
        Ok(prescription.id())
    }
}

8.6 EVM Subnet (roadmap)

Programmability is delivered as a dedicated EVM subnet (REVM execution engine) sharing the L1 validator set — the primary smart-contract surface, not a side-executor on the base layer. Solidity contracts deploy with standard ETH-style tooling (MetaMask, ethers, Hardhat, Foundry); identity host functions are exposed as EVM precompiles that verify inclusion proofs against the L1’s finalized DID/credential roots. The L1 itself runs no contract bytecode, preserving its latency and audit surface.

9. Authentication SDK

The Solidus Auth SDK provides application developers with a familiar authentication interface. From the developer’s perspective, it works identically to Firebase Auth or Auth0: call login(), receive a JWT, and use verifyToken() on the backend.

9.1 Authentication Flow

+--------+        +---------+       +------------+       +----------+
|  App   |        | Wallet  |       | Auth Bridge|       | Solidus  |
|        |        |         |       | Gateway    |       | Network  |
+---+----+        +----+----+       +-----+------+       +----+-----+
    |                  |                  |                    |
    | 1. login({       |                  |                    |
    |  requiredClaims})|                  |                    |
    |----------------->|                  |                    |
    |                  | 2. Generate VP   |                    |
    |                  |  (select VCs,    |                    |
    |                  |   sign)          |                    |
    |                  |----------------->|                    |
    |                  | 3. POST          |                    |
    |                  |  /auth/verify    |                    |
    |                  |                  | 4. Validate VP     |
    |                  |                  |    signature       |
    |                  |                  |------------------->|
    |                  |                  | 5. Check revocation|
    |                  |                  |    status          |
    |                  |                  |------------------->|
    |                  |                  | 6. Confirm claims  |
    |                  |                  |<-------------------|
    |                  |                  |                    |
    |                  | 7. Return JWT    |                    |
    |                  |<-----------------|                    |
    | 8. JWT with DID  |                  |                    |
    |  and claims      |                  |                    |
    |<-----------------|                  |                    |
    |                  |                  |                    |

1. The application calls login() with a list of required claims.
2. The user’s wallet selects the appropriate verifiable credentials, constructs a Verifiable Presentation (VP), and signs it.
3. The SDK sends the VP to the Auth Bridge Gateway via POST /auth/verify.
4. The gateway validates the VP signature against the subject’s DID document.
5. The gateway checks revocation status for each included credential.
6. The gateway confirms that the required claims are satisfied.
7. The gateway issues a short-lived JWT containing the subject’s DID and verified claims.
8. The application receives the JWT and uses it for session management.

9.2 Auth Gateway

The Auth Bridge Gateway is OIDC-compliant. It exposes standard OpenID Connect endpoints:

9.3 Browser SDK

import { SolidusAuth } from '@solidus-network/auth';
 
const auth = new SolidusAuth({
  appId: 'app-xyz-123',
  network: 'mainnet',
  gatewayUrl: 'https://auth.solidus.network',
});
 
// Login with required claims
const session = await auth.login({
  requiredClaims: ['email_verified', 'age_over_18'],
});
 
console.log(session.did);    // "did:solidus:1:5dK3fP7v..."
console.log(session.claims); // ["email_verified", "age_over_18"]
console.log(session.jwt);    // "eyJhbGciOiJFZDI1NTE5..."
 
// Check current session
const current = await auth.getSession();
if (current) {
  console.log('Authenticated as', current.did);
}
 
// Logout
await auth.logout();

9.4 Backend SDK

import { SolidusVerifier } from '@solidus-network/auth/server';
 
const verifier = new SolidusVerifier({
  gatewayUrl: 'https://auth.solidus.network',
});
 
// Middleware: verify JWT on every request
app.use(async (req, res, next) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  try {
    req.identity = await verifier.verifyToken(token);
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
});
 
// Route-level claim enforcement
app.get('/medical/records', verifier.requireClaim('doctor_license_valid'), (req, res) => {
  // Only reachable if the caller has a valid doctor license credential
  const records = getRecordsFor(req.query.patientId);
  res.json(records);
});

9.5 JWT Structure

The JWT issued by the Auth Gateway contains the following claims:

{
  "iss": "https://auth.solidus.network",
  "sub": "did:solidus:1:5dK3fP7vLm8Qw2xNz9Rb4YcJ6tHgAs",
  "aud": "app-xyz-123",
  "iat": 1741683600,
  "exp": 1741687200,
  "solidus_claims": ["email_verified", "age_over_18"],
  "solidus_network": "1",
  "nonce": "a1b2c3d4e5f6"
}

The JWT is signed with Ed25519 using the gateway’s key pair. The public key is available at the JWKS endpoint for offline validation.

10. Network Layer

The Solidus network layer handles peer-to-peer communication, message propagation, and transport security.

10.1 Transport

Framework: libp2p

10.2 Peer Discovery

Peer discovery uses a two-phase approach:

1. Bootstrap nodes. New nodes connect to a set of well-known bootstrap nodes maintained by the Solidus Foundation. Bootstrap node addresses are hardcoded in the client software and updated with each release.

2. Distributed Hash Table (DHT). After connecting to bootstrap nodes, the new node populates its routing table via Kademlia DHT. Subsequent peer discovery is fully decentralized.

10.3 Message Propagation (Gossip)

Messages (transactions, blocks, verification requests) propagate through the network using a gossip protocol:

1. The originating node signs the message.
2. The message is broadcast to 8 randomly selected peers (fanout = 8).
3. Each receiving peer validates the message signature, then forwards it to 8 of its own peers (excluding the sender).
4. Propagation is exponential: 8 -> 64 -> 512 -> …
5. Full network coverage is achieved in under 500 milliseconds for networks up to 10,000 nodes.

Deduplication: Each node maintains a short-lived message ID cache (TTL = 30 seconds) to prevent processing or forwarding duplicate messages.

10.4 Network Security

11. Governance: Solidus Improvement Proposals

The Solidus protocol evolves through a formal governance process. Changes are proposed, debated, voted on, and activated according to a defined lifecycle.

11.1 SIP Lifecycle

DRAFT -> REVIEW -> DISCUSSION (30 days) -> VOTE -> IMPLEMENTATION -> ACTIVATION

11.2 Voting

• Voting power is weighted by staked SLDS.
• A SIP passes with 67% approval (measured by stake weight, not by headcount).
• Quorum: at least 30% of total staked SLDS must participate in the vote.

11.3 Changeable Parameters

The following protocol parameters can be modified through SIP governance:

• Transaction and credential fees.
• Validator stake requirements.
• Slashing percentages.
• Consensus committee size and thresholds.
• Gas weight schedules.
• Revocation list capacity.

11.4 Immutable Properties

The following properties are fixed at genesis and cannot be changed through governance:

• Cryptographic algorithms. Ed25519, BLAKE3, BBS+, BLS12-381, and other shipped core primitives cannot be replaced. (Migration to post-quantum algorithms, if needed, would require a hard fork with broad social consensus, not a SIP vote.)
• Total token supply. The maximum supply of SLDS is fixed.
• Core security properties. BFT safety guarantees, the requirement for 2/3 supermajority, and the binding between identity and validator eligibility.

12. Fee Schedule

All fees are denominated in SLDS and are payable by the transaction sender.

12.1 DID Operations

12.2 Credential Issuance

12.3 Verification Requests

Verification request fees are set by the requester and must meet the minimum fee for the credential types involved. Validators receive a share of the fee as compensation.

12.4 Fee Distribution

Fee amounts are governance-adjustable via SIP (see Section 11.3).

Note: This per-transaction fee distribution (70/20/10) is distinct from the protocol-level revenue distribution (40% stakers / 30% treasury / 25% burn / 5% development fund) which applies to revenue from enterprise subscriptions and other non-transaction protocol revenue streams.

13. Security Considerations

13.1 Threat Model

The protocol assumes the following adversary capabilities:

• The adversary may control up to 33% of the validator committee (7 of 21).
• The adversary may observe all network traffic.
• The adversary may attempt Sybil attacks by creating multiple identities.
• The adversary may attempt to correlate user activity across verification requests.

13.2 Mitigations

13.3 Privacy Guarantees

• Personal data is never stored on-chain. Only credential hashes are registered.
• ZK proofs allow claim verification without data disclosure.
• Selective disclosure lets users present only the claims requested, not entire credentials.
• The SolidPod is under the user’s exclusive control; no third party can access it without the user’s consent.

13.4 Cryptographic Assumptions

The security of the protocol rests on:

• The hardness of the Discrete Logarithm Problem on Curve25519 (for Ed25519 and Curve25519 encryption).
• The collision resistance of BLAKE3 and SHA-256.
• The unforgeability of BBS+ signatures under the q-SDH assumption in pairing-friendly groups (for selective-disclosure credentials).
• The unforgeability of BLS signatures under the Computational Diffie-Hellman assumption.

Appendix A: Wire Format Summary

All protocol messages are serialized as JSON-LD when transmitted over HTTP APIs and as CBOR when transmitted over the libp2p gossip layer. CBOR is used for compactness and parsing speed in the consensus-critical path.

Appendix B: Version History

This document is the authoritative specification for the Solidus Protocol. Implementations must conform to the behaviors described herein. Where ambiguity exists, the reference implementation governs.