zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/contractInterface.ts

@@ -0,0 +1,465 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * contractInterface.ts
+ *
+ * Public contract interface: event Structs, slot/grace constants, duration
+ * helpers, and a minimal `LicensingAppEventsContract` SmartContract subclass
+ * that has the events declaration but no @method bodies.
+ *
+ * The full `LicensingApp` (with provable method bodies) lives in the private
+ * zklicensing-app package; only the things needed to decode events and reason
+ * about durations are published here so a public verify service can replay
+ * the archive without pulling in the contract source.
+ *
+ * `CANONICAL_VK_HASH` is the verification-key hash of the published
+ * `LicensingApp` circuit. Bump it whenever the on-chain zkApp changes
+ * and rerun the backend's boot assertion (see zklicensing-app/src/keeperService.ts)
+ * / the verify service's `ensureCompiled()` check to catch drift.
+ */
+
+import { Bool, declareState, fetchAccount, Field, PublicKey, SmartContract, Struct, UInt32, UInt64, MerkleMap } from 'o1js';
+
+// ------------------------------------------------------------
+// EVENT STRUCTS
+// ------------------------------------------------------------
+
+// Struct() returns a class whose type references o1js internals that fall
+// outside this package's rootDir (npm hoists o1js to the workspace root).
+// Annotating each export as `any` keeps tsc from inferring (and therefore
+// emitting) those internal type references, so the generated declarations
+// stay self-contained.
+//
+// The clean alternative — `export class X extends Struct({...}) {}` as the
+// mina-fungible-token repo does — only works when o1js sits inside rootDir,
+// which a workspace member can't guarantee.
+
+// `cap` is carried so that a backend reconstructing the license from archive
+// events (e.g. after losing its in-memory intent map to a restart) can
+// rehydrate the exact LicenseLeaf that was committed on-chain. Without it,
+// leafFromRecord() would default cap to UInt32.zero and every follow-up
+// root-mutating proof (renew, refund, bind, unbind) would fail the
+// in-circuit hash check.
+//
+// `deviceSlotsRoot` / `deviceSlotsFilled` are omitted deliberately: at issue
+// time they are always EMPTY_DEVICE_SLOTS_ROOT / 0. The backend's rehydration
+// uses those defaults, matching the leaf the circuit wrote.
+//
+// The leaf carries no separate ownerPubKeyHash — `licenseHash` IS the owner-
+// pubkey commitment (buyLicense asserts them equal), so it doesn't need to
+// ride in the event either.
+export const LicenseIssuedEvent: any = Struct({
+  licenseHash: Field,
+  buyer:       PublicKey,
+  amount:      UInt64,
+  slot:        UInt32,
+  expirySlot:  UInt32,
+  cap:         UInt32,
+});
+export type LicenseIssuedEvent = any;
+
+export const ExpiryUpdateEvent: any = Struct({
+  licenseHash: Field,
+  newExpiry:   UInt32,
+});
+export type ExpiryUpdateEvent = any;
+
+export const PriceUpdatedEvent: any = Struct({
+  priceMonthly:   UInt64,
+  priceYearly:    UInt64,
+  priceFiveYear:  UInt64,
+  pricePerpetual: UInt64,
+});
+export type PriceUpdatedEvent = any;
+
+export const AppCreatedEvent: any = Struct({
+  vendor: PublicKey,
+  /** The app this one continues (a redeploy: it starts with that app's licenses); PublicKey.empty() for a first generation. */
+  predecessor: PublicKey,
+  /** The licenses tree it starts with: empty, or its predecessor's frozen root. */
+  licensesRoot: Field,
+});
+export type AppCreatedEvent = any;
+
+// Emitted by `retire`: the app is frozen at `licensesRoot` for a redeploy;
+// its successor starts with that tree (initializeSuccessor). `by` is the key
+// that signed it (the vendor's or the platform's).
+// `forced`: the platform retired it with purchases still in escrow (their
+// funds stay on the retired contract, which settles nothing any more).
+export const AppRetiredEvent: any = Struct({ licensesRoot: Field, by: PublicKey, successor: PublicKey, forced: Bool });
+export type AppRetiredEvent = any;
+
+/**
+ * What the vendor or the platform signs to retire an app: bound to the app,
+ * its frozen root, the one successor that may start from it, and `force`
+ * (only the platform may: retire with purchases in escrow, whose funds then
+ * stay on the retired contract).
+ */
+export const APP_RETIRE_TAG: Field = Field(0x7a6b726574697265n); // "zkretire"
+export function appRetireMessage(app: PublicKey, licensesRoot: Field, successor: PublicKey, force: Bool): Field[] {
+  return [APP_RETIRE_TAG, ...app.toFields(), licensesRoot, ...successor.toFields(), force.toField()];
+}
+
+/**
+ * LicensingApp's on-chain state, in declaration order (appState index of
+ * each field; a PublicKey takes two). A successor's initializeSuccessor
+ * reads its predecessor's through account preconditions.
+ */
+export const LICENSING_APP_STATE = {
+  licensesRoot: 0, vendorX: 1, vendorIsOdd: 2, escrowRoot: 3, pricesPacked: 4,
+  version: 5, ancestorsRoot: 6, forkActivationSlot: 7, deviceCap: 8, retired: 9,
+  successorX: 10, successorIsOdd: 11,
+  payoutX: 12, payoutIsOdd: 13, pendingPayoutX: 14, pendingPayoutIsOdd: 15, pendingPayoutSlot: 16,
+  platformX: 17, platformIsOdd: 18, treasuryX: 19, treasuryIsOdd: 20, platformEpoch: 21,
+  vendorNonce: 22, networkId: 23,
+} as const;
+
+// ------------------------------------------------------------
+// KEYS: the platform key, payout addresses, the vendor key, license owners
+// ------------------------------------------------------------
+
+/** Deterministic Field from a short ASCII label (≤ 31 bytes). */
+function tagField(label: string): Field {
+  let v = 0n;
+  for (const ch of label) v = (v << 8n) | BigInt(ch.charCodeAt(0));
+  return Field(v);
+}
+
+export const KEY_TAGS: Readonly<Record<'PLATFORM_KEY' | 'PLATFORM_RECOVER' | 'VENDOR_KEY' | 'LICENSE_TRANSFER', Field>> = {
+  PLATFORM_KEY:     tagField('zkLicensing/v1/platformKey'),
+  PLATFORM_RECOVER: tagField('zkLicensing/v1/platformRecover'),
+  VENDOR_KEY:       tagField('zkLicensing/v1/vendorKey'),
+  LICENSE_TRANSFER: tagField('zkLicensing/v1/licenseMove'),
+};
+
+/**
+ * The platform's key (signs platform retires and cancels), its treasury
+ * (receives the 2%) and how many times they changed, as every app and
+ * registry holds them. A new contract starts with the current ones (the
+ * keeper checks them before listing it); a successor carries its
+ * predecessor's over, checked on chain.
+ */
+export const PlatformState: any = Struct({ key: PublicKey, treasury: PublicKey, epoch: UInt32 });
+export type PlatformState = any;
+
+/**
+ * A change of the platform key and treasury: signed by the current platform
+ * key and the new one. Bound to the network and the next epoch, not to a
+ * contract, so one pair of signatures updates every app and registry on the
+ * network (anyone may send them; each contract takes it once).
+ */
+export function platformKeyMessage(a: { network: Field; epoch: UInt32; key: PublicKey; treasury: PublicKey }): Field[] {
+  return [KEY_TAGS.PLATFORM_KEY, a.network, a.epoch.value, ...a.key.toFields(), ...a.treasury.toFields()];
+}
+
+/**
+ * The same, signed by the offline recovery key alone (compiled into the
+ * circuits): it can always set a new platform key and treasury, lost or
+ * stolen, at any epoch above a contract's current one.
+ */
+export function platformRecoverMessage(a: { network: Field; epoch: UInt32; key: PublicKey; treasury: PublicKey }): Field[] {
+  return [KEY_TAGS.PLATFORM_RECOVER, a.network, a.epoch.value, ...a.key.toFields(), ...a.treasury.toFields()];
+}
+
+/** A new vendor key for an app: signed by the current vendor key and the new one; `nonce` is the app's vendorNonce. */
+export function vendorKeyMessage(a: { network: Field; app: PublicKey; nonce: UInt32; vendor: PublicKey }): Field[] {
+  return [KEY_TAGS.VENDOR_KEY, a.network, ...a.app.toFields(), a.nonce.value, ...a.vendor.toFields()];
+}
+
+/**
+ * A license moving to a new owner key (`to` = ownerPubKeyHash of the new
+ * key): signed by the current owner key and the new one, over the license
+ * as it is now (its leaf hash) and a last slot it may land by.
+ */
+export function licenseTransferMessage(a: { network: Field; app: PublicKey; leafHash: Field; to: Field; validUntil: UInt32 }): Field[] {
+  return [KEY_TAGS.LICENSE_TRANSFER, a.network, ...a.app.toFields(), a.leafHash, a.to, a.validUntil.value];
+}
+
+/**
+ * How long a new payout address waits before it takes effect: 48 hours at
+ * 90 s per slot. Payments keep going to the current one until it is
+ * applied, and the owner can cancel it meanwhile.
+ */
+export const PAYOUT_DELAY_SLOTS_N = 1_920;
+
+/** A payout address was proposed; anyone may apply it from `effectiveSlot` on. */
+export const PayoutProposedEvent: any = Struct({ payout: PublicKey, effectiveSlot: UInt32 });
+export type PayoutProposedEvent = any;
+/** The payout address now in use (applied), or the pending one cancelled (`applied` false). */
+export const PayoutChangedEvent: any = Struct({ payout: PublicKey, applied: Bool });
+export type PayoutChangedEvent = any;
+export const PlatformChangedEvent: any = Struct({ platform: PlatformState, byRecovery: Bool });
+export type PlatformChangedEvent = any;
+export const VendorChangedEvent: any = Struct({ vendor: PublicKey, nonce: UInt32 });
+export type VendorChangedEvent = any;
+/**
+ * A license moved to a new owner key: the same leaf under `to`. `wallet` is
+ * the transaction's sender, the new owner's wallet that paid for it (as
+ * LicenseIssuedEvent's `buyer`), so a replay lists it under that wallet.
+ */
+export const LicenseTransferredEvent: any = Struct({ from: Field, to: Field, wallet: PublicKey });
+export type LicenseTransferredEvent = any;
+
+// Emitted by `bind` when the buyer's device commitment lands in a slot on
+// their license leaf. `deviceCommitment = Poseidon(devicePubKeyHash)` — the
+// raw pubkey is never revealed. `slotIndex` is 0-based within the license's
+// fixed-size slot array (see DEVICE_SLOT_CAP).
+//
+// `boundAtSlot` carries the circuit's proof-time `globalSlotSinceGenesis` —
+// the exact value packed into the leaf's `freedAt` via `packSlotTimes(
+// currentSlot, 0)`. Off-chain backends rebuilding `deviceSlotsRoot` MUST use
+// this, not the block's globalSlot: the tx's precondition allows any block
+// slot within TOLERANCE_WINDOW of proof time, so block-slot != proof-slot in
+// the general case, and any mismatch flips the packed field, the leaf hash,
+// and the aggregate `licensesRoot`. Follows the same pattern as
+// `LicenseIssuedEvent.slot`.
+export const DeviceBoundEvent: any = Struct({
+  licenseHash:      Field,
+  slotIndex:        UInt32,
+  deviceCommitment: Field,
+  boundAtSlot:      UInt32,
+});
+export type DeviceBoundEvent = any;
+
+// Emitted by `unbind` when a slot is freed. `slotIndex` stays occupied in the
+// array (`slotFreedAt` stamp stays set) so the cooldown timer starts; the
+// slot's `occupied` field goes to Field(0). Any device holding the license's
+// ownership key can trigger this — remote log-off is by design.
+//
+// `freedAtSlot` carries the circuit's proof-time `globalSlotSinceGenesis` —
+// the value packed into the leaf's `freedAt` via `packSlotTimes(preservedBound,
+// currentSlot)`. Same off-chain reconstruction reason as `DeviceBoundEvent.
+// boundAtSlot`. The preserved `boundAtSlot` is not re-emitted; the backend
+// reads it from its own record (which still has the earlier bind's stamp).
+export const DeviceUnboundEvent: any = Struct({
+  licenseHash: Field,
+  slotIndex:   UInt32,
+  freedAtSlot: UInt32,
+});
+export type DeviceUnboundEvent = any;
+
+// ------------------------------------------------------------
+// CONSTANTS (slot math — 90 s/slot after Mesa upgrade)
+// ------------------------------------------------------------
+
+// Plain numbers, in an o1js-free module so the package root (verifyLicense)
+// can use them without o1js installed; re-exported here unchanged.
+import {
+  MONTHLY_SLOTS_N, ONE_YEAR_SLOTS_N, FIVE_YEAR_SLOTS_N, PERPETUAL_SLOTS_N,
+  REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT_N, SLOTS_PER_DAY_N,
+} from './slotConstants.js';
+export {
+  MONTHLY_SLOTS_N, ONE_YEAR_SLOTS_N, FIVE_YEAR_SLOTS_N, PERPETUAL_SLOTS_N,
+  REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT_N, SLOTS_PER_DAY_N,
+};
+
+// Slot tolerance for the globalSlotSinceGenesis precondition. Applied uniformly to
+// every method that reads currentSlot. 40 slots × 90 s = 1 hour — sized to
+// clear the honest-user prove+wallet+mempool latency envelope. The refund vs
+// release windows stay disjoint by construction: requestRefund asserts against
+// the lower bound (currentSlot ≤ purchaseSlot + REFUND_WINDOW), releaseFunds
+// asserts against a threshold shifted by +TOLERANCE_WINDOW so neither can
+// land on the same real slot as the other. See AUDIT_BRIEF.md §7.
+export const TOLERANCE_WINDOW_N = 40;
+
+// How far before a successor's fork activation slot a license's grace period
+// may have ended and still qualify for the fork bump (effectiveExpirySlot).
+// The bump exists for licenses that lapsed because the pre-fork sales freeze
+// blocked renewal; the freeze starts at hardforkSlot - REFUND_WINDOW_N -
+// margin (~15_500 slots). 20_160 slots = 21 days covers that with slack.
+// Licenses whose grace ran out earlier lapsed normally and keep their expiry.
+// The keeper warns at startup if FREEZE_AFTER_SLOT sits further back.
+export const MIGRATION_BUMP_LOOKBACK_N = 20_160;
+
+/**
+ * A license's expiry as the app's contract treats it: a successor deployed
+ * across a Mina hardfork (forkActivationSlot > 0) starts with its
+ * predecessor's licenses, and a license that lapsed during the pre-fork
+ * freeze (expiry before the fork slot, but within grace + lookback of it)
+ * counts as expiring at the fork slot, so the 7-day grace runs from there.
+ * renewLicense applies the same rule in-circuit; verification uses this.
+ */
+export function effectiveExpirySlot(expirySlot: number, forkActivationSlot = 0): number {
+  return forkBumpedExpiry(expirySlot, forkActivationSlot, GRACE_PERIOD_N);
+}
+
+/**
+ * The fork bump shared by licenses and permits: an expiry before the fork
+ * slot, but within `grace` + MIGRATION_BUMP_LOOKBACK_N of it (it lapsed
+ * during the pre-fork freeze, when it couldn't be renewed), counts as
+ * expiring at the fork slot. Licenses use their 7-day grace, permits their
+ * registry's grace period.
+ */
+export function forkBumpedExpiry(expirySlot: number, forkActivationSlot: number, grace: number): number {
+  return expirySlot < forkActivationSlot && expirySlot + grace + MIGRATION_BUMP_LOOKBACK_N >= forkActivationSlot
+    ? forkActivationSlot : expirySlot;
+}
+
+export const EMPTY: Field      = Field(0);
+export const EMPTY_ROOT: Field = new MerkleMap().getRoot();
+
+// ------------------------------------------------------------
+// DURATION HELPERS
+// ------------------------------------------------------------
+
+export const DURATION_LABELS = ['1 Month', '1 Year', '5 Years', 'Perpetual'] as const;
+export type DurationLabel = typeof DURATION_LABELS[number];
+
+export const DURATION_INDEX = { '1 Month': 0, '1 Year': 1, '5 Years': 2, 'Perpetual': 3 } as const;
+
+export function durationSlotsFromLabel(label?: string | null): number | null {
+  if (label === '1 Month')  return MONTHLY_SLOTS_N;
+  if (label === '1 Year')   return ONE_YEAR_SLOTS_N;
+  if (label === '5 Years')  return FIVE_YEAR_SLOTS_N;
+  if (label === 'Perpetual') return PERPETUAL_SLOTS_N;
+  return null;
+}
+
+export function durationIndexFromLabel(label?: string | null): number | null {
+  if (label === '1 Month')   return 0;
+  if (label === '1 Year')    return 1;
+  if (label === '5 Years')   return 2;
+  if (label === 'Perpetual') return 3;
+  return null;
+}
+
+export function durationLabelFromIndex(idx: number): DurationLabel | null {
+  return DURATION_LABELS[idx] ?? null;
+}
+
+// ------------------------------------------------------------
+// EVENTS-ONLY CONTRACT
+//
+// A SmartContract subclass with the same `events: { ... }` declaration as
+// LicensingApp but no `@method` bodies. Used by archive-replay code to call
+// `.fetchEvents()` without depending on the private circuit source.
+// ------------------------------------------------------------
+
+export class LicensingAppEventsContract extends SmartContract {
+  events: any = {
+    appCreated:             AppCreatedEvent,
+    licenseIssued:          LicenseIssuedEvent,
+    licenseIssuedNoEscrow:  LicenseIssuedEvent,
+    licenseRenewed:         ExpiryUpdateEvent,
+    appRetired:             AppRetiredEvent,
+    refundIssued:           Field,
+    fundsReleased:          Field,
+    priceUpdated:           PriceUpdatedEvent,
+    deviceBound:            DeviceBoundEvent,
+    deviceUnbound:          DeviceUnboundEvent,
+    licenseTransferred:     LicenseTransferredEvent,
+    vendorChanged:          VendorChangedEvent,
+    payoutProposed:         PayoutProposedEvent,
+    payoutChanged:          PayoutChangedEvent,
+    platformChanged:        PlatformChangedEvent,
+  };
+}
+
+// State-slot layout mirrors LicensingApp's declareState(). Read-only from here
+// — no @method bodies exist. Consumers use `.version.get()`, `.licensesRoot.get()`
+// etc. after fetchAccount(). `pricesPacked` is a single Field with the four
+// 63-bit tier prices packed as [pM | pY<<63 | pF<<126 | pP<<189]; unpack with
+// `unpackPrices` if you need the individual tiers off-chain.
+declareState(LicensingAppEventsContract, {
+  licensesRoot:    Field,
+  vendor:          PublicKey,
+  escrowRoot:      Field,
+  pricesPacked:    Field,
+  version:         UInt32,
+  ancestorsRoot:   Field,
+  forkActivationSlot: UInt32,
+  deviceCap:       UInt32,
+  retired:         Field,
+  successor:       PublicKey,
+  payout:          PublicKey,
+  pendingPayout:   PublicKey,
+  pendingPayoutSlot: UInt32,
+  platform:        PublicKey,
+  treasury:        PublicKey,
+  platformEpoch:   UInt32,
+  vendorNonce:     UInt32,
+  networkId:       Field,
+} as any);
+
+// Off-chain mirror of the in-circuit price packing (see LicensingApp.ts). Kept
+// here so the events service can decode `pricesPacked` slots without pulling
+// the private contract source. Layout: four 63-bit tiers = 252 bits, fits in
+// the ~254-bit Field. Each tier's high bit is unused — a UInt64 written by
+// packPrices is range-checked to 63 bits in circuit.
+export function unpackPrices(packed: Field): {
+  priceMonthly:   UInt64;
+  priceYearly:    UInt64;
+  priceFiveYear:  UInt64;
+  pricePerpetual: UInt64;
+} {
+  const raw = packed.toBigInt();
+  const mask = (1n << 63n) - 1n;
+  return {
+    priceMonthly:   UInt64.from(raw & mask),
+    priceYearly:    UInt64.from((raw >> 63n) & mask),
+    priceFiveYear:  UInt64.from((raw >> 126n) & mask),
+    pricePerpetual: UInt64.from((raw >> 189n) & mask),
+  };
+}
+
+// ------------------------------------------------------------
+// SUPPORTED SOURCE VERSIONS
+//
+// On-chain `version` slot is set at init() and can never change (setPermissions
+// is impossible; setVerificationKey is impossibleDuringCurrentVersion). A
+// backend / verifier that only understands v1 state decodes must refuse to serve
+// a zkApp deployed from a different source revision — otherwise it could
+// mis-decode events or feed a stale state format to the verifier.
+//
+// Add new versions here once the corresponding decoder / verifier code path
+// lands. Never remove: dropping a version is a support-removal decision that
+// belongs in a release note, not silent breakage.
+// ------------------------------------------------------------
+
+export const SUPPORTED_LICENSING_APP_VERSIONS: readonly number[] = [1];
+
+// Read the immutable `version` slot from a deployed LicensingApp. Returns null
+// when the account is not (yet) a zkApp — caller decides whether to retry
+// (deploy still pending) or reject (wrong address).
+export async function fetchLicensingAppVersion(zkAppAddress: string): Promise<number | null> {
+  const pub = PublicKey.fromBase58(zkAppAddress);
+  await fetchAccount({ publicKey: pub });
+  const contract: any = new LicensingAppEventsContract(pub);
+  try {
+    const v = contract.version.get();
+    return Number(v.toString());
+  } catch {
+    return null;
+  }
+}
+
+// ------------------------------------------------------------
+// CANONICAL VK HASHES
+//
+// Per-generation, append-only. The backend boots with `LicensingApp.compile()`
+// and asserts the resulting VK hash matches `CANONICAL_VK_HASH` (the current
+// generation's row); the verify service resolves an address's generation via
+// AppRecord.deploymentHistory and asserts the on-chain VK hash matches
+// `CANONICAL_VK_HASHES[generation]`. Retired-generation licenses (e.g. a
+// 5-year buyer whose license lives on v1 after the platform bumped to v2/v3)
+// continue to verify because the historical row is still present. A genuine
+// old circuit deployed at a fresh address fails: the address is not in any
+// `deploymentHistory[]`, so the resolver returns null and verify rejects.
+//
+// Rules:
+//   - Append the new generation's row at each circuit release; never
+//     delete historical rows.
+//   - Bump `CURRENT_GENERATION` to the new key alongside the row.
+//   - `CANONICAL_VK_HASH` is derived from the record — drift test and backend
+//     boot-assert are unchanged.
+// ------------------------------------------------------------
+
+export const CANONICAL_VK_HASHES: Readonly<Record<number, string>> = {
+  1: '24356937757056509770089463595975375774248178850824042790271400407790662393035',
+  // 2: '…' — append at each circuit release, never delete.
+};
+
+export const CURRENT_GENERATION: number = 1;
+
+export const CANONICAL_VK_HASH: string = CANONICAL_VK_HASHES[CURRENT_GENERATION];

