Level 2: Weight-of-Weights - For tightly cooperating teams, KERI supports a two-level hierarchy where:

• Individual users manage split keys across devices (Level 1)
• Teams of teams coordinate through weighted multi-signature groups (Level 2)

This two-level limitation is intentional. According to the canonical documentation, KERI explicitly does not support recursive weight-of-weights beyond two levels because:

• The primary use cases are adequately served by two levels
• More complex hierarchies can be addressed through KERI's delegation mechanism as an alternative
• Deeper nesting would create significant implementation complexity in CESR (Composable Event Streaming Representation) encoding

Key Components

The weight system integrates with several KERI components:

Tholder Objects: The Tholder (threshold holder) is a specialized object in KERI implementations that manages fractionally-weighted thresholds. It encapsulates the logic for:

• Parsing weight expressions from threshold strings
• Calculating whether a set of signatures satisfies the weighted threshold
• Supporting both integer and fractional weight values

Threshold Expressions: Weights are expressed in threshold strings that can represent:

• Simple integer thresholds: "2" (requires 2 signatures)
• Fractional weights: "1/2" (requires signatures totaling at least 1/2 of total weight)
• Complex weighted combinations encoded in CESR format

CESR Encoding: Weights must be encoded in CESR format for inclusion in key events. The CESR specification provides dual-indexed codes specifically designed for weighted threshold multi-signature schemes, enabling compact representation of weight information in both text and binary domains.

Data Format

Field Definitions

Weights appear in KERI data structures in several contexts:

In Establishment Events:

{
  "v": "KERI10JSON00011c_",
  "t": "icp",
  "d": "EZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "i": "EZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "s": "0",
  "kt": ["1/2", "1/2", "1/2"],
  "k": [
    "DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
    "DZH3ULvaU6JR2nmwyZ-i0d8JZAoTNYAfSVPzhzS6b5CM",
    "DTNZH3ULvaU6JR2nmwyZ-i0d8JZAoYAfSVPzhzS6b5CM"
  ],
  "nt": ["1/2", "1/2", "1/2"],
  "n": [
    "EYAfSVPzhzaU6JR2nmwyZdi0d8JZTNZH3ULvS6b5CM",
    "EaU6JR2nmwyZdi0d8JZTNZH3ULvYAfSVPzhzS6b5CM",
    "ETNZH3ULvYAfSVPzhzaU6JR2nmwyZdi0d8JZS6b5CM"
  ],
  "bt": "2",
  "b": ["witness1", "witness2", "witness3"],
  "c": [],
  "a": []
}

In this example:

• kt (key threshold) contains weight values for current keys
• nt (next threshold) contains weight values for pre-rotated keys
• Each weight is expressed as a fractional string "1/2"
• The threshold is satisfied when signatures from keys whose weights sum to ≥1 are provided

In ACDC Edge Sections:

{
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "boss": {
    "n": "EQzFVaMasUf4cZZBKA0pUbRc9T8yUXRFLyM1JDASYqAA",
    "s": "EQzFVaMasUf4cZZBKA0pUbRc9T8yUXRFLyM1JDASYqAA",
    "w": "high"
  }
}

Here the w field provides an edge weight property, though the ACDC specification notes this is optional and the semantics of edge weights are application-specific.

Encoding Format

Weights in KERI must be encoded according to CESR specifications:

Text Domain Encoding: Weights are represented as strings in JSON serializations:

• Integer weights: "2", "3", "5"
• Fractional weights: "1/2", "2/3", "3/5"
• The fractional notation enables precise specification of weighted voting schemes

Binary Domain Encoding: When serialized to binary formats (CBOR, MGPK), weights follow CESR primitive encoding rules:

• Weights are encoded as CESR primitives with appropriate derivation codes
• The encoding preserves the fractional representation
• Round-trip conversion between text and binary domains maintains weight values

CESR Dual-Indexed Codes: The CESR specification provides specialized encoding for weighted threshold configurations:

• Dual-indexed codes support the common use case of thresholded multi-signature schemes
• These codes enable compact representation of both key indices and their associated weights
• The encoding is designed to be both human-readable (in text domain) and compact (in binary domain)

Size and Constraints

