Distributions API

Overview

Distributions on Sails.to are waterfall-based and enforced on-chain. The sails_distributions program is a dedicated Solana Anchor program that handles everything from revenue receipt to investor payout. It is separate from the sails_securities token program - distributions are a first-class concern with their own instruction set, account structures, and authorization model.

The design principle is simple: investors get paid before the platform. Revenue flows through a priority structure defined at offering creation, and every step is recorded on-chain. There are no off-chain side agreements, no manual overrides, no way to redirect funds outside the waterfall without Trustee authentication. The Paying Agent executes the waterfall; the Trustee authenticates it; the blockchain enforces it.

The Waterfall Model

Every offering on Sails.to defines a waterfall - a priority structure that determines the order in which revenue is distributed. The waterfall is configured when the offering is initialized via the init_waterfall instruction and cannot be modified after investors have committed capital.

The waterfall executes in strict priority order. Each tranche must be fully satisfied before the next tranche receives any funds:

The investor-first design is non-negotiable. The platform fee sits at priority 3 - below investor distributions. If revenue in a given epoch is insufficient to fully satisfy the investor tranche, the platform receives zero fees for that epoch. This alignment of incentives is encoded in the smart contract, not in a terms-of-service document.

Program Instructions

The sails_distributions program exposes five instructions. Each instruction enforces role-based authorization via the NFT hierarchy - you cannot call these instructions without holding the correct role NFT:

Authorization Flow

The dual-authorization model for execute_waterfall deserves emphasis. This is not a single-signer operation:

1. Paying Agent initiates - The Paying Agent (appointed by the Trustee, holding a Paying Agent role NFT) submits the execute_waterfall instruction with the offering ID.
2. Trustee authenticates - The Trustee (holding a Trustee role NFT) co-signs the transaction. The program verifies both NFTs before executing. For standard distributions, this is a 1-of-1 Trustee NFT signature. For large distributions exceeding a configurable threshold, a 2-of-3 keyholder ceremony is required.
3. On-chain execution - The program snapshots token balances, runs the waterfall calculation, creates the DistributionRecord, and emits the DistributionPaid event. Funds are placed in escrow for investor claiming.

Distribution Records

Every executed waterfall creates a DistributionRecord - a Program Derived Address that stores the complete state of a single distribution epoch:

DistributionRecord PDA
Seeds: ["distribution", offering_id, epoch]
├── offering_id: Pubkey        // The offering this distribution belongs to
├── epoch: u32                 // Sequential distribution number (0, 1, 2, ...)
├── amount_per_token: u64      // Lamports (or smallest unit) per token for this epoch
├── total_distributed: u64     // Total amount allocated across all tranches
├── snapshot_slot: u64         // Solana slot at which token balances were snapped
├── claimed_bitmap: Vec<u8>    // Bit array tracking which investors have claimed
├── created_at: i64            // Timestamp of waterfall execution
├── trustee_signature: Pubkey  // Trustee who authenticated this distribution
└── status: enum { Active, Reconciled, Disputed }

The Claimed Bitmap

The claimed_bitmap is a compact bit array where each bit corresponds to an investor position index. When an investor calls claim_distribution, the program sets their bit to 1. This design has three advantages:

• Space efficiency: A single byte tracks 8 investors. An offering with 2,000 investors requires only 250 bytes for the bitmap - far cheaper than creating a separate PDA per investor per epoch.
• Idempotency: The program checks the bitmap before transferring funds. If the investor's bit is already set, the instruction returns success without transferring anything. Double-claiming is impossible.
• Audit visibility: Anyone can read the bitmap to see exactly which investors have claimed and which have not. Unclaimed distributions are immediately visible to the Paying Agent and Trustee for follow-up.

Investor position indices are assigned sequentially when tokens are first minted to a wallet. The mapping from wallet address to position index is stored in the InvestorPosition PDA and does not change - even if the investor transfers all their tokens and later reacquires them, they retain their original index.

Claiming Distributions

Distributions on Sails.to use a pull-based model. The execute_waterfall instruction calculates allocations and records them on-chain, but it does not push funds to investors. Instead, each investor calls claim_distribution to pull their allocation when they are ready.

On-Chain Holders

For investors holding security tokens directly in their Solana wallet, the claim process is straightforward:

1. The investor connects their wallet and calls claim_distribution(offering_id, epoch).
2. The program reads the DistributionRecord for the specified epoch and retrieves the amount_per_token value.
3. The program reads the investor's InvestorPosition PDA to determine their token balance at the snapshot_slot.
4. The program calculates the payout: amount_per_token × investor_balance.
5. The program checks the claimed_bitmap - if the investor's bit is already set, the instruction returns without transferring funds.
6. The program transfers the calculated amount from the distribution escrow to the investor's wallet, sets the bitmap bit, and emits a claim event.

Bankable / Clearstream Holders

Investors who hold their position on the bankable side via Clearstream (through CrossConversion) do not claim distributions on-chain. Instead, distributions to these holders are processed as corporate actions through Clearstream's settlement infrastructure:

• When execute_waterfall runs, the program identifies tokens locked in the CrossConversion lockbox and calculates the distribution amount for those positions.
• The Clearstream adapter service receives the DistributionPaid event and initiates a corporate action (ISO 20022 message) to distribute funds to the corresponding ISIN holders.
• Clearstream settles the distribution to each investor's custodial account according to its standard settlement cycle.
• The reconcile instruction is then used to verify that the on-chain and bankable distributions match.

This dual-track claiming model is what makes CrossSecurities work - the same offering can pay both on-chain and traditional finance investors from a single waterfall execution.

Reconciliation

Reconciliation is the process of cross-checking on-chain distribution records with the bankable side. This is critical for offerings that have investors on both sides of the CrossConversion bridge.

The Reconcile Instruction

After a distribution epoch has been executed and Clearstream has settled the corresponding corporate action, the Trustee calls the reconcile instruction:

1. The Trustee obtains the Clearstream position report for the offering's ISIN, showing each investor's distribution receipt.
2. The Clearstream adapter generates a SHA-256 hash of the position report and submits it as clearstream_data.
3. The program compares the total distributed on-chain (from the DistributionRecord) with the total reported by Clearstream.
4. If the amounts match, the DistributionRecord status is updated to Reconciled.
5. If a discrepancy is detected, the status is set to Disputed, a ComplianceViolation event is emitted, and the DAO Manager Grain is alerted for investigation.

Reconciliation Schedule

The reconciliation engine runs on a configurable schedule - typically within 48 hours of each distribution execution. For high-frequency distributions (monthly), the nightly reconciliation job compares the on-chain lockbox state with Clearstream holdings and flags any drift. A discrepancy in the supply invariant (tokens_locked == isin_outstanding) triggers an immediate alert to the Trustee and platform operators.

API Endpoints

The Distributions API is exposed through the platform's API gateway at api.sails.to. Authentication uses Solana wallet signature + NFT verification. All endpoints return JSON.

Investor Endpoints

Authenticated with investor wallet signature:

Issuer Endpoints

Authenticated with Issuer NFT:

Distribution Frequency

The distribution frequency is configured per offering in the OfferingConfig via the distributionFrequency field. Supported options:

The frequency setting determines when the Paying Agent is expected to execute the waterfall, but it does not enforce timing at the program level - the execute_waterfall instruction can be called at any time, subject to the dual-authorization requirement. The frequency is a business-logic convention, not a smart contract constraint.