# Tier-based Role Certifier

**Authors**: BlockScience and SDF, September 2023

### Summary

The Tier-based Role Certifier (TRC) is a framework for attesting per-identity roles through the aggregation of available attestations. It is vaguely similar to Passport-like solutions for identity attestation, with the caveat that affordances are made for multiple roles (eg. each role has their own passport-like attestator) and that the concepts of role disqualifiers / autoqualifiers are introduced.


Attestation flows on a stylized TRC on which admissible roles for an identity are:
1) Pathfinder
2) Navigator
3) Pilot

Source attestations to be aggregated are shown as ellipses. Any identity can apply for being attested for any of the available roles, with its approval being conditional either on the identity being listed on the disqualifiers / autoqualifiers, or the identity being above a threshold on the conditional qualifiers.

#### Use Cases

- **Managing identity rights on role-based systems**: TRC allows for expressing differentiated rights across identities on a single system by setting different sets of attestations for each role that encodes those rights.
- **Representing hierarchical-like roles in terms of rights and required attestations**: TRC allows creating dependence and/or fast-track pathways towards roles that require more layers of attestations. For example, is Role B only possible if Role A was acquired beforehand? Does acquiring Role C automatically associate having acquired Role B and A regardless of the path? TRC allows for a generalized form to express all of those.

#### User Journey

##### Setting-up TRC
1. Administrator user creates roles of interest.
2. Administrator user configures the validity duration for each role attestation.
3. Administrator user attaches dis/auto qualifiers for each created role.
4. Administrator user attaches conditional qualifiers and its weights for each role.
5. Administrator user sets up the weighted conditional attestations threshold.

##### Using TRC
1. Users can apply for attestations for any role at any time. Newer attestations will replace older attestations regardless of them being expired or active.
2. The attestation result will be processed through TRC's logic with the following sequence:
- If any disqualifier attestation is present and valid, then the result is to not attest.
- If any autoqualifier attestation is present and valid, then the result is to attest.
- If the user weighted sum of conditional attestations is above the role threshold, then the result is to attest.
- If the result is to attest, the user will receive a soulbound registry entry with its expiry date set up until the role attestation duration. Else, nothing happens.

#### Module-specific Adjustments

##### Parametric Adjustments
- Setting up the Conditional Attestator thresholds.
- Including / Excluding Attestators as Dis/Conditional/Auto qualifiers.

##### Logical Adjustments
- Implementing new Attestators.

---

## Specification

#### Introduction