Weight Value Constraints:

• Weights must be non-negative rational numbers
• Fractional weights are expressed as numerator/denominator
• The sum of all weights in a key set defines the total voting power
• Threshold values must be ≤ sum of all weights

Architectural Constraints:

• KERI supports exactly two levels of weighted thresholds (weight-of-weights)
• This limitation is enforced to maintain CESR encoding simplicity
• Deeper hierarchies must use delegation instead of nested weights

Implementation Constraints:

• Weight calculations must handle fractional arithmetic precisely
• Implementations must avoid floating-point precision issues
• Threshold satisfaction checks must be deterministic across implementations

Operations

Creation and Initialization

Weighted Threshold Specification:

When creating a new AID with weighted thresholds, the controller specifies:

1. Key List: The ordered list of public keys
2. Weight List: Corresponding weights for each key (same length as key list)
3. Threshold Value: The minimum weight sum required for valid signatures

Example using KERIpy's kli tool:

kli incept \
  --name myaid \
  --icount 3 \
  --isith '["1/2","1/2","1/2"]' \
  --ncount 3 \
  --nsith '["1/2","1/2","1/2"]' \
  --transferable

This creates an AID where:

• Three keys are specified
• Each key has weight 1/2
• Total weight is 3/2
• Any two signatures (weight sum = 1) satisfy the threshold

Tholder Object Initialization:

In KERIpy implementation, the Tholder class manages weighted thresholds:

from keri.core.coring import Tholder

# Create a tholder for weighted threshold
tholder = Tholder(sith=["1/2", "1/2", "1/2"])

# Check if a set of indices satisfies the threshold
indices = [0, 1]  # First two keys
satisfied = tholder.satisfy(indices=indices)

Updates and Modifications

Key Rotation with Weight Changes:

Weights can be modified during rotation events:

{
  "v": "KERI10JSON00011c_",
  "t": "rot",
  "d": "E8JZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "i": "EZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "s": "1",
  "p": "EZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "kt": ["2/3", "1/3"],
  "k": [
    "DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
    "DZH3ULvaU6JR2nmwyZ-i0d8JZAoTNYAfSVPzhzS6b5CM"
  ],
  "nt": ["2/3", "1/3"],
  "n": [
    "EYAfSVPzhzaU6JR2nmwyZdi0d8JZTNZH3ULvS6b5CM",
    "EaU6JR2nmwyZdi0d8JZTNZH3ULvYAfSVPzhzS6b5CM"
  ],
  "bt": "2",
  "br": [],
  "ba": [],
  "a": []
}

This rotation:

• Reduces the key set from 3 to 2 keys
• Changes weights to 2/3 and 1/3
• Maintains the threshold requirement (signatures totaling ≥1)
• The first key alone (weight 2/3) is insufficient
• Both keys together (weight 1) satisfy the threshold

Weight Rebalancing:

Organizations may need to rebalance weights as governance structures change:

• Adding new participants with specific voting power
• Adjusting existing participant weights
• Removing participants and redistributing their weight

Each rebalancing requires a rotation event that:

1. Specifies the new key set
2. Assigns new weights
3. Must be signed according to the current threshold (before rotation)
4. Establishes the new threshold for future operations

Verification and Validation

Threshold Satisfaction Checking:

Validators must verify that attached signatures satisfy the weighted threshold:

1. Extract Signature Indices: Determine which keys signed the message
2. Sum Weights: Calculate the total weight of signing keys
3. Compare to Threshold: Verify sum ≥ threshold value

Pseudocode:

def verify_weighted_threshold(signatures, keys, weights, threshold):
    total_weight = 0
    for sig in signatures:
        key_index = sig.index
        if verify_signature(sig, keys[key_index]):
            total_weight += weights[key_index]
    return total_weight >= threshold

Fractional Arithmetic Precision:

Implementations must handle fractional weights correctly:

• Use rational number arithmetic (not floating point)
• Maintain exact fractional representations
• Ensure deterministic threshold calculations across implementations

KERIpy uses Python's fractions.Fraction class for this purpose:

from fractions import Fraction

weight1 = Fraction(1, 2)
weight2 = Fraction(1, 2)
total = weight1 + weight2  # Exactly 1, not 0.9999999

