Fee Splits & Immutability Policy#

This guide details how fee splits are calculated using Basis Points (bps), how split smart contracts are validated, and the immutability policy enforced after container deployment.

1. Split Allocation & Basis Points (bps)#

BasaltSurge uses basis points (bps) to allocate transaction payouts on-chain, where: $$100 \text{ bps} = 1.00%$$ $$10,000 \text{ bps} = 100.00%$$

When payments are processed, the PaymentSplitter smart contract divides the payouts: $$\text{merchantBps} = 10,000 - \text{platformFeeBps} - \text{partnerFeeBps}$$

Resolution Precedence:#

1. Platform Fee (
   markup

   platformFeeBps

   ):
   • First priority: Brand configuration override in Cosmos DB (
     markup

     brand:config.platformFeeBps

     ).
   • Second priority: Static default brand config (
     markup

     BRANDS[key].platformFeeBps

     ).
   • Third priority: Environment defaults (
     markup

     PLATFORM_SPLIT_BPS

     ).
   • Fallback:
     markup

     50 bps

     (0.50%).
2. Partner Fee (
   markup

   partnerFeeBps

   ):
   • First priority: Brand configuration override in Cosmos DB (
     markup

     brand:config.partnerFeeBps

     ).
   • Second priority: Static brand defaults.
   • Fallback:
     markup

     0 bps

     (0.00%).

2. Split Validation Audits#

PaymentSplitter

• The platform recipient address must be present with shares matching the resolved
  markup

  platformFeeBps

  .
• The partner recipient address must be present with shares matching the resolved
  markup

  partnerFeeBps

  .
• Total recipient shares must sum to exactly
  markup

  10,000 bps

  (100%).

Misconfiguration Signals:#

If a mismatch is found, the system flags the split as misconfigured and returns a warning:

• markup

  platform_bps_mismatch

  : The split contract's platform share doesn't match the resolved database configuration.
• markup

  missing_platform_recipient

  or
  markup

  missing_partner_recipient

  : Required wallets are missing from the splitter contract.
• markup

  needsRedeploy

  : Indicates that the contract must be re-bound or redeployed to resolve the mismatch.

3. Post-Deployment Immutability Policy#

To protect merchants and preserve network transparency, fee structures are locked after container provisioning:

• Lock Event: Once a partner container is deployed (detected when
  markup

  containerState

  ,
  markup

  containerAppName

  , or
  markup

  containerFqdn

  is written to the database configuration overrides), fee configurations are locked.
• Partner Restrictions: Partners cannot adjust
  markup

  platformFeeBps

  or
  markup

  partnerFeeBps

  post-deployment. Attempting to modify these fields returns:

  json
  { "error": "fees_locked_after_deploy" }

  (HTTP Status:
  markup

  403 Forbidden

  ).
• UI Behavior: In the Branding Panel, the fee input boxes are disabled and show the message "Locked after partner container deploy".
• Operational Overrides: If fees must be altered due to contract adjustments, changes must be performed by a Platform administrator carrying
  markup

  platform_superadmin

  or
  markup

  platform_admin

  credentials.