A notebook containing an end-to-end example implementation for this document can be found on the [gov-modules-demos GitHub repository](https://github.com/BlockScience/gov-modules-demos/blob/main/demos/tier_based_role_certifier.ipynb).

#### Definitions

- **Attestation**: Retrievable boolean assertion. Can contain or be assigned an expiry timestamp. Can be sourced exogenously (eg. by retrieving stamps through oracles) or endogenously (eg. by attestating instantaneously through procedural rules).
- **Role**: Computable boolean assertion on which the result depends on the aggregation of pre-defined prior attestations.
- **Qualifier**: Attestation source that can be used for attesting for a given role.
- **Disqualifier**: Qualifier that will automatically deny a given role attestation.
- **Autoqualifier**: Qualifier that will automatically approve a given role attestation, provided that it wasn't disqualified beforehand.
- **Conditional Qualifier**: Qualifier on which the result will add to the accumulated approval criteria for a given role attestation.
- **Attestation Weight**: Transforms a boolean assertion into a real number. Used for controlling the relative importance for each conditional qualifier.
- **Qualifier Aggregator**: Transforms a list of real numbers into a single real number. Used for transforming the conditional qualifier weights into a single number that can be compared against.
- **Conditional Threshold**: Comparison number that is used for transforming a single real number into a boolean assertion. Used for determining whether the aggregated conditional qualifiers approve a positive result for the role attestation or not.

#### Example Implementation in Python

# Definitions


AttestationUUID = str
AttestationWeight = float
Days = int

class AttestationProbabilityArgs(NamedTuple):
    attest_probability: float
    invoke_probability: float
    issuance_mean_expiry_in_days: Days
    issuance_std_expiry_in_days: Days

@dataclass
class Attestation():
    attestation_uuid: AttestationUUID
    result: bool  # Between 0.0 and 1.0
    issuance: Days
    expiry: Days


@dataclass
class Agent():
    attestations: dict[AttestationUUID, Attestation]

    def valid_attestations(self, reference_time) -> list[Attestation]:
        return [a
                for a in self.attestations.values()
                if a.expiry > reference_time
                and a.issuance <= reference_time]

    def sucessful_attestations(self, reference_time) -> list[Attestation]:
        return [a
                for a in self.valid_attestations(reference_time)
                if a.result == True]

@dataclass
class RoleCertifier():
    attestation_uuid: AttestationUUID
    issuance_validity: Days

    conditional_qualifiers: dict[AttestationUUID, AttestationWeight]
    auto_qualifers: set[AttestationUUID]
    disqualifiers: set[AttestationUUID]

    qualifier_aggregator: Callable[[dict], float]
    conditional_threshold: float

    def generate_attestation(self, result: bool, time: Days) -> Attestation:
        return Attestation(self.attestation_uuid,
                           result,
                           time,
                           time + self.issuance_validity)

    def agent_certification_result(self,
                                   agent: PassportDemoAgent,
                                   time: Days) -> bool:
        agent_sucessful_attestations = set(a.attestation_uuid
                                           for a in agent.valid_attestations(time)
                                           if a.result == True)

        if len(agent_sucessful_attestations & self.disqualifiers) > 0:
            return False
        elif len(agent_sucessful_attestations & self.auto_qualifers) > 0:
            return True
        else:
            conditional_attestations = set(self.conditional_qualifiers.keys())
            agent_relevant_attestations = agent_sucessful_attestations & conditional_attestations

            agent_conditional_values = {a: self.conditional_qualifiers[a]
                                        for a
                                        in agent_relevant_attestations}
            agent_conditional_value = self.qualifier_aggregator(
                agent_conditional_values)
            if agent_conditional_value >= self.conditional_threshold:
                return True
            else:
                return False

    def attestate_agent(self, agent: PassportDemoAgent, time: Days):
        return self.generate_attestation(self.agent_certification_result(agent, time), time)

# Example instantiation of TRC

def compound_product(lst): 
    if len(lst) > 1:
        return reduce(lambda x, y: (1 + x) * (1 + y) - 1, list(lst))
    elif len(lst) == 1:
        return lst[0]
    else:
        return 0.0

role_A = RoleCertifier(
    attestation_uuid='role_A_attestation',
    issuance_validity=90,
    conditional_qualifiers={'att_1': 1, 'att_2': 2, 'att_3': 3},
    auto_qualifers=set(),
    disqualifiers={'att_ban'},
    qualifier_aggregator=lambda atts: sum(atts.values()),
    conditional_threshold=2
)

role_B = RoleCertifier(
    attestation_uuid='role_B_attestation',
    issuance_validity=30,
    conditional_qualifiers={'att_3': 0.3, 'att_4': 0.25, 'att_5': 0.2},
    auto_qualifers={'role_A_attestation'},
    disqualifiers={'att_ban'},
    qualifier_aggregator=lambda atts: compound_product(tuple(atts.values())),
    conditional_threshold=0.25
)

EXAMPLE_ATTESTATION_PROVIDERS = {
    'att_1': AttestationProbabilityArgs(0.2, 0.1, 7, 10),
    'att_2': AttestationProbabilityArgs(0.2, 0.1, 14, 10),
    'att_3': AttestationProbabilityArgs(0.05, 0.1, 30, 10),
    'att_4': AttestationProbabilityArgs(0.4, 0.05, 15, 3),
    'att_5': AttestationProbabilityArgs(0.6, 0.5, 40, 10),
    'att_ban': AttestationProbabilityArgs(0.02, 0.05, 120, 5)
}

EXAMPLE_ROLE_CERTIFIERS = [role_A, role_B]

---

## Implementation Instructions

As of now (November 2023), no PoC for the TRC was built, therefore providing implementation instructions is postponed. We'll list expected steps that are required in order to be able to implement a potential MVP:
1. Implement Role Certifiers
2. Implement Qualifiers (dis-, auto- and conditional-)
3. Decide Conditional Qualifier Weights, Aggregator and Threshold.
4. Implement Base Module

---

## Tuning Guidelines

#### Tuning Story 1: When to add new dis/auto/conditional qualifiers to a role certifier?

TRC's goal is to provide a comprehensive framework to make the requirements for acquiring a given role explicit. Some of them may require a requirements-based approach, on which everyone that fulfills a base set of qualities is approved for the role, whereas others may require a selection procedure for filling in a limited supply of positions. In terms of heuristics, we can have the following guidelines when creating new qualifiers:
- **Disqualifiers** are useful for any vetting process: e.g. ban lists and restrictions.
- **Conditional qualifiers** are useful when algorithmical procedures for attesting someone to a role are desirable. This tends to be the case with roles in which many members are expected. They can also be useful when the role belonging rules should be made particularly explicit.
- **Autoqualifiers** are useful for hierarchical roles, where belonging to a higher-ranked role gives automatic access to all lower roles. They can also be useful for fast-tracking members.

#### Tuning Story 2: When to add new roles?

Ideally, a Role Attestation is attesting that some identity should have particular rights. Those rights can then be broken down into pieces or bundled together as combos. Adding new roles can be useful when new bundles of rights are created. Alternatively, one approach is to associate each potential right with a role, in which case any new rights should be associated with new roles.

---

### Simulations

**cadCAD demo**: [Link to demo](https://github.com/BlockScience/gov-modules-demos/blob/main/demos/tier_based_role_certifier.ipynb)

---

#### Visualizations