package/src/contractTypes.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * contractTypes.ts — `zklicensing/contract-types`
+ *
+ * The two contract types the platform runs and where they meet: the
+ * verification-key table by type. A missing type anywhere (manifest,
+ * well-known file, record) means `licensing`, so everything published
+ * before permits existed keeps its meaning.
+ */
+
+import { CANONICAL_VK_HASHES } from './contractInterface.js';
+import { CANONICAL_PERMIT_VK_HASHES } from './permitInterface.js';
+
+export type ContractType = 'licensing' | 'permits';
+export const CONTRACT_TYPES: readonly ContractType[] = ['licensing', 'permits'];
+
+/** Canonical VK hashes by contract type, each keyed by generation. */
+export const CANONICAL_VK_HASHES_BY_TYPE: Readonly<Record<ContractType, Readonly<Record<number, string>>>> = {
+  licensing: CANONICAL_VK_HASHES,
+  permits: CANONICAL_PERMIT_VK_HASHES,
+};
+
+/** Reads an optional `contractType` field; absent or unknown-but-empty → licensing. */
+export function contractTypeOf(value: { contractType?: unknown } | null | undefined): ContractType {
+  const t = value?.contractType;
+  if (t === undefined || t === null || t === '') return 'licensing';
+  if (t === 'licensing' || t === 'permits') return t;
+  throw new Error(`unknown contractType: ${String(t)}`);
+}