Payroll by weight

// Pays a payroll in USDC from the Pot: `budget`, or all the USDC the Pot holds when `budget` is 0,
// split among `payees` by weight. Each payee gets budget × weight ÷ the sum of the weights,
// rounded down, and the last payee also gets the rounding remainder, so the payroll spends exactly
// the budget. Every payee is checked before anything moves: an empty list, a zero address, the
// Pot itself, a payee listed twice, weights that sum to 0 or a budget the Pot does not hold
// reverts the cook. Each payment is measured at its payee, and a payee that receives a different
// amount reverts the cook too. Returns what each payee received, in order.
//
//   sauce simulate payroll-by-weight.sauce.ts --chain <chain> --owner <address> \
//     --assume-balance USDC:<whole-tokens> --args <payees> <budget>
//   sauce run payroll-by-weight.sauce.ts --chain <chain> --wallet <name> --args <payees> <budget>
//
//   payees: { to: Address; weight: Uint256 }[]  who is paid and their weight, as a JSON array of
//                                               records: '[{"to":"<payee>","weight":3}]'
//   budget: Uint256                             the USDC paid in all, in its base units (6
//                                               decimals): 6000000000 is 6,000 USDC; 0 pays all
//                                               the USDC the Pot holds
//
// On Base, 100 USDC to three payees at 3:2:1:
//
//   sauce run payroll-by-weight.sauce.ts --chain base --wallet me --args \
//     '[{"to":"<payee1>","weight":3},
//       {"to":"<payee2>","weight":2},
//       {"to":"<payee3>","weight":1}]' 100000000
function main(payees: { to: Address; weight: Uint256 }[], budget: Uint256): Uint256[] {
  const count = payees.length;
  require(count > 0, "no payees");

  // Check every payee before any USDC moves.
  let totalWeight = 0;
  for (let i = 0; i < count; i++) {
    const to = payees[i].to;
    require(to != 0 && to != pot, "a payee is the zero address or the Pot");
    for (let j = 0; j < i; j++) {
      require(payees[j].to != to, "a payee is listed twice");
    }
    totalWeight += payees[i].weight;
  }
  require(totalWeight > 0, "the weights sum to 0");

  const held = USDC.balanceOf(pot);
  const spend = budget == 0 ? held : budget;
  require(spend > 0, "nothing to pay");
  require(held >= spend, "the budget is not in the Pot");

  const paid: Uint256[] = new Array(count);
  let left = spend;
  for (let i = 0; i < count; i++) {
    const to = payees[i].to;
    // Each share rounds down; the last payee takes what is left, the remainder included.
    const share = i == count - 1 ? left : Math.mulDiv(spend, payees[i].weight, totalWeight);
    left -= share;
    if (share > 0) {
      const before = USDC.balanceOf(to);
      USDC.transfer(to, share);
      paid[i] = USDC.balanceOf(to) - before;
      require(paid[i] == share, "a payee received a different amount");
    }
  }
  return paid;
}