Shard Validators

interface IShardExecValidator {
    function isAllowed(
        address sender,
        address to,
        uint256 value,
        bytes calldata data,
        bytes calldata validatorArgs
    ) external view returns (bool);
}

shard.setValidator(IShardExecValidator newValidator);   // DEFAULT_ADMIN_ROLE; newValidator != address(0)

validator.setAllowlistRoot(bytes32 newRoot);   // onlyOwner

domainSeparator = keccak256(abi.encodePacked(
    bytes4(0x414c4c57),   // "ALLW" magic
    uint8(1),             // layout version
    block.chainid,
    address(this)
))

(data[4 + offset : 4 + offset + 32] & mask) == expected

leaf value = [LEAF_TYPE, domainSeparator, ruleEncoded]
           = [0,         domainSeparator, ruleEncoded]

import { ethers } from 'ethers';
import { StandardMerkleTree } from '@openzeppelin/merkle-tree';
import { packRuleSelector, packedSelectorToBytes4 } from '../../scripts/strategy/merkleUtils';
 
const MerkleAllowlistValidator = await ethers.getContractFactory('MerkleAllowlistValidator');
const validator = await MerkleAllowlistValidator.deploy(ownerAddress);
await validator.waitForDeployment();
 
const domainSeparator = await validator.domainSeparator();

interface RuleConstraint {
  offset: number;
  mask: string;
  expected: string;
}
 
function encodeMerkleRule(p: {
  flags: number;
  selector?: string;
  sender: string;
  to: string;
  value: bigint;
  dataLength: number;
  constraints: RuleConstraint[];
}): string {
  const sel = packedSelectorToBytes4(packRuleSelector(p.selector));
  const types = ['uint8', 'uint8', 'bytes4', 'address', 'address', 'uint256', 'uint32', 'uint16'];
  const values: (string | bigint | number)[] = [
    0x01, p.flags, sel, p.sender, p.to, p.value, p.dataLength >>> 0, p.constraints.length,
  ];
  for (const c of p.constraints) {
    types.push('uint16', 'bytes32', 'bytes32');
    values.push(c.offset, c.mask, c.expected);
  }
  return ethers.solidityPacked(types, values);
}
 
const LBTC_ADDRESS    = '0xabc...';   // LBTC token contract
const VAULT_ADDRESS   = '0xdef...';   // DeFi vault contract
const ZERO_ADDRESS    = ethers.ZeroAddress;
 
// Rule 1: approve(address spender, uint256 amount) on LBTC
//   - Exact `to` = LBTC, exact selector; spender pinned to vault; any amount
const vaultWordPadded = ethers.AbiCoder.defaultAbiCoder().encode(['address'], [VAULT_ADDRESS]);
const ALL_ONES = '0x' + 'ff'.repeat(32);
// Ethereum addresses occupy the low 20 bytes of a 32-byte ABI word; mask the address portion.
const ADDRESS_MASK = '0x' + '00'.repeat(12) + 'ff'.repeat(20);
 
const ruleApprove = encodeMerkleRule({
  flags: 0x02 | 0x10,                      // FLAG_TO + FLAG_SELECTOR
  selector: 'approve(address,uint256)',
  sender: ZERO_ADDRESS,                    // any sender
  to: LBTC_ADDRESS,
  value: 0n,
  dataLength: 0,                           // any data length
  constraints: [
    // First arg (offset 0) = spender; must equal VAULT_ADDRESS
    { offset: 0, mask: ADDRESS_MASK, expected: vaultWordPadded },
  ],
});
 
// Rule 2: deposit(uint256 amount) on the vault, any amount, any sender
const ruleDeposit = encodeMerkleRule({
  flags: 0x02 | 0x10,                      // FLAG_TO + FLAG_SELECTOR
  selector: 'deposit(uint256)',
  sender: ZERO_ADDRESS,
  to: VAULT_ADDRESS,
  value: 0n,
  dataLength: 0,
  constraints: [],                         // no amount restriction
});
 
// Rule 3: withdraw(uint256 amount) from the vault, any amount, any sender
const ruleWithdraw = encodeMerkleRule({
  flags: 0x02 | 0x10,                      // FLAG_TO + FLAG_SELECTOR
  selector: 'withdraw(uint256)',
  sender: ZERO_ADDRESS,
  to: VAULT_ADDRESS,
  value: 0n,
  dataLength: 0,
  constraints: [],
});

const leaves = [ruleApprove, ruleDeposit, ruleWithdraw].map(rule => [
  0,                               // LEAF_TYPE
  domainSeparator,
  ethers.getBytes(rule),
]);
 
const tree = StandardMerkleTree.of(leaves, ['uint8', 'bytes32', 'bytes']);
 
// Set root on-chain (owner of the validator)
await validator.setAllowlistRoot(tree.root);
console.log('Allowlist root set:', tree.root);

// If deploying a new Shard:
const shard = await Shard.deploy();
await shard.initialize(
  strategyAddress,
  validator.target,
  adminAddress,
  shardTransfererAddress,
);
 
// Or, if replacing the validator on an existing shard:
await shard.setValidator(validator.target);   // DEFAULT_ADMIN_ROLE

// Approve the vault to spend 1000 LBTC
const approveCalldata = LBTC.interface.encodeFunctionData('approve', [VAULT_ADDRESS, ethers.parseUnits('1000', 8)]);
 
// Find the rule in the tree and get its proof
const ruleApproveBytes = ethers.getBytes(ruleApprove);
const proof = tree.getProof([0, domainSeparator, ruleApproveBytes]);
 
// ABI-encode validatorArgs as CallVerificationInput
const validatorArgs = ethers.AbiCoder.defaultAbiCoder().encode(
  ['tuple(bytes ruleEncoded, bytes32[] merkleProof)'],
  [{ ruleEncoded: ruleApproveBytes, merkleProof: proof }],
);
 
// Execute via the shard
await shard.exec(LBTC_ADDRESS, 0n, approveCalldata, validatorArgs);

const depositCalldata = vault.interface.encodeFunctionData('deposit', [ethers.parseUnits('500', 8)]);
 
const ruleDepositBytes = ethers.getBytes(ruleDeposit);
const depositProof = tree.getProof([0, domainSeparator, ruleDepositBytes]);
const depositValidatorArgs = ethers.AbiCoder.defaultAbiCoder().encode(
  ['tuple(bytes ruleEncoded, bytes32[] merkleProof)'],
  [{ ruleEncoded: ruleDepositBytes, merkleProof: depositProof }],
);
 
await shard.exec(VAULT_ADDRESS, 0n, depositCalldata, depositValidatorArgs);

// Add a new rule for a second vault
const ruleDepositVault2 = encodeMerkleRule({
  flags: 0x02 | 0x10,
  selector: 'deposit(uint256)',
  sender: ZERO_ADDRESS,
  to: VAULT_ADDRESS_2,
  value: 0n,
  dataLength: 0,
  constraints: [],
});
 
const newLeaves = [ruleApprove, ruleDeposit, ruleWithdraw, ruleDepositVault2].map(rule => [
  0, domainSeparator, ethers.getBytes(rule),
]);
const newTree = StandardMerkleTree.of(newLeaves, ['uint8', 'bytes32', 'bytes']);
 
// Atomic swap, old proofs become invalid as soon as this lands
await validator.setAllowlistRoot(newTree.root);