Trust Bonds Docs

Introduction

Trust Bonds is a public good initiative created by former Kernel Block participants, introducing a novel approach to establishing and verifying trust in monetary bonds between individuals within the Web3 environment. This incentivizes coordination, allowing participants to earn a higher-than-market-average yield on their savings, creating a new primitive for social reputation.

For those unfamiliar with the term, public goods are Web3 resources or services that are accessible to everyone in a non-excludable and non-rivalrous way. That is, one person's use of a public good doesn't reduce the availability to others, nor can anyone be prevented from using it. In the real world, examples include public parks or access to clean air. In Web3, public goods are projects that benefit the entire ecosystem, aiming to aid the growth of decentralized technologies and their popularity.

Our Solutions

For this project, two Web3 solutions are being used:

  • Aave: An open-source protocol used to create non-custodial liquidity markets to earn interest on supplying and borrowing assets with a variable interest rate.
  • Gitcoin Passport: Provides an identity verification application and Sybil resistance protocol by aggregating various identity attributes such as social media verification or financial history. This creates a "digital passport" that can be used to participate in the application while reducing the risk of fake or duplicated identities—known as Sybil attacks.

How Trust Bonds Work

The project creates Trust Bonds, which are monetary bonds between two or more people who trust each other. Every participant contributes an equal amount of money to a shared account, and each of them has access to the total amount and can withdraw it at any time.

This works towards building trust and transparency in decentralized systems using these cutting-edge tools and helps users build on-chain reputation through their digital history and behavior recorded and verified on a blockchain. As all blockchain actions are transparent and immutable, users' interactions, contributions, and behavior with decentralized protocols will build up their reputation, allowing communities to assess trustworthiness without relying on traditional centralized institutions or other third parties.

Considering that when you form a Trust Bond with someone, you are also trusting them with a set amount of money, one can form different bonds of different values according to how much one trusts someone.

Getting Started

To develop the contract:

  1. Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup
  1. Install dependencies
# Install Node.js dependencies
pnpm install

# Install Forge dependencies
cd packages/contracts
forge install
  1. Test the contracts
# Run all tests
pnpm -F @trust-bonds/contracts test

# Run tests with coverage
pnpm -F @trust-bonds/contracts coverage

# Run gas snapshot checks
pnpm -F @trust-bonds/contracts snapshot-check

# Create new gas snapshots
pnpm -F @trust-bonds/contracts snapshot
  1. Build the contracts
pnpm -F @trust-bonds/contracts build
  1. Lint and format
pnpm -F @trust-bonds/contracts lint

The project uses Foundry for Solidity development and testing. The main contract files are located in packages/contracts/src/. Tests can be found in packages/contracts/test/.

How to contribute

We are looking for contributors. Check our Issues Page and look for good first issue tag.

You can also schedule a call with Leo to know more about the project and how to help.

Core Concepts

Trust Bond

A Trust Bond is a novel financial primitive that represents a mutual trust relationship between two parties on the blockchain. Key characteristics include:

  • Equal Contribution: Both parties must contribute the same amount of tokens to form a bond
  • Mutual Access: Either party can withdraw the full amount at any time
  • Yield Generation: Bonded tokens are deposited into Aave to generate yield
  • Trust Quantification: The bond amount represents the level of trust between parties
  • Sybil Resistance: Integration with Gitcoin Passport ensures genuine user identities

Bond States

Active Bond

  • Both parties have matching deposits
  • Tokens are generating yield in Aave
  • Either party can initiate withdrawals
  • Bond details are tracked: partner addresses, amount, creation time, and last update

Broken Bond

When trust is violated or a relationship needs to end:

  • Either party can unilaterally break the bond
  • Incurs a higher penalty (4% break fee) compared to mutual withdrawal
  • Remaining funds are returned to the breaker
  • The bond relationship is permanently terminated

Economic Mechanisms

Fee Structure

The project implements different fee levels to incentivize positive behavior:

  • Withdrawal Fee (1%): Applied when both parties mutually agree to withdraw
  • Break Fee (4%): Higher penalty for unilateral bond breaking
  • Fees contribute to the community pool, supporting the project's sustainability

Yield Generation

  • Bonded tokens are automatically supplied to Aave's lending pool
  • Participants earn higher-than-market-average yields on their locked tokens
  • Yield serves as an incentive for maintaining long-term trust relationships

Social Reputation

On-chain Trust Network

  • Each bond creates a verifiable trust connection between addresses
  • Bond amounts indicate trust levels between participants
  • Network of bonds forms a map of trust relationships in the ecosystem

