Trinary v2.0

[otech47]

Potential Features

Project Administration & Reporting

• Creating projects & clients
• Viewing insights for a project

Budgeting

• Allocating funds to different contributors to create budget reports
• Negotiating rates with contributors to compensate them for their work
• Funding allocations with BTC on-chain or lightning

Bitcoin-native Payment Disbursements

• Configuring BTCLN node(s) for the platform & other contributors
• Creating payments via BTC transactions + LN invoices
• Connecting an external node to receive payments as a contributor

Funding Github Repos & Contributors

• Browsing Github projects & contributions
• Sending sats to a Github repo
• Sending sats to a Github profile for their contributions
• Sending sats to a Github issue

Design Goals

• Define Trinary's core features so that anyone in the world can use it as a platform to coordinate human resources
• Establish a UX for Contributors
• Improve the UX for Admins to organize projects and allocations with a simple way for Contributors to interact with the Admin's project allocations
• Enable Contributors to be paid in BTC using a dedicated BTCLN wallet node. This can be their own node or they can choose to spawn a secure cloud node to use to collect BTC rewards

User Stories

Project Administration

• As an Admin, I want to create a new project so that I can start planning out a budget and timeline
• As an Admin, I want to generate a report for a project so that I can present project status updates to interested parties (customers, investors, owners, etc)
• As an Admin, I want to facilitate payment transactions from clients to contributors so that I prove that rates / terms of allocations are being respected

Budgeting

• As an Admin, I want to see a list of Contributor Github profiles so that I can propose an allocation of money to pay them for their time
• As an Admin, I want to invite a Contributor to review an allocation proposal so that we can engage in a paid work collaboration
• As a Contributor, I want to review the allocations that have been proposed to me, so that I can decide whether to accept or counter with different terms
• As a Contributor, I want to review the allocations I've agreed to so I can confirm how to spend my time working
• As a Contributor, I want to create or edit allocations so that I can negotiate which allocation should become funded

Bitcoin-native Payment Disbursements

• As a Contributor, I want to configure a bitcoin wallet so that I can receive payments for my allocations directly
• As an Admin, I want to make sure all Contributors have bitcoin wallets enabled so that I can execute instant BTC payouts & bonuses

Notes

• Improve BTC/LN integration
• Create a UX for contributors
• Provide useful reporting insights
• Implement permissions on projects/clients

[otech47]

#700

[otech47]

UIUX Flowcharts for Contributors

[otech47]

Contributor UX starts when an Admin creates an Allocation and wants the Contributor to review the proposed terms

• Should the Allocation creation trigger the notification/interaction with Contributor? OR should there be a separate event... draft allocations???

A. Contributors can be invited by email without ever having signed up on Trinary
B. Existing contributors on Trinary

[otech47]

What should the Home page (directly after login) look like when there are 0 projects linked to the logged in Contributor? Create new projects and create new payments

What should the Home page look like after projects & payments are created?
Should all Contributors be able to see payments created? Or only their allocations from the payment?

[otech47]

What should the core navigation be? Currently it is:

• Clients
• Projects
• Contributors
• Account

[otech47]

#692 #693

[otech47]

Permissions System

[otech47]

Test thoroughly how the current functions work

[otech47]

Permissions API seem largely in place. We should add some testing suites to track API functions

