Functional Specification: Token Payments via SAFE Multisig (1)

Project Name:

CollabBerry Token-Powered Payment Automation

Author:

CollabBerry Tech Product Specialist

Last Updated:

June 10, 2025

1. Overview

This specification describes a system that enables organizations using CollabBerry to automate contributor payouts using:

Stablecoins (e.g. USDC, DAI, USDT) for Monetary Compensation, based on contributor agreements

DAO-native ERC-20 tokens for Team Points (TP)based recognition

Payouts will be executed via Gnosis SAFE multisig wallets, initiated from within the CollabBerry admin interface.

Goals

Implement UI and backend logic to support token-based payout automation.

Allow integration with custom ERC-20 smart contracts for minting or transferring tokens based on Team Points.

Ensure a secure, transparent, and admin-governed flow for monthly distributions.

2. Feature Scope

Core Functionalities

Feature	Description
TP-weighted Payout Engine	Uses monthly calculated outputs in TP and USD to prepare transfer transactions
Stablecoin Payments	Transfers exact USD-denominated amounts in stablecoin from SAFE multisig to contributors
Token Recognition Distribution	Transfers (or mints, if applicable) exact TP amounts in DAO-native tokens
SAFE Multisig Integration	Builds and sends transactions to SAFE via SDK or deeplink
Admin UI	Dashboard to preview and trigger token and stablecoin distributions

3. Data Flows

3.1 Inputs

From CollabBerry:

TP output per contributor (e.g., Alice: 1200 TP)

USD output per contributor (e.g., Alice: $230)

From Org Admin via UI:

Gnosis SAFE wallet address

Token contract address (for TP-based token)

Stablecoin token contract address (e.g. USDC)

3.2 Outputs

Transaction bundle for SAFE:

ERC20.transfer(address to, uint256 amount) for stablecoin payments

ERC20.transfer(address to, uint256 amount) or custom mint() calls for DAO tokens

4. User Stories

Org Admin

Can preview transactions, export distribution breakdown, and trigger SAFE proposals

Can execute token and stablecoin transfers with a single click or two distinct buttons ?

Contributor

Sees past and current payment breakdowns

Gets token payouts automatically upon SAFE execution

5. Token Distribution Logic

CollabBerry generates exact amounts for each contributor:

TP Token Amount: Sent as-is, per round result (e.g. let’s assume a Dynamic Pooling logic)

Dynamic Pool vs. Fixed Pool

Stablecoin Amount: Sent as-is, based on monetary agreement (e.g. $230 → 230 USDC)

The amounts come directly from the round’s evaluation and agreement terms.

6. SAFE Multisig Integration

Tools

safe-core-sdk for transaction creation

Transaction batch via SafeTransactionData[]

Optional: Deep-linking to SAFE app with safe:// URI for review/signature

Requirements

CollabBerry generates exact transaction payloads

Admin signs transactions via SAFE UI

Support for up to 200 recipients in one batch

7. Architecture

Backend

Fetch payout data from compensation logic (TP + USD)

Format ERC20 transfer or mint transactions

Validate token balances or minting permissions

UI

Admin: Configure token and SAFE address, preview payout transactions, and execute

Contributor: View payout history, token and USD equivalent

Libraries

ERC-20 ABI helper for encoding transactions

Token balance checker for SAFE

Gnosis SAFE SDK integration layer

8. Edge Case Handling

Scenario	Handling
Insufficient SAFE balance	Warn admin before submission
Rounding dust	Round down and return dust to treasury
Custom token contract fails	Log error and skip affected user

9. Non-Functional Requirements

Category	Specification
Security	Only admin roles can trigger payouts. Transactions require SAFE signature.
Auditing	Downloadable JSON and CSV transaction breakdown
Performance	Batch distribution to up to 200 contributors per cycle
Compatibility	ERC-20 token standard and Gnosis SAFE supported

10. Open Items / Decisions Needed

Will CollabBerry request and manage mint allowance or rely on admin to do so manually?

Should token and stablecoin payouts be one or two buttons in the UI?

How do we handle compliance for fiat-equivalent reporting?

11. Future Extensions

Superfluid or Sablier-style streaming integration for continuous payments

Integration with CollabBerry agreements module to generate payouts automatically

IPFS proof of payout snapshot

12. Appendix: Example Payload

{
  "safeAddress": "0x...",
  "tokens": [
    {
      "type": "stablecoin",
      "symbol": "USDC",
      "address": "0x...",
      "recipients": [
        {"wallet": "0xabc", "amount": "230000000"}
      ]
    },
    {
      "type": "recognition",
      "symbol": "ORG",
      "address": "0x...",
      "recipients": [
        {"wallet": "0xabc", "amount": "1200000000000000000000"}
      ]
    }
  ]
}

13. Estimates

Frontend Efforts

Settings Page Update

Add fields: stable token address, recognition token address

Validate token addresses

Execute Payment Buttons

Add two buttons: Send Stable Payment, Send Token Payment

Connect buttons to backend endpoints

Preview & Confirmation UI

Show transaction summary or Safe deeplink

Contributor Payment History

Show status or block explorer link if available

Backend Efforts

Org Settings Update

Extend schema to store token addresses (stable + TP token)

SAFE SDK Integration

Build batch transfer() payloads per token

Support multiple token types (stablecoin, DAO token)

Transaction Builder API

Create endpoint to generate transactions for current round

Return transactions to frontend for approval via Safe

Validation & Safety Checks

Validate token balance in SAFE

Handle missing wallets or token transfer errors