Identity Verification

  • Integration with Gitcoin Passport for Sybil resistance
  • Minimum score requirement (20) ensures legitimate participants
  • Combines off-chain identity verification with on-chain actions

Public Good Aspects

Non-excludable Access

  • Anyone meeting the minimum Passport score can participate
  • No privileged access or special permissions required
  • Open source and transparent implementation

Community Benefits

  • Creates a new primitive for establishing trust in Web3
  • Enables reputation building through verifiable actions
  • Supports coordination and collaboration in decentralized systems
  • Fee structure maintains system sustainability

Technical Safeguards

Security Measures

  • Pause mechanism for emergency situations
  • Access controls for administrative functions
  • Economic penalties to discourage malicious behavior
  • Score-based participation requirements

Smart Contract Integration

  • Seamless integration with Aave for yield generation
  • ERC20 token compatibility
  • Gitcoin Passport integration for identity verification

Contract

Overview

The TrustBond contract is a decentralized system that enables users to create trust-based bonds with other users by locking tokens. It leverages AAVE's lending pool to generate yield on the locked tokens. The system provides functionality for creating bonds, withdrawing funds, and breaking bonds, with various security measures and fee structures in place.

Key Components

External Integrations

  • AAVE Pool: Used for lending/borrowing functionality
  • Gitcoin Passport Decoder: Provides score verification for sybil resistance
  • ERC20 Tokens:
    • Base token for bonding
    • AAVE's aToken for yield generation

Core Data Structure

struct Bond {
    address partner;      // The address of the bonding partner
    uint256 amount;       // Amount of tokens locked in the bond
    uint256 createdAt;    // Timestamp of bond creation
    uint256 lastUpdated;  // Timestamp of last update
}

Contract Functions

Administrative Functions

Constructor

constructor(
    address owner,
    IGitcoinPassportDecoder passportDecoder,
    IPool pool,
    IERC20 token,
    IERC20 atoken
)
  • Initializes the contract with essential components
  • Sets initial withdrawal fee (1%) and break fee (4%)

Fee Management

  • setFee(uint256 newFee): Sets the general fee (currently under review)
  • setWithdrawalFee(uint256 newFee): Sets the fee for withdrawals
  • setBreakFee(uint256 newFee): Sets the fee for breaking bonds

Security Controls

  • pause(): Pauses all contract operations
  • unpause(): Resumes contract operations
  • isPaused(): Returns current pause status

Core Bond Functions

Deposit

function deposit(uint256 amount, address partner) external

Before calling the deposit function, users must first approve the TrustBond contract to spend their tokens:

// First approve the TrustBond contract to spend tokens
token.approve(trustBondAddress, amount);
// Then make the deposit
trustBond.deposit(amount, partner);

Requirements:

  • Amount must be greater than 0
  • Sufficient balance and allowance:
    • User must have enough tokens in their wallet
    • User must have approved the TrustBond contract to spend their tokens
  • Cannot bond with yourself (sender address cannot be the same as partner address)
  • Both parties must have valid Gitcoin Passport scores:
    • Both sender and partner must have a score ≥ 20
    • This prevents Sybil attacks and ensures user legitimacy

Process:

  1. Validates all requirements (reverts if any check fails)
  2. Transfers tokens from sender to contract
  3. Supplies tokens to AAVE pool for yield generation
  4. Creates or updates bond record:
    • If no existing bond: Creates new bond with specified amount
    • If existing bond: Updates amount and lastUpdated timestamp

Example usage:

  1. Creating bond without passport:
sequenceDiagram
       participant User
       participant TrustBond
       participant PassportDecoder

       User->>TrustBond: deposit(100, partner)
       TrustBond->>PassportDecoder: getScore(user)
       PassportDecoder-->>TrustBond: score < REQUIRED_SCORE
       TrustBond-->>User: Revert: insufficient passport score
  1. Creating bond with user without passport:
sequenceDiagram
       participant User
       participant TrustBond
       participant PassportDecoder

       Note over User: User has valid score
       User->>TrustBond: deposit(100, partner)
       TrustBond->>PassportDecoder: getScore(partner)
       PassportDecoder-->>TrustBond: score < REQUIRED_SCORE
       TrustBond-->>User: Revert: partner has insufficient score
  1. Successful bond creation:
