🛰️ TrustBridge

Preventing PAYMENT_NO_TRUST failures in Stellar-powered open source contribution workflows.

TrustBridge is an open source toolchain that ensures contributors in Stellar-funded open source programs — such as Stellar Community Fund waves and Soroban Quest bounties — have valid USDC trustlines and sufficient XLM reserves before payout time.

We eliminate the silent failure: contributor gets assigned, does the work, wave ends — and the payout bounces.

Stellar-based open source incentive programs (like SCF Dev Waves) pay contributors in USDC at the end of each wave. But a Stellar payment fails with a PAYMENT_NO_TRUST error if the recipient hasn't manually established a USDC trustline on their account.

This creates a painful, invisible failure mode:

❌  Wave ends
❌  Automated payout triggered  
❌  tx fails → PAYMENT_NO_TRUST
❌  Contributor goes unpaid
❌  Maintainer has to manually chase and retry

No error is surfaced to the contributor. No warning is given at assignment time. The problem only surfaces after the work is done.

TrustBridge fixes this at the source — the moment a contributor is assigned to an issue.

This organisation hosts three repositories that work together as a complete system:

┌─────────────────────────────────────────────────────┐
│              Contributor Flow                        │
│                                                      │
│  1. Contributor registers their Stellar G-address    │
│     via trustbridge-dashboard (GitHub OAuth)         │
│                                                      │
│  2. Address is saved to Soroban contract on-chain    │
│     (trustbridge-contract)                           │
│                                                      │
│  3. Contributor is assigned to a GitHub issue        │
│                                                      │
│  4. trustbridge-action fires automatically           │
│     → Queries Horizon API for their account          │
│     → Checks: account funded? trustline set? XLM ok? │
│                                                      │
│  5a. ✅ All good → issue comment: "Ready for payout" │
│  5b. ❌ Issue found → issue comment with exact steps │
│       to fix (add trustline, fund account, etc.)     │
└─────────────────────────────────────────────────────┘

The maintainer never has to chase contributors manually. The contributor knows exactly what to fix, right on the issue — at the time of assignment, not the time of payment.

The core product. A GitHub Action written in TypeScript that integrates directly into any repository's CI.

What it does:

• Triggers on issues: [assigned] events
• Looks up the contributor's registered Stellar address from trustbridge-contract or a configured input
• Calls the Stellar Horizon API to validate the account
• Checks for USDC trustline existence
• Checks for minimum XLM reserve (default: 1.5 XLM)
• Posts a formatted Markdown comment on the issue with status badges and remediation links
• Optionally fails the CI (fail_on_missing: true) to block assignment until the contributor is ready

Quick setup in your repo:

# .github/workflows/trustline-check.yml
name: Trustline Pre-Flight Check

on:
  issues:
    types: [assigned]

jobs:
  check-trustline:
    runs-on: ubuntu-latest
    steps:
      - uses: trustbridge-stellar/trustbridge-action@v1
        with:
          stellar_address_input: ${{ steps.lookup.outputs.address }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          fail_on_missing: true

A Next.js web application with two audiences: contributors who register their Stellar address, and maintainers who monitor wave payout readiness.

Contributor view:

• GitHub OAuth login
• Register or update your Stellar G-address
• Live trustline status checker with real-time Horizon API feedback
• Step-by-step guide to create a USDC trustline (Lobstr, Stellar Lab)

Maintainer view:

• Full table of all registered contributors
• Colour-coded payout readiness: ✅ Ready / ⚠️ Low Reserve / ❌ Not Ready
• "Re-check all" button for batch Horizon queries
• CSV export for wave payout preparation

Live instance: https://trustbridge.stellar.community (coming soon)

A Soroban smart contract deployed on Stellar that serves as the decentralised, on-chain registry mapping GitHub usernames to Stellar G-addresses.

This is the trust layer. Instead of relying on a centralised database, the mapping lives on-chain — verifiable, permissionless, and permanent.

Contract functions:

• register(github_username, stellar_address) — contributor registers their address (proves ownership via signature)
• get_address(github_username) → returns the registered Stellar address
• verify(github_username) — admin marks a contributor as identity-verified
• get_all_registered() — admin batch lookup for the dashboard
• get_stats() — total and verified contributor counts

Deployed on:

• Testnet: C... (address TBD on deployment)
• Mainnet: C... (address TBD on deployment)

1. Visit the TrustBridge Dashboard
2. Sign in with your GitHub account
3. Enter your Stellar G-address
4. Check your trustline status — fix any issues shown
5. You're ready for automated payouts ✅

1. Add the action to your .github/workflows/ directory (see snippet above)
2. Configure inputs for your asset (USDC by default)
3. Point stellar_address_input at your registry of choice (on-chain contract or dashboard API)
4. That's it — contributors get alerted automatically on assignment

See individual repository READMEs for full local development setup:

• trustbridge-action — local dev guide
• trustbridge-dashboard — local dev guide
• trustbridge-contract — local dev guide

TrustBridge was built specifically to support the Stellar Soroban open source contribution ecosystem, including:

• Stellar Community Fund (SCF) — wave-based grants paid in USDC
• Stellar Quest — bounty-style learning rewards
• Any GitHub-integrated project paying contributors via Stellar

The PAYMENT_NO_TRUST error is documented in the Stellar developer docs but has no automated prevention mechanism in existing tooling. TrustBridge fills that gap.

We welcome contributions to any of the three repositories. TrustBridge itself is built with the same open-source contributor workflow it is designed to protect.

Before contributing:

1. Register your Stellar address on the TrustBridge Dashboard so you're ready for any future USDC bounties
2. Read the CONTRIBUTING.md in the relevant repository
3. Look for issues tagged good first issue or help wanted

Contribution areas:

• 🐛 Bug fixes and edge case handling in the Horizon API integration
• 🌍 Support for assets beyond USDC (e.g. EURC, AQUA, yXLM)
• 🔌 Integrations with other GitHub project management tools (ZenHub, Linear)
• 📖 Documentation and translated guides for non-English contributors
• 🧪 Test coverage improvements across all three repos

If you discover a security vulnerability in any TrustBridge repository, do not open a public issue. Please email security@trustbridge.dev with details. We follow responsible disclosure and will acknowledge reports within 48 hours.

All TrustBridge repositories are released under the MIT License unless stated otherwise in the individual repo.

Built with and for the Stellar developer community. Thanks to the Stellar Development Foundation for Soroban, the Horizon API, and the open infrastructure that makes projects like this possible.