Funding Groups

A funding group is a pre-approved charitable cause or organization registered with the protocol. Products can allocate a percentage of mint revenue to one via a FUNDING_GROUP contribution.

Schema

interface FundingGroup {
  id: number;
  name: string;
  description: string | null;
  stxAddress: string | null;
  status: FundingGroupStatus;
  website: string | null;
  createdAt: string;
}

type FundingGroupStatus =
  | "PENDING" | "APPROVED" | "VERIFIED" | "REJECTED" | "SUSPENDED";

Approval workflow

1. Group applies (status: PENDING)
2. Admin approves (APPROVED) or rejects (REJECTED - terminal)
3. On-chain proof upgrades to VERIFIED
4. Admins can SUSPEND and restore to APPROVED/VERIFIED

Only APPROVED or VERIFIED groups can be referenced in a contribution.

Using a funding group

Allocations are fixed when the product is created, in the contributions input, and frozen on deploy. There is no add-after-deploy - once the contract is live the splits are immutable.

await rtClient.smartProducts.createPage({
  // ...page fields
  contributions: {
    fundingGroups: [
      { id: 42, percentage: 5 }, // 5% of every mint to approved group #42
    ],
  },
});

You supply only the group id and percentage. The server resolves the group's payout address and derives the recipient, so a creator can never point a FUNDING_GROUP cut at an arbitrary address.

On-chain settlement

The group's stxAddress is written into the unified creator-info map at contract deploy time, alongside the creator, template-artist, sticker-artist, and collaborator entries. distribute-fees pays every entry on each mint, and the Chainhook position-verifier reads them back by frozen position. The FUNDING_GROUP vs creator distinction lives off-chain in ProductContribution.role - on chain it is just another creator-N slot, so no special template handling is required.

API endpoints

Status transitions run through the PUT update and are guarded service-side (PENDING -> APPROVED|REJECTED, APPROVED -> VERIFIED|SUSPENDED, and so on); a backwards transition is rejected 409.

See FundingGroupStatus for the full transition table.