feat(cct-sdk): Add deploy verification + unify ops

ccip-sdk/src/cct/evm/index.ts

@@ -133,7 +133,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
   /**
    * Builds an unsigned `CrossChainToken` (v2.0.0) deployment tx (for multisig / offline
    * signing). The deployed address is only known once mined, so it is NOT returned here —
-   * use {@link deployToken} to deploy and receive `{ hash, contractAddress }`.
+   * use {@link deployToken} to deploy and receive `{ hash, contractAddress, verification }`.
    * @remarks Same post-deploy roles caveat as {@link deployToken} — the pool needs
    * `grantMintAndBurnRoles` before it can bridge.
    * @throws {@link CCTParamsInvalidError} if any param is invalid
@@ -155,7 +155,8 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
 
   /**
    * Deploys a `CrossChainToken` (v2.0.0), signing + submitting with `opts.wallet`; resolves
-   * to the tx hash and the newly deployed token address.
+   * to the tx hash, the newly deployed token address, and a `verification`
+   * ({@link ExplorerVerificationInput}) for verifying the source on a block explorer.
    * @remarks Mint/burn are role-gated (`MINTER_ROLE`/`BURNER_ROLE`); the token grants neither
    * to any pool at deploy. `preMint` mints initial supply to `preMintRecipient`, but before a
    * pool can bridge, `burnMintRoleAdmin` must `grantMintAndBurnRoles(pool)`.
@@ -164,7 +165,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
    * @throws {@link CCTTxFailedError} if the tx reverts, fails, or mines without an address
    * @example
    * ```typescript
-   * const { hash, contractAddress } = await cct.deployToken({
+   * const { hash, contractAddress, verification } = await cct.deployToken({
    *   name: 'My Token',
    *   symbol: 'MTK',
    *   decimals: 18,
@@ -183,7 +184,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
    * the pool contract — a `DeployableTokenPoolType` (`BurnMintTokenPool`, `BurnFromMintTokenPool`,
    * `BurnWithFromMintTokenPool`, or `LockReleaseTokenPool`; all v2.0.0). The deployed address is
    * only known once mined, so it is NOT returned here — use {@link deployTokenPool} to receive
-   * `{ hash, contractAddress }`.
+   * `{ hash, contractAddress, verification }`.
    * @remarks Same post-deploy setup caveat as {@link deployTokenPool} — a fresh pool must be
    * registered, role-granted, and lane-configured before it can bridge. `LockReleaseTokenPool`
    * additionally requires a pre-deployed `lockbox` ({@link DeployLockReleaseTokenPoolParams})
@@ -208,8 +209,9 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
   }
 
   /**
-   * Deploys a token pool, signing + submitting with `opts.wallet`; resolves to the tx hash
-   * and the newly deployed pool address. `type` selects the pool contract (a
+   * Deploys a token pool, signing + submitting with `opts.wallet`; resolves to the tx hash, the
+   * newly deployed pool address, and a `verification` ({@link ExplorerVerificationInput}) for
+   * verifying the source on a block explorer. `type` selects the pool contract (a
    * `DeployableTokenPoolType`, v2.0.0).
    * @remarks Deploying the pool alone doesn't make it usable: register it with {@link setPool},
    * grant it the token's mint/burn roles (`grantMintAndBurnRoles`), and configure its remote
@@ -223,7 +225,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
    * @throws {@link CCTTxFailedError} if the tx reverts, fails, or mines without an address
    * @example
    * ```typescript
-   * const { hash, contractAddress } = await cct.deployTokenPool({
+   * const { hash, contractAddress, verification } = await cct.deployTokenPool({
    *   type: 'LockReleaseTokenPool',
    *   token: '0xToken...',
    *   localTokenDecimals: 18,
@@ -242,7 +244,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
    * Builds an unsigned `ERC20LockBox` (v2.0.0) deployment tx (for multisig / offline signing).
    * A lockbox escrows a single `token` for `LockReleaseTokenPool`s. The deployed address is
    * only known once mined, so it is NOT returned here — use {@link deployLockbox} to receive
-   * `{ hash, contractAddress }`.
+   * `{ hash, contractAddress, verification }`.
    * @remarks Deploy the lockbox before its pool, then authorize the pool on it with
    * {@link authorizeLockboxCallers} before the pool can lock/release.
    * @throws {@link CCTParamsInvalidError} if any param is invalid
@@ -260,7 +262,8 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
 
   /**
    * Deploys an `ERC20LockBox` (v2.0.0), signing + submitting with `opts.wallet`; resolves to the
-   * tx hash and the newly deployed lockbox address.
+   * tx hash, the newly deployed lockbox address, and a `verification`
+   * ({@link ExplorerVerificationInput}) for verifying the source on a block explorer.
    * @remarks Step two of the lock/release flow: {@link deployToken} → {@link deployLockbox} →
    * {@link deployTokenPool} (passing this lockbox) → {@link authorizeLockboxCallers}
    * (`addedCallers: [pool]`) → {@link setPool} → configure lanes.
@@ -269,7 +272,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
    * @throws {@link CCTTxFailedError} if the tx reverts, fails, or mines without an address
    * @example
    * ```typescript
-   * const { hash, contractAddress } = await cct.deployLockbox({
+   * const { hash, contractAddress, verification } = await cct.deployLockbox({
    *   token: '0xToken...',
    *   wallet,
    * })
@@ -302,10 +305,7 @@ export class EVMTokenManager extends TokenManager<typeof ChainFamily.EVM> {
 
   /**
    * Adds/removes authorized callers on an `ERC20LockBox`, signing + submitting with `opts.wallet`
-   * (the lockbox owner). Authorize the `LockReleaseTokenPool` before it can lock/release — until
-   * then its lock/release reverts `UnauthorizedCaller(pool)`.
-   * @remarks Depositing the lockbox's initial liquidity is a manual final step with no SDK op: the
-   * depositor must itself be an authorized caller and have ERC20-approved the lockbox.
+   * (the lockbox owner). Authorize the `LockReleaseTokenPool` before it can lock/release.
    * @throws {@link CCIPWalletInvalidError} if `wallet` is not a valid signer
    * @throws {@link CCTParamsInvalidError} if any param is invalid, or if no caller is supplied
    * @throws {@link CCTTxFailedError} if the tx reverts or fails
@@ -335,5 +335,10 @@ export type {
 } from './token-pool/operations/deploy-token-pool.ts'
 export type { DeployLockboxParams } from './lockbox/operations/deploy-lockbox.ts'
 export type { AuthorizeLockboxCallersParams } from './lockbox/operations/authorize-callers.ts'
-export type { DeployResult, EVMExecuteParams } from './operation.ts'
+export type {
+  DeployArtifact,
+  DeployResult,
+  EVMExecuteParams,
+  ExplorerVerificationInput,
+} from './operation.ts'
 export type { TransactionResult } from '../operation.ts'

ccip-sdk/src/cct/evm/lockbox/contracts.ts

@@ -0,0 +1,29 @@
+/**
+ * EVM lockbox contract layer for CCT: the cached `ERC20LockBox` {@link Interface}
+ * ({@link LOCKBOX_INTERFACE}) for calldata encoding, and its deploy artifact
+ * ({@link getLockboxArtifact}). Only one lockbox version is deployable, so there is no version
+ * framework here. Mirrors `token/contracts.ts`.
+ *
+ * @packageDocumentation
+ */
+
+import { Interface } from 'ethers'
+
+import ERC20_LOCKBOX_V2_0_0_ABI from '../artifacts/abi/V2_0_0/erc20-lockbox.ts'
+import ERC20_LOCKBOX_V2_0_0_BYTECODE from '../artifacts/bytecode/V2_0_0/erc20-lockbox.ts'
+import type { DeployArtifact } from '../operation.ts'
+
+/** Shared, cached `ERC20LockBox` interface for constructor and calldata encoding. */
+export const LOCKBOX_INTERFACE = new Interface(ERC20_LOCKBOX_V2_0_0_ABI)
+
+/** `ERC20LockBox` creation bytecode for `deployLockbox`. */
+export const LOCKBOX_BYTECODE = ERC20_LOCKBOX_V2_0_0_BYTECODE
+
+/** `ERC20LockBox` deploy artifact: contract name + ctor {@link Interface} + creation bytecode. */
+export function getLockboxArtifact(): DeployArtifact {
+  return {
+    contract: 'ERC20LockBox',
+    iface: LOCKBOX_INTERFACE,
+    bytecode: LOCKBOX_BYTECODE,
+  }
+}

