damm-sdk 1.4.36 → 1.4.37

package/src/integrations/lagoonV2/lagoon.v2.setters.ts

@@ -0,0 +1,521 @@
+/**
+ * Lagoon v0.6 vault setter/admin calldata builders — SDK-C.
+ *
+ * This module extends the v0.6 permission surface beyond what SDK-B covered.
+ * SDK-B (`lagoon.v2.permissions.ts`) handles the 16 role-gated operational
+ * functions (settleDeposit, settleRedeem, updateNewTotalAssets, expireTotalAssets,
+ * pause, unpause, whitelist/blacklist ops, updateRates, role-address setters).
+ *
+ * This module adds the remaining 13 setter/admin/utility functions:
+ *   - MaxCap:      updateMaxCap
+ *   - Sync:        setSyncMode, updateTotalAssetsLifespan
+ *   - Guardrails:  updateGuardrails, updateActivated, securityCouncilUpdateTotalAssets
+ *   - Sanctions:   setExternalSanctionsList
+ *   - Kill-switch: lockUpdateSafe, lockSuperOperator
+ *   - Batch claim: claimSharesOnBehalf, claimAssetsOnBehalf
+ *   - Metadata:    updateName, updateSymbol
+ *
+ * All function signatures have been verified against the deployed v0.6 implementations:
+ *   Arbitrum: 0x3f5A9e1D82c595d14bA93c97eB8a77928cFdee70
+ *   Ethereum: 0x6C77c47FB8168E22976C3B0338CB1769c952249f
+ *
+ * Selector verification (2026-06-08):
+ *   updateMaxCap(uint256)                               0xe81ba080
+ *   setSyncMode(uint8)                                  0x363d8de8
+ *   updateTotalAssetsLifespan(uint128)                  0xae16ea8c
+ *   updateGuardrails((uint256,int256))                  0xced9a8de
+ *   updateActivated(bool)                               0xdc324cb2
+ *   securityCouncilUpdateTotalAssets(uint256)           0xdeb337a5
+ *   setExternalSanctionsList(address)                   0x7de5c4f4
+ *   lockUpdateSafe()                                    0x8c9881a9
+ *   lockSuperOperator()                                 0x32c06a4e
+ *   claimSharesOnBehalf(address[])                      0xf15be6f9
+ *   claimAssetsOnBehalf(address[])                      0x26d6c82f
+ *   updateName(string)                                  0x84da92a7
+ *   updateSymbol(string)                                0x537f5312
+ */
+
+import { encodeFunctionData } from "viem";
+import type { Address } from "viem";
+import { createCall, type Call, type HexString, type Unwrapable } from "../..";
+import lagoonV2VaultAbi from "./vault.abi.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Guardrails struct for Lagoon v0.6.
+ *
+ * When activated, `updateNewTotalAssets` is gated:
+ *   - newTotalAssets must not increase by more than `upperRate` (expressed as a
+ *     percentage delta in WAD — e.g. 1e17 = 10% max increase per interval).
+ *   - newTotalAssets must not decrease by more than `|lowerRate|` (negative int256
+ *     expressed in WAD — e.g. -1e17 = 10% max decrease).
+ *
+ * The Security Council can bypass these bounds via `securityCouncilUpdateTotalAssets`.
+ */
+export type LagoonV2Guardrails = Readonly<{
+    upperRate: bigint; // uint256, WAD (e.g. 1e17 = 10% max increase)
+    lowerRate: bigint; // int256 (negative), WAD (e.g. -1e17 = 10% max decrease)
+}>;
+
+/**
+ * SyncMode enum for Lagoon v0.6.
+ *
+ * Async = 0 (default): standard epoch-based settlement flow.
+ * Sync  = 1: synchronous instant settlement — deposit/redeem are settled immediately.
+ */
+export const LagoonV2SyncMode = {
+    Async: 0,
+    Sync: 1,
+} as const;
+export type LagoonV2SyncModeValue = (typeof LagoonV2SyncMode)[keyof typeof LagoonV2SyncMode];
+
+// ---------------------------------------------------------------------------
+// MaxCap — Admin
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes an `updateMaxCap(uint256 maxCap)` call.
+ * Selector: 0xe81ba080
+ * Role: Owner (Admin)
+ *
+ * Sets the maximum total assets the vault is allowed to hold. Deposits that
+ * would push totalAssets above this cap are rejected. Set to `type(uint256).max`
+ * to disable the cap.
+ *
+ * Required by the DeFi-Kit mandatory-cap deploy step (DeFi-Kit#200).
+ */
+export const LagoonV2UpdateMaxCapCalldata = ({ maxCap }: { maxCap: bigint }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateMaxCap",
+        args: [maxCap],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateMaxCapTrx = ({ vault, maxCap }: { vault: Address; maxCap: bigint }): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateMaxCapCalldata({ maxCap }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Sync configuration — Admin
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a `setSyncMode(uint8 syncMode)` call.
+ * Selector: 0x363d8de8
+ * Role: Owner (Admin)
+ *
+ * Switches between Async (epoch settlement) and Sync (instant settlement) modes.
+ * Use `LagoonV2SyncMode.Async` or `LagoonV2SyncMode.Sync`.
+ *
+ * WARNING: switching modes mid-epoch may leave open requests in an inconsistent
+ * state. Only switch when no pending deposit/redeem requests are outstanding.
+ */
+export const LagoonV2SetSyncModeCalldata = ({ syncMode }: { syncMode: LagoonV2SyncModeValue }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "setSyncMode",
+        args: [syncMode],
+    }) as HexString;
+};
+
+export const lagoonV2SetSyncModeTrx = ({
+    vault,
+    syncMode,
+}: {
+    vault: Address;
+    syncMode: LagoonV2SyncModeValue;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2SetSyncModeCalldata({ syncMode }),
+    });
+};
+
+/**
+ * Encodes an `updateTotalAssetsLifespan(uint128 lifespan)` call.
+ * Selector: 0xae16ea8c
+ * Role: Owner (Admin)
+ *
+ * Sets the duration (in seconds) for which a published NAV remains valid.
+ * After `lifespan` seconds, `isTotalAssetsValid()` returns false and the valuation
+ * manager must call `updateNewTotalAssets` to publish a fresh NAV before the next
+ * settlement can proceed.
+ *
+ * The Valuation Manager calls `expireTotalAssets()` to invalidate early.
+ * The Admin calls this to adjust the lifespan window.
+ */
+export const LagoonV2UpdateTotalAssetsLifespanCalldata = ({ lifespan }: { lifespan: bigint }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateTotalAssetsLifespan",
+        args: [lifespan],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateTotalAssetsLifespanTrx = ({
+    vault,
+    lifespan,
+}: {
+    vault: Address;
+    lifespan: bigint;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateTotalAssetsLifespanCalldata({ lifespan }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Guardrails — Admin
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes an `updateGuardrails((uint256,int256) guardrails)` call.
+ * Selector: 0xced9a8de
+ * Role: Owner (Admin)
+ *
+ * Sets the guardrail bounds for `updateNewTotalAssets`. When guardrails are
+ * activated (via `updateActivated(true)`), any NAV update that would move
+ * totalAssets outside [currentTotalAssets * (1 + lowerRate/1e18),
+ * currentTotalAssets * (1 + upperRate/1e18)] will revert.
+ *
+ * The Security Council can bypass guardrails via `securityCouncilUpdateTotalAssets`.
+ *
+ * @param guardrails.upperRate - Max allowed NAV increase as a WAD multiplier
+ *   (e.g. 1e17 = 10% max increase). uint256.
+ * @param guardrails.lowerRate - Max allowed NAV decrease as a signed WAD multiplier
+ *   (e.g. -1e17 = 10% max decrease). int256, must be <= 0 for a decrease bound.
+ */
+export const LagoonV2UpdateGuardrailsCalldata = ({ guardrails }: { guardrails: LagoonV2Guardrails }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateGuardrails",
+        args: [{ upperRate: guardrails.upperRate, lowerRate: guardrails.lowerRate }],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateGuardrailsTrx = ({
+    vault,
+    guardrails,
+}: {
+    vault: Address;
+    guardrails: LagoonV2Guardrails;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateGuardrailsCalldata({ guardrails }),
+    });
+};
+
+/**
+ * Encodes an `updateActivated(bool activated)` call.
+ * Selector: 0xdc324cb2
+ * Role: Owner (Admin)
+ *
+ * Enables or disables the guardrails for NAV updates.
+ * When `activated = true`, `updateNewTotalAssets` enforces the bounds set by
+ * `updateGuardrails`. When `false`, guardrails are bypassed.
+ */
+export const LagoonV2UpdateActivatedCalldata = ({ activated }: { activated: boolean }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateActivated",
+        args: [activated],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateActivatedTrx = ({
+    vault,
+    activated,
+}: {
+    vault: Address;
+    activated: boolean;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateActivatedCalldata({ activated }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Security Council — guardrail bypass NAV update
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a `securityCouncilUpdateTotalAssets(uint256 newTotalAssets)` call.
+ * Selector: 0xdeb337a5
+ * Role: Security Council
+ *
+ * Publishes a new NAV, bypassing all guardrail bounds. Only callable by the
+ * address set as `securityCouncil`. Use in emergencies where the normal
+ * `updateNewTotalAssets` path would revert due to guardrail violations (e.g.
+ * after a significant NAV drawdown that exceeds the `lowerRate` bound).
+ *
+ * This directly sets the vault's total assets — verify the value before calling.
+ */
+export const LagoonV2SecurityCouncilUpdateTotalAssetsCalldata = ({
+    newTotalAssets,
+}: {
+    newTotalAssets: bigint;
+}): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "securityCouncilUpdateTotalAssets",
+        args: [newTotalAssets],
+    }) as HexString;
+};
+
+export const lagoonV2SecurityCouncilUpdateTotalAssetsTrx = ({
+    vault,
+    newTotalAssets,
+}: {
+    vault: Address;
+    newTotalAssets: bigint;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2SecurityCouncilUpdateTotalAssetsCalldata({ newTotalAssets }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Sanctions — Admin
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a `setExternalSanctionsList(address sanctionsList)` call.
+ * Selector: 0x7de5c4f4
+ * Role: Owner (Admin)
+ *
+ * Sets the external sanctions oracle address (e.g. Chainalysis OFAC sanctions
+ * list at 0x40C57923924B5c5c5455c48D93317139ADDaC8fb). When set to a non-zero
+ * address, the vault will reject transfers from/to addresses that appear on the
+ * sanctions list. Set to `address(0)` to disable external sanctions checking.
+ */
+export const LagoonV2SetExternalSanctionsListCalldata = ({ sanctionsList }: { sanctionsList: Address }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "setExternalSanctionsList",
+        args: [sanctionsList],
+    }) as HexString;
+};
+
+export const lagoonV2SetExternalSanctionsListTrx = ({
+    vault,
+    sanctionsList,
+}: {
+    vault: Address;
+    sanctionsList: Address;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2SetExternalSanctionsListCalldata({ sanctionsList }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Kill-switches — Admin (ONE-WAY, IRREVERSIBLE)
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a `lockUpdateSafe()` call.
+ * Selector: 0x8c9881a9
+ * Role: Owner (Admin)
+ *
+ * WARNING: IRREVERSIBLE. Permanently locks the ability to update the Safe address
+ * that controls settlement. Once called, the vault's Safe cannot be changed, ever.
+ * Only call after confirming the Safe address is correct and the Safe is operational.
+ */
+export const LagoonV2LockUpdateSafeCalldata = (): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "lockUpdateSafe",
+        args: [],
+    }) as HexString;
+};
+
+export const lagoonV2LockUpdateSafeTrx = ({ vault }: { vault: Address }): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2LockUpdateSafeCalldata(),
+    });
+};
+
+/**
+ * Encodes a `lockSuperOperator()` call.
+ * Selector: 0x32c06a4e
+ * Role: Owner (Admin)
+ *
+ * WARNING: IRREVERSIBLE. Permanently disables the Super Operator role. Once
+ * called, `updateSuperOperator` will always revert and no address can ever be
+ * granted Super Operator privileges on this vault again.
+ * Only call if you intend to permanently disable super-operator batch claim functionality.
+ */
+export const LagoonV2LockSuperOperatorCalldata = (): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "lockSuperOperator",
+        args: [],
+    }) as HexString;
+};
+
+export const lagoonV2LockSuperOperatorTrx = ({ vault }: { vault: Address }): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2LockSuperOperatorCalldata(),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Batch claim — Super Operator
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a `claimSharesOnBehalf(address[] receivers)` call.
+ * Selector: 0xf15be6f9
+ * Role: Super Operator
+ *
+ * Batch-claims settled shares on behalf of depositors who have not yet called
+ * `claimShares` themselves. Each address in `receivers` must have a pending
+ * settled deposit for the current or a past epoch.
+ *
+ * Useful for onboarding flows where the operator wants to distribute shares to
+ * newly admitted depositors without requiring each depositor to submit a separate
+ * claim transaction.
+ */
+export const LagoonV2ClaimSharesOnBehalfCalldata = ({ receivers }: { receivers: Address[] }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "claimSharesOnBehalf",
+        args: [receivers],
+    }) as HexString;
+};
+
+export const lagoonV2ClaimSharesOnBehalfTrx = ({
+    vault,
+    receivers,
+}: {
+    vault: Address;
+    receivers: Address[];
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2ClaimSharesOnBehalfCalldata({ receivers }),
+    });
+};
+
+/**
+ * Encodes a `claimAssetsOnBehalf(address[] receivers)` call.
+ * Selector: 0x26d6c82f
+ * Role: Super Operator
+ *
+ * Batch-claims settled underlying assets on behalf of redeemers who have not yet
+ * called `claimAssets` themselves. Each address in `receivers` must have a pending
+ * settled redemption for the current or a past epoch.
+ *
+ * Symmetric to `claimSharesOnBehalf` but for the redeem path.
+ */
+export const LagoonV2ClaimAssetsOnBehalfCalldata = ({ receivers }: { receivers: Address[] }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "claimAssetsOnBehalf",
+        args: [receivers],
+    }) as HexString;
+};
+
+export const lagoonV2ClaimAssetsOnBehalfTrx = ({
+    vault,
+    receivers,
+}: {
+    vault: Address;
+    receivers: Address[];
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2ClaimAssetsOnBehalfCalldata({ receivers }),
+    });
+};
+
+// ---------------------------------------------------------------------------
+// Metadata — Admin
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes an `updateName(string name)` call.
+ * Selector: 0x84da92a7
+ * Role: Owner (Admin)
+ *
+ * Updates the ERC20 `name()` of the vault token. Note that this only updates
+ * the on-chain storage value; any off-chain caches (block explorers, dApps) will
+ * need to refresh.
+ */
+export const LagoonV2UpdateNameCalldata = ({ name }: { name: string }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateName",
+        args: [name],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateNameTrx = ({ vault, name }: { vault: Address; name: string }): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateNameCalldata({ name }),
+    });
+};
+
+/**
+ * Encodes an `updateSymbol(string symbol)` call.
+ * Selector: 0x537f5312
+ * Role: Owner (Admin)
+ *
+ * Updates the ERC20 `symbol()` of the vault token. Same caveats as `updateName`
+ * regarding off-chain cache invalidation.
+ */
+export const LagoonV2UpdateSymbolCalldata = ({ symbol }: { symbol: string }): HexString => {
+    return encodeFunctionData({
+        abi: lagoonV2VaultAbi,
+        functionName: "updateSymbol",
+        args: [symbol],
+    }) as HexString;
+};
+
+export const lagoonV2UpdateSymbolTrx = ({ vault, symbol }: { vault: Address; symbol: string }): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: vault,
+        value: 0n,
+        data: LagoonV2UpdateSymbolCalldata({ symbol }),
+    });
+};