# Trust Graph Bonus

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

#### Summary
The Trust Graph Bonus is a module developed for NQD that increases voting power for community members that are trusted and central on the ecosystem network. The module allows users to assign trust to other users. As opposed to the Reputation Module, which assigns additional Voting Power based on the individual collection of verified badges, the Trust Graph Bonus allows users to actively form a network of trust within their community.

The relationships within the Trust Graph Bonus module are distinct from those within the Quorum Delegation, but might show high correlations. While it might be assumed that a user trusts someone who they delegate to, this assumption does not always hold true in practice. Trust is expected to be assigned more liberally - a user can assign trust for any reasons, as there is no direct effect on their own choices and voting power. Similarly, a user can assign trust to a high number of other users, while Delegation is limited.

The rationale for this design is to enable active contribution to Voting Power determination by the community. The formation of a trust network can further reveal interesting dynamics emanating from the community. The module was highly inspired by prior work from Source.Cred and Block.Science.

Further reading on some of the underlying choices can be found here: [Exploring Subjectivity in Algorithms](https://medium.com/sourcecred/exploring-subjectivity-in-algorithms-5d8bf1c91714)

#### Use Cases

**Permanent Trust:** Communities thrive on localized interactions and social association. Enabling a community to actively set trust relationships, determining additional voting power for community decisions, can increase representation of users. Over time, such a mechanism could be iterated on to represent a proxy for real relationships and social interactions.

**Temporary Trust:** Communities sometimes face temporary decisions where expertise is not always globally attributable or explicit. The Trust Graph Bonus could enable a temporary formation of trust based on a specific decision, allowing the community to collectively attribute the expertise based on local relationships and association. In such a scenario, a separate and temporary instance of the Trust Graph Bonus could help form a more representative view on relevant expertise and experience.

#### User Journey
1. User A decides to assign trust to another User B.
2. User A assigns trust via the UI.
3. The assigned trust is taken as input to the Trust Graph Bonus.
4. When voting, User B's Voting Power is adapted due to User A's trust assignment.

#### Module-specific Adjustments

##### Parametric Adjustments
- **alpha** (Initially at 0.0): The uniform seed vector drives some base level of credit into every node, and the mixing process allows it to diffuse throughout the network. The coefficient alpha can be interpreted as the rate at which this credit is injected. Larger alpha will drive the solution closer and closure to uniform PageRank, while smaller alpha will allow the credit to diffuse much further, resulting in more accumulation in pockets and a wider spread between the largest and smallest values.
- **Self-loop weight** (Initially at 1.0)
- **Upstream weight** (Initially at 0.0)

##### Logical Adjustments
- **Allow for bi-directional trust flows:** While currently only the receiver of a trust assignment receives a bonus, actively assigning trust could also be seen as a value-add to the network.
- **Allow for trust to flow further over individual users:** When User A trusts User B, the trust currently stops there and does not flow further to Users C, D, and E who are trusted by User B. However, one could argue that it is relevant whether a highly trusted User or a barely trusted User actively assigns trust.
- **Allow for trust to decay/accumulate over time/rounds**

##### Functional Adjustments
- Allow for capping the individual users anyone can trust
- Allow for a functional requirement to be passed (such as a time limit) before a new User can trust someone
- Allow for a functional requirement to be passed (such as a time limit) before a new User can be trusted
- Adjust incentives to trust someone / become trusted

## Specification

#### Introduction
A notebook containing an end-to-end example implementation for this document can be found on the [BlockScience/scf-voting-mechanism GitHub repository](https://github.com/BlockScience/scf-voting-mechanism).

#### General Definitions
The admissible user actions for the Trust Bonus Module in each round are:
- **Assign Trust to another User:** Creates a new edge in the trust graph
- **Remove Trust from another User:** Requires first having assigned Trust to that User; removes an edge from the trust graph

#### Type of PageRank
For the PoC, we’ve selected a **Scaled Canonical PageRank** algorithm for the Trust Bonus function. This is justified by its familiarity (it’s relatively well-known through the technical community) and simplicity (the algorithm is relatively simple, and several out-of-the-box implementations are available).

As of now, it uses a damping factor of 0.85 and uniform seeding across the trust graph. The results are min-max normalized, which means that the raw trust scores per user will range between 0 and 1. We do expect that choice to be updated over time, as alternatives are explored, such as using an Aggregated Personalizing PageRank. It’s also possible that new formulations will appear as we build the testing apparatus and refine the forms against the desirables & influx of data.

#### Example Implementation in Python

# 1) Definitions

Key is the Trusting User and the Value Set are the Users being Trusted.


TrustGraph = dict[UserUUID, list[UserUUID]]

def compute_trust_score(raw_graph: dict) -> dict[UserUUID, float]:
    """
    Computes a Trust Score based on the Canonical PageRank.

    This is done by computing the PageRank on the whole Trust Graph
    with default arguments and scaling the results through MinMax.

    The resulting scores will be contained between 0.0 and 1.0
    """
    G = nx.from_dict_of_lists(raw_graph,
                              create_using=nx.DiGraph)

    pagerank_values = nx.pagerank(G, 
                                  alpha=0.85, 
                                  personalization=None, 
                                  maxiter=100,
                                  tol=1e-6,
                                  nstart=None,
                                  weight=None,
                                  dangling=None)
    
    max_value = max(pagerank_values.values())
    min_value = min(pagerank_values.values())
    trust_score = {user: (value - min_value) / (max_value - min_value)
                   for (user, value) in pagerank_values.items()}
    return trust_score


# 2) Backend inputs

TRUST_GRAPH = {'A': ['B', 'C'], 'B': ['C'], 'C': ['A']}
TRUST_BONUS_PER_USER = compute_trust_score(TRUST_GRAPH)

# 3) Implementing an Oracle

def trust_score(user_id: UserUUID, _2, _3) -> VotingPower:
    """
    Oracle for the Trust Bonus.
    """
    return TRUST_BONUS_PER_USER[user_id]

#### Resources

- [GitHub Repository: scf-voting-mechanism](https://github.com/BlockScience/scf-voting-mechanism)
- [Exploring Subjectivity in Algorithms - Medium Article](https://medium.com/sourcecred/exploring-subjectivity-in-algorithms-5d8bf1c91714)

## Implementation Instructions

A PoC implementation in Rust for Soroban by Alejo Mendoza, Karol Bisztyga, and Mateusz Kowalski is located in the voting-poc GitHub repository. It implements the Neural Governance, Quorum Delegation, and the Trust Graph Bonus governance modules, and we'll use it as the basis for providing instructions.

#### 1) Set-up PageRank Parameters

For the setup, check this [link](https://github.com/alejomendoza/voting-poc/blob/84611b625a607bd26d0db5b6f5efe125af769f0d/src/voting_system/src/page_rank/mod.rs#L41).

let num_iterations = 10;
let damping_factor = DecimalNumberWrapper::from((0, 850)).as_tuple(); // eg. alpha=0.85

## Tuning Guidelines

#### Tuning Story 1: How to tune the damping factor? Or set-up the seeds?
Answer: This is a long story that's better answered by the [Exploring Subjectivity in Algorithms](https://medium.com/sourcecred/exploring-subjectivity-in-algorithms-5d8bf1c91714), by Michael Zargham.

## Simulations

#### cadCAD Demo
Check out the cadCAD demo [here](https://github.com/BlockScience/gov-modules-demos/blob/main/demos/trust_bonus.ipynb).

#### Visualizations