ccip-sdk/src/cct/evm/lockbox/operations/authorize-callers.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { describe, it } from 'node:test'
 
-import { ZeroAddress, makeError } from 'ethers'
+import { ZeroAddress, getIcapAddress, makeError } from 'ethers'
 
 import { AuthorizeLockboxCallers } from './authorize-callers.ts'
 import { CCIPExecTxRevertedError, CCIPWalletInvalidError } from '../../../../errors/index.ts'
@@ -129,6 +129,33 @@ describe('AuthorizeLockboxCallers (cct/evm lockbox operation)', () => {
       )
     })
 
+    it('rejects a zero-address lockbox', async () => {
+      // a call to 0x0 hits no code, so it would mine as a successful no-op
+      await assert.rejects(
+        () =>
+          new AuthorizeLockboxCallers().generate(stubChain(), {
+            lockbox: ZeroAddress,
+            addedCallers: [POOL],
+          }),
+        (err: unknown) =>
+          err instanceof CCTParamsInvalidError &&
+          err.context.operation === 'authorizeLockboxCallers' &&
+          err.context.param === 'lockbox',
+      )
+    })
+
+    it('rejects the zero address written in ICAP form', async () => {
+      // isAddress() accepts ICAP, and this never equals ZeroAddress literally
+      await assert.rejects(
+        () =>
+          new AuthorizeLockboxCallers().generate(stubChain(), {
+            lockbox: getIcapAddress(ZeroAddress),
+            addedCallers: [POOL],
+          }),
+        (err: unknown) => err instanceof CCTParamsInvalidError && err.context.param === 'lockbox',
+      )
+    })
+
     it('rejects when no callers are supplied', async () => {
       await assert.rejects(
         () => new AuthorizeLockboxCallers().generate(stubChain(), { lockbox: LOCKBOX }),

ccip-sdk/src/cct/evm/lockbox/operations/authorize-callers.ts

@@ -6,24 +6,18 @@
  * @packageDocumentation
  */
 
-import { ZeroAddress } from 'ethers'
-
 import type { EVMChain } from '../../../../evm/index.ts'
 import type { UnsignedEVMTx } from '../../../../evm/types.ts'
-import { ChainFamily } from '../../../../networks.ts'
 import { CCTParamsInvalidError } from '../../../errors.ts'
-import { EVMOperation } from '../../operation.ts'
-import { validateAddress } from '../../validate.ts'
-import { LOCKBOX_INTERFACE } from '../interface.ts'
+import { EVMOperation, callTx } from '../../operation.ts'
+import { validateNonZeroAddress } from '../../validate.ts'
+import { LOCKBOX_INTERFACE } from '../contracts.ts'
 
 /**
  * Parameters for {@link AuthorizeLockboxCallers}. At least one caller across both arrays is required.
  * @remarks `AuthorizedCallers._applyAuthorizedCallerUpdates` applies `removedCallers` first, so an
  * address in both arrays ends up authorized. The list is a set: re-adding an existing caller is a
  * no-op (though `AuthorizedCallerAdded` still fires), and removing an absent one emits nothing.
- *
- * Two validations here are SDK-side strictness, not contract behaviour: on-chain only *adds* revert
- * `ZeroAddressNotAllowed`, and an update with both arrays empty is a successful owner-only no-op.
  */
 export interface AuthorizeLockboxCallersParams {
   /** Address of the `ERC20LockBox` to update. */
@@ -46,20 +40,16 @@ export class AuthorizeLockboxCallers extends EVMOperation<AuthorizeLockboxCaller
     addedCallers = [],
     removedCallers = [],
   }: AuthorizeLockboxCallersParams): void {
-    validateAddress(this.name, 'lockbox', lockbox)
+    validateNonZeroAddress(this.name, 'lockbox', lockbox)
     if (addedCallers.length + removedCallers.length === 0) {
       throw new CCTParamsInvalidError(
         this.name,
         'addedCallers',
         'at least one caller must be added or removed',
       )
     }
-    const validateCaller = (field: string, c: string, i: number): void => {
-      validateAddress(this.name, `${field}[${i}]`, c)
-      if (c === ZeroAddress) {
-        throw new CCTParamsInvalidError(this.name, `${field}[${i}]`, 'must not be the zero address')
-      }
-    }
+    const validateCaller = (field: string, c: string, i: number): void =>
+      validateNonZeroAddress(this.name, `${field}[${i}]`, c)
     addedCallers.forEach((c, i) => validateCaller('addedCallers', c, i))
     removedCallers.forEach((c, i) => validateCaller('removedCallers', c, i))
   }
@@ -72,6 +62,6 @@ export class AuthorizeLockboxCallers extends EVMOperation<AuthorizeLockboxCaller
     const data = LOCKBOX_INTERFACE.encodeFunctionData('applyAuthorizedCallerUpdates', [
       { addedCallers, removedCallers },
     ])
-    return { family: ChainFamily.EVM, transactions: [{ to: lockbox, data }] }
+    return callTx(lockbox, data)
   }
 }