Edge Weight Validation:

For ACDC edge weights, validation depends on application semantics:

• Edge weights are optional in ACDC specifications
• Applications define their own weight semantics
• Validators must implement application-specific weight logic

Usage Context

In Which Protocols

KERI Establishment Events:

Weights are fundamental to KERI's key management:

• Inception Events: Initial weight assignment for founding keys
• Rotation Events: Weight updates during key rotation
• Delegated Identifiers: Weights in both delegator and delegate key sets

ACDC Credential Graphs:

Weights enable sophisticated authorization logic:

• Edge Weights: Represent relationship strength or priority
• Operator Weights: Support weighted AND/OR logic in edge operators
• Authorization Chains: Weighted paths through credential graphs

Multi-Signature Coordination:

Weights facilitate organizational governance:

• Corporate Governance: Board members with different voting power
• Consortium Management: Organizations with weighted participation
• Threshold Policies: Flexible authorization requirements

Lifecycle Management

Initial Configuration:

Weights are established at AID inception:

1. Controller determines governance model
2. Assigns weights to initial key set
3. Specifies threshold requirement
4. Creates inception event with weight configuration

Operational Phase:

During normal operations:

• Signatures are collected according to weight requirements
• Validators verify threshold satisfaction
• Weight configuration remains stable between rotations

Governance Evolution:

Weights evolve through rotation events:

• Organizational changes trigger weight rebalancing
• New participants receive weight allocations
• Departing participants' weights are redistributed
• Each change requires threshold-satisfying authorization

Delegation Hierarchies:

Weights propagate through delegation:

• Parent identifiers delegate with weighted authorization
• Child identifiers inherit governance constraints
• Weight-of-weights enables nested organizational structures

Related Structures

Tholder (Threshold Holder):

The Tholder object encapsulates weight logic:

• Parses weight expressions from threshold strings
• Calculates threshold satisfaction
• Supports both simple and fractional weights
• Provides consistent weight handling across KERI implementations

CESR Primitives:

Weights are encoded as CESR primitives:

• Text domain: Human-readable fractional strings
• Binary domain: Compact binary representations
• Dual-indexed codes: Specialized encoding for weighted multi-sig

Key Event Logs (KELs):

Weights are recorded in KEL events:

• Establishment events contain weight specifications
• Weight history is verifiable through KEL replay
• Weight changes are cryptographically bound to rotation events

Witness Pools:

Weights can apply to witness configurations:

• Witness threshold of accountable duplicity (TOAD)
• Weighted witness consensus mechanisms
• Flexible witness pool governance

Implementation Considerations

CESR Encoding Complexity:

The two-level weight limitation exists because:

• Recursive weight-of-weights creates complex CESR encoding challenges
• Straightforward encoding is achievable for two levels
• Deeper nesting would require significantly more complex parsing logic

Alternative Approaches:

For scenarios requiring more than two weight levels:

• Use KERI's delegation mechanism instead
• Create hierarchical identifier structures
• Delegate authority through chained AIDs
• Each delegation level can have its own weighted threshold

Performance Implications:

Weighted thresholds affect performance:

• Signature verification requires weight calculation
• Fractional arithmetic adds computational overhead
• Threshold satisfaction checking is more complex than simple counting
• Implementations should cache weight calculations where possible

Security Considerations:

Weight systems introduce security considerations:

• Weight distribution affects attack resistance
• Concentrated weights create single points of failure
• Balanced weight distribution improves resilience
• Threshold values must be carefully chosen relative to total weight

Conclusion

Weights in KERI provide essential flexibility for multi-signature authorization schemes, enabling sophisticated governance models while maintaining cryptographic security. The deliberate limitation to two weight levels balances implementation complexity with practical use cases, while delegation mechanisms provide alternative approaches for more complex hierarchies. Understanding weight mechanics is crucial for implementing robust, flexible identity systems using KERI infrastructure.

Security Best Practices

• Avoid concentrated weight distributions that create single points of failure
• Balance weights to improve resilience against key compromise
• Set thresholds carefully relative to total weight
• Document weight rationale in governance frameworks
• Regularly review and rebalance weights as organizations evolve