Split Allocator

Specifications

A contract can become a split allocator by adhering to ISnowconeSplitAllocator:

interface ISnowconeSplitAllocator {
  function allocate(SnowconeSplitAllocationData calldata _data) external payable;
}

When extending payout distribution or reserved token distribution functionality with an allocator, the protocol will pass a SnowconeSplitAllocationData to the allocate(...) function:

struct SnowconeSplitAllocationData {
  address token;
  uint256 amount;
  uint256 decimals;
  uint256 projectId;
  uint256 group;
  SnowconeSplit split;
}

struct SnowconeSplit {
  bool preferClaimed;
  bool preferAddToBalance;
  uint256 percent;
  uint256 projectId;
  address payable beneficiary;
  uint256 lockedUntil;
  ISnowconeSplitAllocator allocator;
}

The msg.sender to the allocator will either be the payment terminal that facilitated the payout distribution, or the controller that facilitated the reserved tokens distribution.

In payment terminals based on the SnowconePayoutRedemptionPaymentTerminal3_1_1, such as SnowconeETHPaymentTerminal3_1_1's and SnowconeERC20PaymentTerminal3_1_1's, the allocator hook gets called while the payouts are being distributed to splits. View the docs.

If the allocation is coming from an ETH payment terminal such as SnowconeETHPaymentTerminal3_1_1, the ETH will be included in the call to allocate(...). If the allocation is coming from an ERC20 payment terminal such as SnowconeERC20PaymentTerminal3_1_1, the tokens will be pre-approved for the allocator contract to transfer them to it. Make sure to initiate the transfer, and make sure to not leave allocated tokens stuck in the allocator contract. If the allocation is coming from a controller such as SnowconeController3_1 distributing reserved tokens, the tokens will be minted pre-distributed to the allocator's address. If the split's preferClaimed property is true and the project has a token a contract attached, the tokens will be minted directly to the allocator contract. Otherwise, they will be allocated in the SnowconeTokenStore as unclaimed tokens from which the allocator can then claimFor(...) itself or transferFrom(...) itself to another address. Make sure to not leave allocated tokens stuck in the allocator contract or unclaimed in the SnowconeTokenStore contract.

Attaching

New allocator contracts should be deployed independently. Once deployed, its address can be configured into a project's payout splits or reserved token splits so that any distribution triggered while the funding cycle is active sends the relevant token to the allocator contract's allocate(...) hook.