Split Config

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.