Contract Architecture

​

Architecture

​

Contracts

​

SyndicateVault

• Layer 1 (onchain): Syndicate-level checks enforced by the vault are narrow today — registerAgent gates which addresses can be named as proposers, the governor holds the single-active-proposal invariant per vault, and redemptionsLocked() blocks deposits / withdrawals / rescues while a strategy is live. The broader cap surface historically described here (maxPerTx, maxDailyTotal, maxBorrowRatio, per-agent caps, target allowlist) is aspirational — none of those fields exist on AgentConfig or the vault in the current code. Treat them as planned, not implemented. See CLAUDE.md §Aspirational in the repo for the running list.
• Layer 2 (offchain): Agent-side off-chain policies — the caps above are enforced in the Hermes agent runtime as pre-flight checks, not on-chain.
• Layer 3 (economic, new in PR #229): Guardian review + slashable owner bond on the GuardianRegistry. Vault owners must post a WOOD bond before the factory will deploy their vault, and arbitrary-calldata emergency settlement requires surviving a 24h guardian review. See Guardian Review.

• executeGovernorBatch(calls) — governor-only batch execution for proposal strategies. This is the single on-chain entry point for strategy calldata. Reverts for any non-governor caller.
• registerAgent(agentId, agentAddress) — registers agent with ERC-8004 identity verification. AgentConfig stores {agentId, agentAddress, active} — no caps fields.
• transferPerformanceFee(token, to, amount) — governor-only fee distribution after settlement. Has no amount / recipient / token validation on the vault side — the governor is trusted to transfer only what settlement math dictates, to a pre-vetted recipient (proposer, co-proposer, vault owner, or protocolFeeRecipient), in the proposal’s asset(). This is a deliberate trust assumption: the governor is upgradeable by the protocol multisig via the shared GovernorBeacon, so compromising it compromises the fee path by construction. See Trust Assumptions below.
• setAgentFeeBps(bps) — owner-only. Sets the vault’s agent performance fee (the cut a proposing agent earns on profit). Defaults to 5% (500 bps) at creation; reverts above the vault cap of 15% (1500 bps). When a proposal is created the governor snapshots the vault’s current agentFeeBps onto that proposal (immutable for the proposal); at settlement it uses that snapshot, additionally clamped to maxPerformanceFeeBps. A later owner change only affects proposals created after it. Replaces the old per-proposal fee argument.
• deposit(assets, receiver) / redeem(shares, receiver, owner) — standard ERC-4626 LP entry/exit. Revert while redemptionsLocked() is true.
• strategyMint(to, shares) / strategyBurn(shares) — active-strategy-only share hooks (gated msg.sender == activeStrategyAdapter()), added for the custody-deposit model where the strategy custodies user assets and prices entry/exit itself (see Leveraged Aerodrome CL). Both are pure share operations — no asset transfer, no pricing. strategyMint re-checks the depositor whitelist (_openDeposits / _approvedDepositors) and whenNotPaused, so a strategy is not a back door around the vault’s access control; it also auto-delegates the recipient’s voting power. strategyBurn(shares) burns from msg.sender (the strategy holds the redeemer’s transferred shares) and is deliberately not pause-gated, so the per-user direct exit keeps working during an incident pause. The active-strategy gate is the trust boundary — there is no codehash pin (intentional, to conserve the EIP-170-capped vault bytecode); the active strategy is a governance-approved, guardian-reviewed clone of an audited template.
• redemptionsLocked() — pull-model lock: resolves the vault’s governor via factory.governorOf(address(this)) and reads its no-arg getActiveProposal() != 0 live on every call. No lockRedemptions() / unlockRedemptions() state-flipping functions exist on the vault; the lock is derived, not stored.
• rescueEth(to, amount) — owner-only, recovers ETH via Address.sendValue. Also reverts while redemptionsLocked() is true.
• rescueERC20(token, to, amount) — owner-only, recovers ERC-20 tokens (reverts with CannotRescueAsset if token is the vault asset; also reverts while redemptionsLocked() is true).
• rescueERC721(token, tokenId, to) — owner-only, recovers ERC-721 tokens (also reverts while redemptionsLocked() is true).

​

SyndicateGovernor

• propose(vault, strategy, metadataURI, strategyDuration, executeCalls, settlementCalls, coProposers) — create proposal with separate opening/closing call arrays. There is no per-proposal fee argument — at creation the governor snapshots the vault’s current agentFeeBps onto the proposal (immutable for that proposal; clamped to maxPerformanceFeeBps at settlement). strategy is the address whose positions() the vault prices via the PriceRouter for Lane A live NAV during the strategy window; pass address(0) to opt out (queue-only / Lane B). The proposal’s snapshotTimestamp = block.timestamp - 1 (closes a flash-delegate window on 2s L2 blocks). reviewEnd and executeBy are stamped in the same tx based on the current reviewPeriod and executionWindow.
• vote(proposalId, voteType) — cast vote (For/Against/Abstain) weighted by ERC20Votes timestamp-clock snapshot
• executeProposal(proposalId) — permissionless: anyone can trigger the pre-approved executeCalls once state is Approved and the execution window is open. Uses the vault’s executeGovernorBatch.
• settleProposal(proposalId) — proposer can settle at any time; everyone else waits for strategyDuration. Uses the vault’s executeGovernorBatch.
• unstick(proposalId) — vault owner after duration. Runs the pre-committed settlementCalls only. No custom calldata, no fallback. Does not require active owner bond.
• emergencySettleWithCalls(proposalId, calls) — vault owner, requires active owner bond. Stores the full owner-supplied calls array in the registry via registry.openEmergency(proposalId, keccak256(calls), calls) and opens a 24h guardian review window; does not execute yet.
• cancelEmergencySettle(proposalId) — vault owner self-recall of an emergency-settle before reviewEnd. No slashing.
• finalizeEmergencySettle(proposalId) — vault owner after reviewEnd. Takes proposalId only; the registry’s finalizeEmergency returns the stored calls together with the blocked flag. Executes if guardian block quorum was not reached; reverts + slashes owner bond if it was.
• cancelProposal(proposalId) — proposer cancel, allowed from Pending, GuardianReview, or Approved. emergencyCancel(proposalId) — owner cancel, narrowed to Draft and Pending.
• vetoProposal(proposalId) — vault owner rejects a proposal, narrowed to Pending only. Once the proposal enters GuardianReview, the only rejection path is the guardian block quorum.
• approveCollaboration(proposalId) / rejectCollaboration(proposalId) — co-proposer consent
• claimUnclaimedFees(vault, token) — recipient pull-claim for fees that failed to transfer at settlement (blacklist, etc.). See Economics — Try/catch fee transfers.

1. Protocol fee from gross profit
2. Agent performance fee from net profit (after protocol fee)
3. Management fee from remainder (after agent fee)

​

GovernorParameters

​

GovernorEmergency (abstract)

​

GuardianRegistry

• Review windows (openReview(governor, pid), voteOnProposal(governor, pid, …), resolveReview(governor, pid)) with the quorum denominator snapshot at openReview() time (read from sWOOD’s getPastTotalVotes + getPastTotalActiveDelegated at t-1) to close denominator-manipulation attacks
• Emergency-settle review windows (openEmergency(proposalId, callsHash, calls) — governor-only, stores the full calls array; voteBlockEmergencySettle, resolveEmergencyReview, finalizeEmergency)
• Slashing orchestration: on a blocked review the registry computes who/how-much and calls into sWOOD, which performs the WOOD burn to 0x...dEaD (CEI + pull-burn fallback). The registry never custodies the WOOD.
• Approver vote accounting + the getApproverWeights(governor, proposalId) view (approvers, snapshot weights, denominator) consumed by the off-chain guardian-fee attribution bot. (The on-chain guardian-fee pools/claims/W-1-escrow — fundProposalGuardianPool, claimProposalReward, claimDelegatorProposalReward — were deleted in the guardian-fee-buyback refactor; fees now distribute as WOOD via Merkl, see below.)
• Appeal path: fundSlashAppealReserve + refundSlash (owner-only, capped at 20% of reserve per epoch) — the appeal reserve is the registry’s only token balance
• Reward attribution — both guardian reward streams are distributed off-chain via Merkl, in WOOD, claimed at merkl.xyz:
  • Epoch block-rewards (inflationary): on a review that resolves blocked, the registry emits BlockerAttributed(proposalId, epochId, blocker, weight) per blocker. There is no on-chain fundEpoch / claimEpochReward / sweepUnclaimed / minter (all removed in V1.5).
  • Guardian performance fees (revenue): at settlement the governor routes the fee slice to the guardiansFeeRecipient multisig and emits GuardianFeeAccrued. The team swaps it to WOOD and airdrops approvers/delegators weekly. The bot reconstructs the DPoS split from GuardianFeeAccrued + the registry’s getApproverWeights(governor, pid) + sWOOD getPast* checkpoints (commission at settledAt, delegation at openedAt).
• Pause / unpause: pause (owner), unpause (owner, or permissionless after the 7-day DEADMAN_UNPAUSE_DELAY). Pause freezes voting and review resolution; never freezes sWOOD unstake/claim paths.

​

StakedWood (sWOOD)

• Guardian staking / unstaking with cool-down (stakeAsGuardian, requestUnstakeGuardian, cancelUnstakeGuardian, claimUnstakeGuardian)
• Vault-owner bond lifecycle (prepareOwnerStake, cancelPreparedStake, bindOwnerStake / transferOwnerStakeSlot — factory-only, requestUnstakeOwner, claimUnstakeOwner)
• DPoS delegation (StakedWoodDelegation): delegate/undelegate stake to active guardians, per-delegate setCommission, and the active-delegation checkpoints (getPastTotalVotes, getPastTotalActiveDelegated) the registry’s quorum math reads
• Slashing + burn execution: the registry calls in, sWOOD zeroes the slashed stake and burns WOOD to 0x...dEaD (CEI + pull-burn fallback)
• Stake-economic owner-instant setters: setMinGuardianStake, setMinOwnerStake, setCooldownPeriod (must stay >= reviewPeriod — Sherlock #16), setMinSlashBps / setMaxSlashBps, setDelegationEnabled

​

SyndicateFactory

​

BatchExecutorLib

​

StrategyFactory

​

Strategy Templates

• Execute: [tokenA.approve(strategy, amount), tokenB.approve(strategy, amount), strategy.execute()]
• Settle: [strategy.settle()]

​

Trust Assumptions

1. vault.transferPerformanceFee(token, to, amount) has no amount / recipient / token cap. The governor (upgradeable by protocol multisig via the shared GovernorBeacon) is trusted not to pass arbitrary values here. A compromised governor could transfer any ERC-20 the vault holds to any address. Mitigation is governance-level: the beacon upgrade path is multisig-controlled, not instant. Tracked as item A38 in the pre-mainnet punch list.
2. delegatecall target is not codehash-checked. SyndicateVault.executeGovernorBatch forwards its batch to _executorImpl via delegatecall. The intent is that _executorImpl is always the stateless BatchExecutorLib — but _executorImpl is set at init with no codehash assertion, and no runtime check rejects other code at that address. If the factory ever rotates executorImpl to a non-library contract, that contract runs in the vault’s storage context. Tracked as item V-C2.
3. AgentConfig has no per-agent caps. The off-chain Hermes runtime enforces maxPerTx / maxDailyTotal / maxBorrowRatio as pre-flight policy. None of these are stored on-chain; a compromised agent process running alongside a compromised vault owner can submit anything the vault’s single-active-proposal invariant allows. Tracked as item A10 / A35.
4. WOOD is assumed to be a fixed-behavior ERC-20. The GuardianRegistry slashing path uses end-of-function bulk burns; if WOOD is ever migrated to a token with transfer hooks (ERC-777 / 1363) the slashing path becomes reentrancy-exposed. Cross-referenced with the “delegatecall-only-to-BatchExecutorLib” assumption above.

​

Testing

cd contracts
forge build        # compile
forge test         # run all tests
forge test -vvv    # verbose with traces
forge fmt          # format before committing

​

Storage Layout (UUPS Safety)

• Always append new storage variables at the end (before __gap)
• Never reorder or remove existing slots
• Reduce __gap by the number of slots added
• Verify with forge inspect <ContractName> storage-layout