We need to add DirectiveResolvers to protect queries and mutations to make changes that are not authorized according to permissions records (ex: check a Contributor has access to a project before fetching project details

Frontend UI does not respect these permissions currently

[otech47]

Data model and API functionalities are already mostly in place but we need enforcement

Currently anyone can make requests to projects and clients eve though they don't have permission

We need to protect APIs with permission checks

[otech47]

How do we model a Contributor actually receiving a payment?

[otech47]

We could use the Allocation.date_paid column....

should we create a stronger data relation here? Like a transaction ID or an LN invoice ID?

Perhaps we add a payment_proof column to the Allocations table that can be independently verified by anyone (BTC txn or LN invoice) to confirm it was paid

[otech47]

Alternate approach:

Use the Payments table to record payments made to Contributors?

• we would lose the link to the Allocation... more complexity...

[otech47]

BTCLN Architecture

Current Model

BTCPayServer API keys are currently required to enable BTC payments (on-chain + lightning).

When a BTCPS invoice is fulfilled, the Payment.date_paid is timestamped but the funds go directly to the BTCPayServer configured on the Trinary API instance. Let's consider the state of the Payment at this point "activated"

When creating a project and funding the first payment, users should understand what trust model they are using

1. Custodial

• When sending BTC to activate Payments, the user must trust the server hosting the configured BTCPayServer not to steal funds

2. Self-Hosted

• Trinary source code (FOSS) can be deployed with a private DB + application server. The BTCPayServer API keys can be configured for a BTCPS instance controlled by the user

---

Can proof of the balance in a private channel serve as proof that funds are secure?

[otech47]

Taro

• Creating a budget for a project would be represented with minting a Taro asset (on-chain fee must be paid?)
• What is the trust model for a Project Admin and contributors? Can the Project Admin steal the funds at any time? Is this acceptable?

Galoy

• All contributors would use an account-based wallet to receive BTC

Fedimint

• Replace the SuperAdmin with a federation
• Does this make sense since privacy is a key feature? Project Admins may want transparency in the distribution so this may not fit the use case

[otech47]

Trinary SuperAdmin = the entity hosting Trinary + default BTCPS instance

In the current custodial model, we can consider "Payout Requests" where a contributor who has not configured any kind of BTC LN node, can simply submit a BTC address/LN invoice and request to be paid. The application logic may be able to automatically process the payout depending on Allocation data

Node Configuration

Project Admins

• As a project admin, I want to be able to configure my own BTCLN/BTCPS so that I don't have to rely on the central custodian hosting Trinary to secure funds and process payouts
• If we allow PAs to configure their own nodes to receive payments, we would need to be able to generate BTC addresses and LN invoices on their behalf to show in the Trinary UI when payments are made

Contributors

• As a contributor, I want to be able to configure my own node, so that I can receive payouts directly to my wallet

Team Bonuses

• Project Admin is the authority who initiates a bonus payout
• How do we facilitate a permissionless set of transactions to minimize trust on the Trinary SuperAdmin
• What happens if the contributors don't have a node configured? Can we still distribute bonuses?
• Are there any other conditions for distributing the bonuses?

[otech47]

Contributor Wallet Configuration

As a contributor, I want to set up my bitcoin/lightning wallet so that I can be ready to receive payments.
As a contributor, I want to further configure my wallet so that I can reduce the required trust in the Trinary SuperAdmin custodian.

What is the default state for a contributor's wallet?

• Funds go directly to the Trinary SuperAdmin and the sender is fully trusting them to distribute/allocate the funds to the contributor who should receive it
• Basic fields for withdrawing all funds so that a contributor can input a BTC address or LN invoice

Configuration options

1. Connect your own node to grant Trinary permission to create invoices and addresses on your behalf (invoice macaroon in LND)
2. Automatically spawn a Voltage node instance and connect invoice macaroon
3. Provide BTCPayServer API keys to generate fresh addresses/invoices
4. Set a static BTC address for all on-chain payments (UI should include guidance on privacy sacrifice)

Payment Proofs

Currently, the contributor must set up a BTCPayServer instance and provide us API keys

SuperAdmin/Platform Node Configuration

Currently, BTCPayServer instance + API keys are the only requirements

How do we allow for hosting your own Trinary instance with a non-BTCPayServer node setup

Ideas

Time-locked Payments??

• Socially-enforced
  • Project Admin (PA) is fully in control of the funds
  • PA decides whether to send funds to the Contributor or return the funds to the Payer
• Timelock-enforced
  • we can't accomplish this unless the funds are already inside a custom wallet that can specify timelocks in the txn

[otech47]

Project Creation Flow

• Enter basic details
  • project name
  • github
• Establish timeline
  • start date
• Establish budget
  • create first payment(s)
  • budget
• Invite contributors
  • create first allocation(s)
  • both new and existing contributors can be invited

Notes

Does a project need to have a start date?
Do contributors need to have an Allocation for a project or can they just be invited to a project?

[otech47]

4 stages

1. UIUX
2. Permissions System
3. BTCLN Integration
4. Data model refactors

[rishkwal]

Data Model Change Proposal

• Add lightning_pub_key to Contributors
• Add payment_type to Contributors
• Change date to start_date in Projects
• Add project_id to Payments
• Add public to Permissions (public/private) for Projects
• Create table for phases (Timeline View)

[otech47]

Payments and Projects should be independent of Clients

• allow Project.client_id to be nullable
• allow Payment.client_id to be nullable
• add Payment.project_id field (nullable)

Project budgets might have different currencies (currently determines currency via Client.currency

• alter Project.expected_budget_currency and Project.expected_budget_amount
  OR
• create new Budgets table with fields amount, currency, and project_id fields

[rishkwal]

Overview

Four Phases of Development

• UI/UX
• Data Model Refactoring
• Permission System enforcement
• BTC/LN Integration

Trinary v2.0 Features

• Sign Up
  • Users can Sign Up via GitHub
• Creating Projects
  • Projects are tied with a GitHub repository link(it should be possible to create multiple projects with same github link)
  • Projects can be planned on a timeline and labels/phases can be added for a better planning and overview
  • User can Link multiple GitHub issues to those phases
  • Generation of reports for projects
  • Projects can be public or private
• Inviting Contributors to Projects
  • Contributors can be invited via email
  • Money can be allocated to contributors
  • Contributors are allowed to counter the allocation, accept it, or reject it
  • Contributors are allowed to propose a new allocation
• Creating Clients and Linking them to Payments that can be allocated
  • We should be able to create Payments independent of clients
• Funding allocations
  • BTC/Lightning Integration(https://whimsical.com/trinary-2-0-btc-lightning-Azw3sX6d4y5M4RrUrLsWjF)
  • Contributors have a btc/lightning address associated with their accounts

Permissions

1. Project admin:
   a. Creator of the project is by default the admin
   b. They can add phases to timeline
   c. They can accept, reject or counter allocations that are proposed by a contributor
   d. They can fund allocations
   e. They can change other settings for the
   f. They can switch the visibility of the project to public or private

2. Project contributor:
   a. They can accept, reject or counter allocations that are proposed by a contributor
   b. They can view the Project details

Data Model:

https://www.figma.com/file/qgGWXmprU7vTv7guzWzvML/Project-Trinary?node-id=3895%3A11917

UI/UX

https://www.figma.com/file/qgGWXmprU7vTv7guzWzvML/Project-Trinary?node-id=3314%3A3381

Major Changes(code)

• Adding the Timeline View along with a Phases Table
• Completing and applying the permission systems
• Integrating BTC and Lightning Payment system

[otech47]

Notes

Consider a custodial "community banking" solution using the Galoy stack

Pros

• easy, setup and UX... no need to bother with imported keys, macaroons, etc

Cons

• lack of optionality for the user
• expensive in production ($100-$500+ monthly)

---

Somewhere in the UX there might be an option to select a trust model:

1. Send to escrow (server hosting Trinary platform holds the funds... consider a refundable timelock?)
2. Commit funds to channel (opens a channel to Trinary)
3. Send directly to contributor wallet? or admin wallet?

[otech47]

UIUX Planning

User Personas

https://www.figma.com/file/qgGWXmprU7vTv7guzWzvML/Project-Trinary?node-id=4064%3A13325

Onboarding

For users that are only interested in funding projects and/or contributors (Funder), we don't really need to capture any information from them, but we should explain how the platform helps them do this.

Navigation

• Nav Items

  • Dashboard
  • Profile/Account/Contributor Detail (of your own user)
  • Fund FOSS Page
    • for browsing projects and contributors (see https://geyser.fund/ for inspiration)
    • intended to make it as easy as possible to send money to a Project Admin or a Contributor directly
    • Contributor List
      • List of Contributor Tiles
      • Indicate which contributors have registered on Trinary but also show public contributors fetched on Github
    • Project List
      • shows all projects created on Trinary and set to public by the Project Admin

• Landing Page

• Login Page

• Onboarding Guidance Page(s)

• Home Page

  • the home page is going to have a variety of states depending on how many projects/allocations the user has
  • if there are 0 projects, the main calls to action should be:
    • create a project button => opens the project creation flow
    • Fund FOSS => navigates to Fund FOSS page
  • navigation hamburger is always in the top right

Views

Funder Guidance Page

This page is part of the onboarding UIUX and is purely informational

List of Projects to Fund

As a Funder, I want to view a list of projects that have been set to public so that I can directly make payments to the Project Admin

List of Contributors to Fund

As a Funder, I want to view a list of contributors so that I can directly make payments to them.

[otech47]

UIUX Flowchart v2.pdf

[otech47]

• Contributor has not set up their wallet, has 0 accepted allocation, and $0 in their wallet balance

  • accepting the allocation would trigger the Wallet Setup flow
  • they can also trigger the Wallet Setup flow manually without accepting

• Contributor has not set up their wallet, has 0 accepted allocation, and $100 in their wallet balance

  • show the user that someone sent them money but they have to complete Wallet Setup flow before being able to spend it? or allow them to spend but annoy them?
  • this should not be possible... contributors must set up their wallet before we allow anyone to send them money, this removes custodial risk

• Contributor has not set up their wallet, has 1 accepted allocation, and $100 in their wallet balance

  • this should not be possible, the Wallet Setup flow must be completed before the allocation is allocated

Wallet Setup flow

User is presented with a few buttons

• 1. Simple: Download External Wallet > Provide an on-chain BTC address
• 2. Advanced: Connect your Node / Provide an invoice macaroon to be able to generate invoices
• 3. Federated (only if the PA has enabled it?): Spawn your own Voltage node

Simple

• Targeted for users who have never interacted with Bitcoin or maybe have downloaded a wallet already but may not be sure how to create addresses
• Explain to the user that we need at a minimum a BTC address to link to their account
• They can create bitcoin addresses by downloading a wallet
• Show a list of recommended wallets
  • Muun
  • Bluewallet
  • Wallet of Satoshi
• How do we communicate to the user how to receive payments over lightning and what extra setup is needed

Advanced

• Targeted for users who already run their own node
• Should we provide guidance to the user on how to run their own node?
• We need a way to generate both LN invoices & new BTC addresses
  • if they provide BTCPayServer API keys, we can do this already

Federated

• This option is only available if the PA has enabled it and if the contributor has at least 1 allocation (does not have to be accepted)
• PA UX
  • has to provide Voltage API keys to be able to offer this option for all invited contributors
  • needs to have a balance paying for each node
  • how do we handle insufficient credits / billing issues on Voltage?
  • should be able to see which contributors have selected this option
• Contributor UX
  • Guidance explaining what is happening as we spawn the Voltage node
  • Should be able to access credentials

[rishkwal]

FOSS Integration

• BTCPayServer
  • For processing Invoices and tracking payments
  • https://docs.btcpayserver.org/API/Greenfield/v1/
• Voltage API
  • For setting up contributor LND nodes
  • https://api-docs.voltage.cloud/
• LNBITS
  • Leveraging the LNBITS extensions to provide a wide range of functionalities to admin and contributor
• Alby
  • https://guides.getalby.com/alby-wallet-api/reference/authorization
  • To allow the connection of Lightning wallet directly to the application and spending sats through it for various activities
• Sphinx Relay
  • https://github.com/stakwork/sphinx-relay
  • For allowing organizations to run their own version of Trinary leveraging the Lightning Network

[otech47]

Value Proposition

• project management tooling
• team organization

Innovation

• bitcoin-native payments for gamification/bonuses/incentives

BTCLN Integration

• contributors set up their own wallets
• central server node is required

[rishkwal]

Tentative Features for LL Demo

Target Version

• Onboarding Flow
• Login Flow
• Empty State Dashboard with List of Projects + Preview of Setup Wallet (coming soon)
• Project Creation Flow (Github-integrated list of repos + basic detail fields)
• Project Detail Page with info + Add Payment
• Create Payment flow with BTCPayServer integration

---

After Demo / Later Versions

• Allocation Proposal
• Contributor Profile
• BTC Payment: (Simple Option + LND Personal Node setup)
• Other Dashboard features
• Rate Negotiation
• Federated Option(Voltage.cloud)
• Advanced GitHub Integration(Connecting Issues and Milestones, etc)
• TImeline View for Projectes
• Client Integration