sequenceDiagram
       participant User
       participant TrustBond
       participant PassportDecoder
       participant Token
       participant AAVEPool

       Note over User,PassportDecoder: Both user and partner have valid scores
       User->>Token: approve(trustBond, 100)
       User->>TrustBond: deposit(100, partner)
       TrustBond->>PassportDecoder: getScore(user)
       PassportDecoder-->>TrustBond: score ≥ REQUIRED_SCORE
       TrustBond->>PassportDecoder: getScore(partner)
       PassportDecoder-->>TrustBond: score ≥ REQUIRED_SCORE
       TrustBond->>Token: transferFrom(user, trustBond, 100)
       TrustBond->>AAVEPool: supply(100)
       TrustBond->>TrustBond: Create/update bond record
       TrustBond-->>User: Emit BondCreated event

Bond State After Deposit: After a successful deposit, you can query the bond state:

Bond memory bond = trustBond.bond(sender, partner);
// bond.partner == partner address
// bond.amount == deposited amount
// bond.createdAt == timestamp of creation
// bond.lastUpdated == timestamp of last update

Events Emitted:

  • BondCreated(address indexed partner1, address indexed partner2, uint256 amount): Emitted when a new bond is created or updated

Withdraw

function withdraw(address partner) external

Requirements:

  • Both parties must have active bonds
  • Bond amounts must match

Process:

  1. Withdraws tokens from AAVE pool
  2. Applies withdrawal fee (1%)
  3. Distributes tokens to both parties

Break Bond

function breakBond(address partner) external

Process:

  1. Withdraws total bonded amount from AAVE pool
  2. Applies break fee (4%)
  3. Returns remaining tokens to the breaker

View Functions

Bond Information

  • bond(address partner1, address partner2): Returns bond details between two partners
  • bonds(address user): Returns array of all bonds for a user

Fee Information

  • fee(): Returns general fee
  • withdrawalFee(): Returns withdrawal fee percentage
  • breakFee(): Returns bond breaking fee percentage
  • communityPoolBalance(): Returns contract's token balance

Score Functions (To Be Implemented)

  • personMultiplier(address user)
  • score(address user)

Security Features

  1. Access Control

    • Owner-only functions protected by onlyOwner modifier
    • Emergency pause mechanism

  2. Sybil Resistance

    • Integration with Gitcoin Passport
    • Minimum score requirement

  3. Economic Security

    • Fee mechanisms to discourage malicious behavior
    • Withdrawal and break fees

Constants

  • REQUIRED_SCORE: 20 (Minimum Gitcoin Passport score)
  • Withdrawal Fee: 1%
  • Break Fee: 4%

Events

The contract emits the following events:

  • FeeUpdated(uint256 newFee)
  • CommunityPoolDeposited(uint256 amount)
  • CommunityPoolWithdrawn(uint256 amount)
  • RewardsWithdrawn(address indexed user, uint256 amount)
  • BondCreated(address indexed partner1, address indexed partner2, uint256 amount)
  • BondBroken(address indexed breaker, address indexed partner, uint256 amount)
  • Paused(bool paused)

Frontend Documentation

Project Context

This project was initially created as part of the Modular Carnival Hackathon in Belo Horizonte, Brazil. The codebase is currently under active development and will be receiving updates and improvements.

Technical Stack

The frontend application is built using modern web technologies:

  • Framework: Next.js 14.2
  • Language: TypeScript
  • UI Components: Custom UI library (@repo/ui)
  • Web3 Integration:
    • RainbowKit v2 for wallet connection
    • Wagmi v2 for Ethereum interactions
    • Viem 2.23 for blockchain interactions
  • State Management & Data Fetching: TanStack Query (React Query) v5

Project Structure

The frontend is organized as part of a monorepo structure with shared configurations for:

  • ESLint
  • TypeScript
  • Tailwind CSS

Development

To run the project locally:

# Install dependencies (from root directory if using monorepo)
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

Environment Setup

The project uses dotenvx for environment variable management. Make sure to:

  1. Create a .env.local file in the root directory
  2. Add necessary environment variables
  3. The development server will automatically load these variables

Code Quality

The project maintains code quality through:

  • TypeScript for type safety
  • ESLint for code linting
  • Built-in type checking scripts

To run type checks:

pnpm type-check

Styling

The project uses Tailwind CSS for styling with a custom configuration shared across the monorepo (@repo/tailwind-config).

Roadmap

Here's our audacious plan:

  • Q2/2025 Full testnet implementation with testnet passport and frontend
  • Q3/2025 Launch website with custom domain and full documentation
  • Q3/2025 Community engagement
  • Q4/2025 Mainnet launch
gantt
    title Trust Bonds Project Timeline
    dateFormat  YYYY-MM
    axisFormat %Y-%m

    section Development
    Full testnet implementation     :2025-04, 3M
    Launch website & docs          :2025-07, 3M
    Community engagement          :2025-07, 3M
    Mainnet launch               :2025-10, 3M