feat: implement SplitBaseV2 with bucket semantics and revenue tracking (#3)

Major upgrade introducing formal domain model for revenue distribution with bucket categorization, source attribution, and distribution history tracking.

Author: katyailil

.github/workflows/upgrade.yml

@@ -3,16 +3,24 @@ name: Upgrade Contracts
 on:
   workflow_dispatch:
     inputs:
+      contract:
+        description: 'Contract to upgrade'
+        required: true
+        type: choice
+        options:
+          - SplitBase
+          - Registry
+          - Executor
       network:
-        description: 'Network (same as deployment)'
+        description: 'Network'
         required: true
         type: choice
         options:
           - base_sepolia
           - base
       proxy_address:
-        description: 'Proxy contract address (not implementation!)'
-        required: true
+        description: 'Proxy contract address (optional - auto-detected from deployments/)'
+        required: false
 
 jobs:
   upgrade:
@@ -25,22 +33,52 @@ jobs:
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
 
-      - name: Deploy new implementation
+      - name: Determine proxy address
+        id: proxy
+        run: |
+          CHAIN_ID=${{ inputs.network == 'base' && '8453' || '84532' }}
+          CONTRACT_LOWER=$(echo "${{ inputs.contract }}" | tr '[:upper:]' '[:lower:]')
+
+          if [ -n "${{ inputs.proxy_address }}" ]; then
+            PROXY="${{ inputs.proxy_address }}"
+          else
+            PROXY=$(jq -r ".${CONTRACT_LOWER}Proxy" deployments/${CHAIN_ID}.json)
+          fi
+
+          echo "proxy_address=$PROXY" >> $GITHUB_OUTPUT
+          echo "📍 Proxy address: $PROXY"
+
+      - name: Upgrade contract
         env:
           PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
           BASESCAN_API_KEY: ${{ secrets.BASESCAN_API_KEY }}
-          PROXY_ADDRESS: ${{ inputs.proxy_address }}
+          PROXY_ADDRESS: ${{ steps.proxy.outputs.proxy_address }}
         run: |
-          echo "Deploying new implementation..."
-          forge script script/DeployProxy.s.sol \
+          echo "🚀 Upgrading ${{ inputs.contract }}..."
+          echo "Network: ${{ inputs.network }}"
+          echo "Proxy: $PROXY_ADDRESS"
+
+          case "${{ inputs.contract }}" in
+            SplitBase)
+              SCRIPT="script/UpgradeToV2.s.sol"
+              ;;
+            Registry)
+              SCRIPT="script/Upgrade.s.sol"
+              ;;
+            Executor)
+              SCRIPT="script/Upgrade.s.sol"
+              ;;
+          esac
+
+          forge script $SCRIPT \
             --rpc-url ${{ inputs.network }} \
             --broadcast \
             --verify \
             -vvvv
 
-          echo "⚠️  Manual upgrade required:"
-          echo "Call upgradeToAndCall() on proxy at $PROXY_ADDRESS"
-          echo "with new implementation address from deployment"
+          echo ""
+          echo "✅ Upgrade complete!"
+          echo "Proxy $PROXY_ADDRESS upgraded successfully"
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4

README.md

@@ -17,17 +17,26 @@ High-precision share calculations ensure accurate distribution across all recipi
 ## Architecture
 
 - **Core Pool Logic**: Dynamic recipient configurations with percentage/unit-based shares
+- **Bucket Semantics**: Structured categorization (TEAM, INVESTORS, TREASURY, etc.)
+- **Source Tracking**: Revenue attribution (Base Pay, protocol fees, grants, etc.)
 - **Registry**: Centralized pool management and discovery
 - **Executor**: Base Pay integration for automated execution flows
 - **Upgradeability**: UUPS proxy pattern with static addresses
 
+**📚 Documentation:**
+- [Architecture Guide](./docs/ARCHITECTURE.md) - Technical architecture and integration patterns
+- [Domain Model](./docs/DOMAIN_MODEL.md) - Business concepts explained for non-developers
+
 ## Features
 
 - Create and manage payout pools with flexible share models
+- **Bucket categorization** (TEAM, INVESTORS, TREASURY, REFERRALS, SECURITY_FUND, GRANTS)
+- **Revenue source tracking** (Base Pay, protocol fees, grants, donations, partnerships)
+- **Distribution history** with full on-chain audit trail
 - Execute distribution cycles with precise accounting
 - Support for Base smart wallets and sub-accounts
-- Full upgradeability without address changes
-- Event emissions optimized for Subgraph indexing
+- Full upgradeability without address changes (V1 → V2 compatible)
+- Event emissions optimized for Subgraph indexing and analytics dashboards
 - Gas-optimized execution for cost-effective operations
 
 ## Development

deployments/8453.json

@@ -6,7 +6,10 @@
   "network": "base",
   "registryImplementation": "0x4125d418Fe36a755F5eEB7c502ca3e00750cDDd8",
   "registryProxy": "0xEa10580212A12c98eE0ebACbBC595af2062a81B0",
-  "splitBaseImplementation": "0xC680FA2Ba45f01B84E7962cBbe8cDc98dD20Ad72",
+  "splitBaseImplementation": "0x13A8f49C41133A2f3D5E6cbb18626EE242b0E4f4",
+  "splitBaseImplementationV1": "0xC680FA2Ba45f01B84E7962cBbe8cDc98dD20Ad72",
   "splitBaseProxy": "0x9A1f27779561269Ac8bFFdd152D1F8f2C445FC3e",
+  "version": "V2",
+  "upgradedAt": 1733845200,
   "timestamp": 1764058313
 }

deployments/84532.json

@@ -6,7 +6,10 @@
   "network": "base-sepolia",
   "registryImplementation": "0x34aec145B7b2a0922112545C8D9bC20bd551F901",
   "registryProxy": "0xF0f141DeB225D9D4639dF1E6E91bE4bC90EDD5eE",
-  "splitBaseImplementation": "0xc41b9c958109ebcD0Ff3794C30D4d151490a2975",
+  "splitBaseImplementation": "0x2Ca555A7ACFE2da02099A6d950b8665A65f5c861",
+  "splitBaseImplementationV1": "0xc41b9c958109ebcD0Ff3794C30D4d151490a2975",
   "splitBaseProxy": "0x62B52D21db12E4A709a49c043e31adfdAB41FB39",
+  "version": "V2",
+  "upgradedAt": 1733845200,
   "timestamp": 1764058302
 }