ccip-sdk/src/cct/evm/lockbox/operations/deploy-lockbox.test.ts

@@ -109,7 +109,11 @@ describe('DeployLockbox (cct/evm lockbox operation)', () => {
         token: TOKEN,
         wallet: fakeSigner({ contractAddress: DEPLOYED }),
       })
-      assert.deepEqual(result, { hash: HASH, contractAddress: DEPLOYED })
+      assert.deepEqual(result, {
+        hash: HASH,
+        contractAddress: DEPLOYED,
+        verification: { contract: 'ERC20LockBox', encodedConstructorArgs: '0x' + W_TOKEN },
+      })
     })
 
     it('throws CCTTxFailedError when the receipt carries no contract address', async () => {

ccip-sdk/src/cct/evm/lockbox/operations/deploy-lockbox.ts

@@ -7,20 +7,11 @@
  * @packageDocumentation
  */
 
-import { ZeroAddress } from 'ethers'
+import type { Interface } from 'ethers'
 
-import type { EVMChain } from '../../../../evm/index.ts'
-import type { UnsignedEVMTx } from '../../../../evm/types.ts'
-import { CCTParamsInvalidError, CCTTxFailedError } from '../../../errors.ts'
-import {
-  type DeployResult,
-  type EVMExecuteParams,
-  EVMOperation,
-  deploymentTx,
-} from '../../operation.ts'
-import { submit } from '../../submit.ts'
-import { validateAddress } from '../../validate.ts'
-import { LOCKBOX_BYTECODE, LOCKBOX_INTERFACE } from '../interface.ts'
+import { type DeployArtifact, EVMDeployOperation } from '../../operation.ts'
+import { validateNonZeroAddress } from '../../validate.ts'
+import { getLockboxArtifact } from '../contracts.ts'
 
 /** Parameters for {@link DeployLockbox} — deploys `ERC20LockBox` (v2.0.0). */
 export interface DeployLockboxParams {
@@ -30,41 +21,22 @@ export interface DeployLockboxParams {
   sender?: string
 }
 
-/** Deploys an `ERC20LockBox`; `execute` resolves to `{ hash, contractAddress }`. */
-export class DeployLockbox extends EVMOperation<DeployLockboxParams> {
+/** Deploys an `ERC20LockBox`; `execute` resolves to `{ hash, contractAddress, verification }`. */
+export class DeployLockbox extends EVMDeployOperation<DeployLockboxParams> {
   readonly name = 'deployLockbox'
 
   /** Validates the constructor params before building init-code. */
   protected validate(params: DeployLockboxParams): void {
-    validateAddress(this.name, 'token', params.token)
-    if (params.token === ZeroAddress)
-      throw new CCTParamsInvalidError(this.name, 'token', 'must not be the zero address')
+    validateNonZeroAddress(this.name, 'token', params.token)
   }
 
-  /** Builds a deployment tx (no `to`): creation bytecode + ABI-encoded constructor args. */
-  protected buildUnsigned(_chain: EVMChain, params: DeployLockboxParams): UnsignedEVMTx {
-    return deploymentTx(LOCKBOX_BYTECODE, LOCKBOX_INTERFACE.encodeDeploy([params.token]))
+  /** Deploy artifact for `ERC20LockBox` (v2.0.0). */
+  protected artifact(): DeployArtifact {
+    return getLockboxArtifact()
   }
 
-  /**
-   * {@link generate}, then sign and submit; resolves to the tx hash and the newly deployed
-   * lockbox address (read from the mined receipt).
-   * @throws {@link CCTTxFailedError} if the tx mined without producing a contract address
-   */
-  override async execute(
-    chain: EVMChain,
-    params: EVMExecuteParams<DeployLockboxParams>,
-  ): Promise<DeployResult> {
-    const { response, receipt } = await submit(
-      chain,
-      params.wallet,
-      await this.generate(chain, params),
-      this.name,
-    )
-    if (!receipt.contractAddress)
-      throw new CCTTxFailedError(this.name, 'deployment produced no contract address', {
-        context: { txHash: response.hash },
-      })
-    return { hash: response.hash, contractAddress: receipt.contractAddress }
+  /** ABI-encodes the `ERC20LockBox` (v2.0.0) constructor args. */
+  protected encode(iface: Interface, p: DeployLockboxParams): string {
+    return iface.encodeDeploy([p.token])
   }
 }