types.ts

/** Ethereum transaction to be formatted. */
export interface Transaction {
  chainId: number;
  to: string;
  /** calldata hex string */
  data: string;
  value?: bigint;
  from?: string;
}

/**
 * A single call within an EIP-5792 batch.
 */
export interface Eip5792Call {
  to?: string;
  data?: string;
  value?: bigint;
}

/**
 * An EIP-5792 batch of calls sharing the same sender and chain.
 * Pass to {@link formatEip5792Batch} to format all calls at once.
 */
export interface Eip5792Batch {
  from?: string;
  chainId: number;
  calls: Eip5792Call[];
}

/** EIP-712 type member definition. */
export interface TypeMember {
  name: string;
  type: string;
}

/**
 * ERC-7730 field type category — the base Solidity type that determines
 * which display formats can be applied:
 *   - address → addressName, tokenTicker, interoperableAddressName, raw
 *   - uint/int → amount, tokenAmount, nftName, date, duration, unit, enum, chainId, raw
 *   - bytes   → calldata, raw
 *   - string  → raw
 *   - bool    → raw
 */
export type FieldType =
  | "address"
  | "bool"
  | "string"
  | "bytes"
  | "uint"
  | "int";

/** EIP-712 typed data domain. */
export interface TypedDataDomain {
  name?: string;
  version?: string;
  chainId?: number | string;
  verifyingContract?: string;
  salt?: string;
}

/** EIP-712 typed data input. */
export interface TypedData {
  account: string; // Needed for @.from references
  types: Record<string, TypeMember[]>;
  primaryType: string;
  domain: TypedDataDomain;
  message: Record<string, unknown>;
}

/** Machine-readable warning code. */
export type WarningCode =
  | "UNEXPECTED_LIB_ERROR" // indicates a bug in the library
  | "NO_DESCRIPTOR"
  | "DESCRIPTOR_FETCH_ERROR"
  | "INVALID_CALLDATA_HEX"
  | "CALLDATA_TOO_SHORT"
  | "UNSUPPORTED_DOMAIN"
  | "DEPLOYMENT_MISMATCH"
  | "NO_FORMAT_MATCH"
  | "CALLDATA_DECODE_ERROR"
  | "MUSTMATCH_VIOLATION"
  | "UNSUPPORTED_NESTED_FIELD_GROUP"
  | "DEFINITIONS_RESOLUTION_ERROR"
  | "INVALID_DESCRIPTOR"
  | "INTERPOLATION_ERROR"
  | "UNKNOWN_TOKEN"
  | "UNKNOWN_ADDRESS"
  | "ADDRESS_TYPE_MISMATCH"
  | "CONTAINER_MISSING_CHAIN_ID"
  | "CONTAINER_MISSING_REQUIRED_PATH"
  | "ARGUMENT_TYPE_MISMATCH"
  | "DOMAIN_MISMATCH"
  | "EMPTY_ARRAY"
  | "UNKNOWN_NFT_COLLECTION"
  | "BUNDLED_ARRAY_SIZE_MISMATCH"
  | "FORMAT_PARAM_RESOLUTION_ERROR"
  | "UNKNOWN_ENCODING"
  | "UNKNOWN_BLOCK"
  | "UNKNOWN_CHAIN"
  | "PARAM_ARRAY_SIZE_MISMATCH"
  | "EMBEDDED_CALLDATA_NOT_SUPPORTED"
  | "DECRYPTION_FAILED"
  | "BATCH_VALUE_TRANSFER"
  | "BATCH_CONTRACT_CREATION"
  | "BATCH_INTERPOLATION_INCOMPLETE"
  | "BATCH_EMPTY"
  | "CYCLIC_INCLUDES"
  | "NO_TRUSTED_ATTESTATION"
  | "ATTESTATION_OPTIONS_INCOMPLETE";

/** Warning from formatting. */
export interface Warning {
  /** machine-readable warning code */
  code: WarningCode;
  /** human-readable warning message */
  message: string;
}

export interface RawCalldataFallback {
  /** function selector, e.g. "0x095ea7b3" */
  selector: string;
  /** hex-encoded ABI arguments */
  args: string[];
}

/**
 * Present on a DisplayField when format is "calldata". Contains the formatted
 * nested transaction, the resolved callee address, and the chain ID if it
 * differs from the outer transaction.
 */
export interface EmbeddedCalldata {
  /** Formatted display model for the nested transaction. */
  display: DisplayModel;
  /** Target address of the nested call (EIP-55 checksum format). */
  callee?: string;
  /**
   * Chain ID of the nested call — present only when it differs from the outer
   * container's chain ID.
   */
  chainId?: number;
}

/**
 * A single labeled field to display to the user.
 *
 * When clear-signing transactions with embedded calldata (nested
 * transactions), a calldata formatted field will have an embeddedCalldata
 * property containing the formatted nested transaction and resolved callee.
 */
export interface DisplayField {
  /** Label to show in the UI for this field. */
  label: string;
  /** Value to show in the UI for this field. */
  value: string;

  /**
   * For iterated array elements whose descriptor defines a `separator`:
   * the separator text with `{index}` substituted (e.g. "Recipient 0").
   * Per ERC-7730, wallets MUST display it before this field when present.
   */
  separator?: string;

  /**
   * Present when format is "calldata". The value property holds the full
   * embedded calldata as a hex string (including any prepended selector).
   * Wallets should prefer to render embeddedCalldata.display over the raw
   * value property. If no matching ERC-7730 descriptor is found or if the
   * wallet does not support embedded calldata, it MAY display a hash of the
   * value property (embedded calldata) instead.
   */
  embeddedCalldata?: EmbeddedCalldata;

  /**
   * The fieldType and format properties can be used to show type-specific
   * components. For example, for a fieldType of "address" the wallet can
   * display an address copy button.
   *
   * The fieldType corresponds to the underlying Solidity type.
   */
  fieldType: FieldType;
  /**
   * The format corresponds to the specific display format as per ERC-7730.
   */
  format: string;

  /**
   * For example for externally resolved data, wallets should display
   * a warning when encountering unknown entities.
   */
  warning?: Warning;

  /**
   * For formatted addresses (fieldType: "address"), wallets should also
   * display the raw value in some form.
   */
  rawAddress?: string;

  /**
   * For token amounts (format: "tokenAmount") the token address is returned.
   * Wallets can display it in case that the library failed to resolve token
   * metadata from the ExternalDataProvider. In this case, value will fall
   * back to the raw amount formatting and warning.code will be UNKNOWN_TOKEN.
   */
  tokenAddress?: string;

  /**
   * For fields carrying an `encryption` annotation, the raw encrypted value as
   * 0x-prefixed hex — the field's value as it appears in the signing request,
   * before decryption. Depending on the scheme this is the ciphertext itself or
   * a pointer to it.
   *
   * Set whether or not decryption succeeded. When it did not, `value` is the
   * descriptor's `fallbackLabel` (or a generic placeholder if it declares none)
   * and `warning.code` is DECRYPTION_FAILED; the ERC-7730 spec recommends
   * wallets also show this raw value — fully or partially — next to that
   * placeholder, so the user can tell that a real value is present but withheld.
   */
  rawEncryptedValue?: string;
}

/**
 * A named group of display fields, optionally carrying a warning.
 * A group with an `EMPTY_ARRAY` warning indicates that the corresponding
 * array in the transaction data was empty.
 */
export interface DisplayFieldGroup {
  label?: string;
  fields: DisplayField[];
  warning?: Warning;
}

/**
 * The complete display model produced by the library.
 *
 * According to ERC-7730, wallets have two display options:
 *   1. Show `intent` as an explanation what the contract call does, and
 *      `fields` as a list of labeled values representing the calldata parameters.
 *   2. Show `interpolatedIntent` as a short string presentation of intent and fields,
 *      which already has formatted field values embedded in it — in this case
 *      `fields` can be omitted or shown as supplementary detail.
 *
 * When interpolation fails or is not defined, wallets should fall back to Option 1.
 */
export interface DisplayModel {
  /**
   * The intent from the resolved descriptor, representing a short
   * description of the operation, e.g. "Approve token spending".
   * Two possible forms:
   *   - A simple human-readable string
   *   - A list of human-readable key-value pairs
   */
  intent?: string | Record<string, string>;

  /**
   * Ordered list of fields to show to the user,
   * formatted according to their field format specification.
   */
  fields?: (DisplayField | DisplayFieldGroup)[];

  /**
   * Full sentence with formatted field values interpolated in, e.g.
   * "Approve USDC spending up to 1,000 USDC for Uniswap V3".
   * Absent when the descriptor does not define an interpolatedIntent,
   * or when interpolation fails.
   */
  interpolatedIntent?: string;

  /**
   * Additional metadata directly from the resolved descriptor.
   * Wallets may choose to display these items to provide additional
   * context about the contract being interacted with.
   */
  metadata?: {
    owner?: string;
    contractName?: string;
    info?: { deploymentDate?: string; url?: string };
  };

  /**
   * Raw calldata fallback when no descriptor matched or the descriptor was faulty.
   * Only present for calldata formatting — not applicable to EIP-712 typed data.
   */
  rawCalldataFallback?: RawCalldataFallback;

  /**
   * Warnings providing additional context, e.g. why
   * interpolation failed.
   */
  warnings?: Warning[];
}

/**
 * Display model for an EIP-5792 batch of calls.
 *
 * The `callDisplays` array preserves the same order as the `calls`
 * array passed to {@link formatEip5792Batch}, so wallets can correlate
 * each display model with its source call by index.
 *
 * The batch-level `interpolatedIntent` concatenates all individual
 * `interpolatedIntent` strings with " and " (per ERC-7730).
 * It is absent when any call could not produce an `interpolatedIntent`,
 * in which case `warnings` will contain a `BATCH_INTERPOLATION_INCOMPLETE`
 * entry.
 */
export type BatchDisplayModel = Pick<
  DisplayModel,
  "interpolatedIntent" | "warnings"
> & {
  callDisplays: DisplayModel[];
};

/** Closure for formatting embedded calldata (nested function calls). */
export type FormatCalldata = (tx: Transaction) => Promise<DisplayModel>;

/** Result of resolving an address name (ENS or local). */
export interface AddressNameResult {
  name: string;
  /** Whether the resolved address type matches the expected type. */
  typeMatch: boolean;
}

/** Result of resolving a token address */
export interface TokenResult {
  name: string;
  symbol: string;
  decimals: number;
}

/** Result of resolving an NFT collection name. */
export interface NftCollectionNameResult {
  name: string;
}

/** Result of resolving a block timestamp. */
export interface BlockTimestampResult {
  /** Unix timestamp in seconds. */
  timestamp: number;
}

/** Result of resolving chain information by chain ID. */
export interface ChainInfoResult {
  /** Human-readable chain name, e.g. "Ethereum Mainnet". */
  name: string;
  /** Native currency metadata. */
  nativeCurrency: {
    name: string;
    symbol: string;
    decimals: number;
  };
}

/** Result of decrypting an encrypted field value. */
export interface DecryptedValueResult {
  /**
   * The decrypted plaintext, as 0x-prefixed hex of its big-endian ABI bytes —
   * never a `bigint`, `boolean`, or decimal string. The library re-interprets
   * these bytes according to the descriptor's declared `plaintextType`, so a
   * single encoding covers every scheme and every type.
   *
   * Must be valid, even-length hex.
   */
  value: string;
}

/** A read-only `eth_call` request. */
export interface EthCallRequest {
  /** Target contract address. */
  to: string;
  /** 0x-prefixed hex calldata. */
  data: string;
}

/**
 * Wallet-provided raw chain access. The semantic resolvers on
 * {@link ExternalDataProvider} let the wallet serve data from any source. The
 * chain client is different: the library selects the contract, encodes the
 * call, and decodes the result. The wallet only supplies the RPC connection.
 *
 * Currently only used to check the ERC-8176 revocation state of an
 * attestation on the EAS contract on Ethereum mainnet.
 */
export interface ChainClient {
  /**
   * Performs `eth_call` against `chainId` and returns the 0x-prefixed hex
   * return data. Throw on transport failures and reverts; the library
   * handles them. Return the data exactly as the node returns it — including
   * `0x` for empty return data — and never substitute a value on failure.
   */
  call: (chainId: number, request: EthCallRequest) => Promise<string>;
}

/** Wallet-provided async resolvers for external data needed by the formatter. */
export interface ExternalDataProvider {
  /**
   * Raw chain access for checks the library performs itself (see
   * {@link ChainClient}). Required when an {@link AttestationOptions} policy
   * is set: the ERC-8176 revocation check reads the EAS contract on Ethereum
   * mainnet.
   */
  chainClient?: ChainClient;

  /**
   * Resolution for addressName formats. The wallet should verify whether the
   * address matches any of the provided accepted types (e.g., "eoa", "contract", ...)
   * if able to. If none of the types match, set typeMatch to false so the library
   * can include a warning in the DisplayModel. When acceptedTypes is absent, the
   * descriptor has no type constraint and typeMatch: true can be returned safely.
   */
  resolveLocalName?: (
    address: string,
    acceptedTypes?: DescriptorAddressType[],
  ) => Promise<AddressNameResult | null>;
  /**
   * Resolution for addressName formats. The wallet should verify whether the
   * address matches any of the provided accepted types (e.g., "eoa", "contract", ...)
   * if able to. If none of the types match, set typeMatch to false so the library
   * can include a warning in the DisplayModel. When acceptedTypes is absent, the
   * descriptor has no type constraint and typeMatch: true can be returned safely.
   */
  resolveEnsName?: (
    address: string,
    acceptedTypes?: DescriptorAddressType[],
  ) => Promise<AddressNameResult | null>;

  /** Resolution for tokenAmount formats. */
  resolveToken?: (
    chainId: number,
    tokenAddress: string,
  ) => Promise<TokenResult | null>;

  /** Resolution for nftName formats. */
  resolveNftCollectionName?: (
    chainId: number,
    collectionAddress: string,
  ) => Promise<NftCollectionNameResult | null>;

  /** Resolution for date format with blockheight encoding. */
  resolveBlockTimestamp?: (
    chainId: number,
    blockHeight: bigint,
  ) => Promise<BlockTimestampResult | null>;

  /** Resolution for chainId and amount formats. */
  resolveChainInfo?: (chainId: number) => Promise<ChainInfoResult | null>;

  /**
   * Decryption for fields carrying an `encryption` annotation
   * ({@link DescriptorFieldEncryption}). Only needed by wallets opting in to
   * an encryption scheme — omit it and encrypted fields render their
   * `fallbackLabel`.
   *
   * The wallet decrypts and reports the plaintext bytes; the library interprets
   * them against the descriptor's declared `plaintextType`. That declared type
   * is deliberately not passed here — decryption yields bytes, and typing them
   * is the library's job, not the wallet's.
   *
   * Return `null` when the value cannot be decrypted — unsupported scheme,
   * declined by the user, or access not granted.
   */
  resolveDecryptedValue?: (
    chainId: number,
    /** 0x-prefixed hex of the raw encrypted field value. */
    encryptedValue: string,
    params: {
      /** Scheme from the descriptor. Dispatch on this. */
      scheme: DescriptorFieldEncryptionScheme;
      /**
       * The contract the encrypted value belongs to (the container's `@.to`).
       * Absent when an EIP-712 domain declares no `verifyingContract`.
       */
      contractAddress?: string;
    },
  ) => Promise<DecryptedValueResult | null>;
}

export interface FormatOptions {
  /**
   * Wallets should provide an object with async methods to resolve
   * external data like ENS names, token metadata, and NFT collection
   * names. The provided functions may use RPC calls or fetch data
   * from internal sources. This allows the library to remain
   * agnostic about how this data is fetched. If absent, the library
   * will fall back to raw formats for the corresponding fields.
   */
  externalDataProvider?: ExternalDataProvider;

  /**
   * Controls where descriptors are fetched from.
   * Defaults to the GitHub registry when omitted.
   *
   * Pass `{ type: "github", ... }` ({@link GitHubResolverOptions}) to fetch
   * from the registry, or `{ type: "custom", resolver }`
   * ({@link CustomResolverOptions}) to plug in any pre-built
   * {@link DescriptorResolver} — for instance the Node-only filesystem
   * resolver from `@ethereum-sourcify/clear-signing/filesystem`.
   */
  descriptorResolverOptions?: GitHubResolverOptions | CustomResolverOptions;

  // TODO: resolvedImplementationAddress for proxy contracts — may be replaced
  // with an ExternalDataProvider method.
  // resolvedImplementationAddress?: string;
}

/**
 * ERC-8176 attestation policy. Controls which auditors (EAS attesters) the
 * wallet trusts to have reviewed descriptors.
 *
 * The policy needs an {@link ExternalDataProvider.chainClient}: the library
 * reads the revocation state of each attestation from the EAS contract on
 * Ethereum mainnet.
 */
export interface AttestationOptions {
  /**
   * Addresses of the attesters (auditors) whose attestations the wallet
   * trusts. A descriptor is only accepted when at least one listed attester
   * has a valid attestation over it.
   */
  trustedAttesters: string[];
}

/** Token standards for descriptor generation. */
export type TokenStandard = "erc20" | "erc721";

/** Nested map: chain ID → token address → token standard. */
export interface TrustedTokens {
  [chainId: number]: { [tokenAddress: string]: TokenStandard };
}

export interface BaseResolverOptions {
  /**
   * ERC-8176 attestation policy. When set, a resolved registry descriptor is
   * only used when one of the listed trusted attesters has a valid
   * attestation over it; otherwise resolution fails with a
   * `NO_TRUSTED_ATTESTATION` warning. The revocation check requires an
   * {@link ExternalDataProvider.chainClient}.
   *
   * When omitted, descriptors are used without any attestation check. That
   * mode is intended for testing only — production wallets should always set
   * an attestation policy.
   *
   * Bundled trusted-token descriptors (see {@link BaseResolverOptions.trustedTokens})
   * are not subject to this policy.
   */
  attestations?: AttestationOptions;

  /**
   * Wallet-provided trusted token list. Used to generate descriptors for tokens
   * on the fly. Standard tokens usually don't have a descriptor in the registry.
   * Without this option, the library can't format calls to standard tokens.
   * Only wallet-trusted tokens should be included in this object.
   *
   * Both lowercase and checksummed token addresses are accepted.
   */
  trustedTokens?: TrustedTokens;
}

export type GitHubResolverOptions = BaseResolverOptions & {
  type: "github";
  /**
   * Pre-built registry index. Strongly recommended: fetch once at app
   * startup via `fetchPrebuiltRegistryIndex()` and reuse across calls.
   * If omitted, the library re-fetches the registry's prebuilt index
   * files on every `format()` / `formatTypedData()` call.
   */
  index?: RegistryIndex;
  githubSource?: Partial<GitHubSource>;
};

/**
 * Plugs a user-built {@link DescriptorResolver} into the format pipeline.
 * Use this for any descriptor source other than the built-in GitHub
 * registry — filesystem (see `@ethereum-sourcify/clear-signing/filesystem`),
 * in-memory map, custom HTTP endpoint, etc.
 */
export type CustomResolverOptions = BaseResolverOptions & {
  type: "custom";
  resolver: DescriptorResolver;
};

/**
 * A pre-built descriptor resolver: a registry index plus a closure that
 * fetches and parses a single descriptor file by its index-relative path.
 *
 * Wrap an instance in {@link CustomResolverOptions} and pass it to
 * {@link FormatOptions.descriptorResolverOptions} to override the default
 * GitHub-backed resolution with any descriptor source. The library resolves
 * `includes` chains and merges descriptors using only `index` and
 * `fetchDescriptor`, so any source that satisfies this shape will work.
 */
export interface DescriptorResolver {
  index: RegistryIndex;
  fetchDescriptor: (path: string) => Promise<Descriptor>;

  /**
   * Fetches the ERC-8176 offchain attestation issued by `attester` for the
   * descriptor at `descriptorPath` (the same path `fetchDescriptor` receives).
   * `attester` is passed as an EIP-55 checksummed address. Return `null` when
   * the attester published no attestation for the descriptor; throw on I/O
   * failures.
   *
   * Required when {@link AttestationOptions} policy is set.
   */
  fetchAttestation?: (
    descriptorPath: string,
    attester: string,
  ) => Promise<OffchainAttestation | null>;
}

export interface RegistryIndex {
  /**
   * Maps CAIP-10 identifiers ("eip155:{chainId}:{address}") to the descriptor
   * file's path.
   *
   * The path is resolved relative to the resolver root — `descriptorDirectory`
   * for the filesystem resolver, the repository root for GitHub resolvers. It MUST
   * be the descriptor's full relative path, not just a basename: an
   * `includes` declared inside the descriptor (e.g. `"../../ercs/foo.json"`)
   * is resolved against the directory of *this* path, and any `..` segments
   * that overshoot the root are dropped. So an index keyed by bare basename
   * silently truncates `..` traversals — store `"registry/foo/main.json"`,
   * not `"main.json"`, if the include chain reaches a sibling directory.
   */
  calldataIndex: { [caip10Id: string]: string };

  /**
   * Maps CAIP-10 identifiers to a per-primary-type list of descriptor entries.
   *
   * A single (chainId, verifyingContract, primaryType) triple may resolve to
   * multiple descriptor files (e.g. Uniswap Permit2's `PermitWitnessTransferFrom`
   * wraps different order shapes). Entries are disambiguated by matching the
   * EIP-712 `encodeType` hash of the incoming typed data against
   * `encodeTypeHashes`.
   *
   * The `path` on each entry follows the same relative-path contract as
   * `calldataIndex`.
   *
   * See https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/index.eip712.json
   * as an example of the shape of this index in practice.
   */
  typedDataIndex: {
    [caip10Id: string]: { [primaryType: string]: TypedDataIndexEntry[] };
  };
}

/**
 * One candidate descriptor for an EIP-712 (chainId, verifyingContract, primaryType)
 * triple. `encodeTypeHashes` lists the keccak256 hashes of the EIP-712
 * `encodeType` strings that this descriptor supports.
 */
export interface TypedDataIndexEntry {
  path: string;
  encodeTypeHashes: string[];
}

export interface GitHubSource {
  repo: string;
  ref: string;
}

/** The signed `Attest` message of an EAS offchain attestation. */
export interface OffchainAttestationMessage {
  version?: number;
  /** EAS schema UID (bytes32 hex). */
  schema?: string;
  recipient?: string;
  /** Unix seconds; EAS serializes uint64 values as decimal strings. */
  time?: string | number;
  /** Unix seconds, or 0 for a non-expiring attestation. */
  expirationTime?: string | number;
  revocable?: boolean;
  refUID?: string;
  /** Schema-encoded payload — for ERC-8176 the bytes32 descriptor hash. */
  data?: string;
  salt?: string;
}

/** An Ethereum secp256k1 ECDSA signature: `r`, `s`, and the recovery id `v`. */
export interface EcdsaSignature {
  v?: number;
  r?: string;
  s?: string;
}

/** The `sig` envelope of an EAS offchain attestation. */
export interface OffchainAttestationSig {
  version?: number;
  /** Deterministic offchain attestation UID (bytes32 hex). */
  uid?: string;
  domain?: TypedDataDomain;
  primaryType?: string;
  types?: Record<string, TypeMember[]>;
  message?: OffchainAttestationMessage;
  signature?: EcdsaSignature;
}

/**
 * An EAS offchain attestation, as stored in the registry's `sigs/`
 * directories per ERC-8176.
 */
export interface OffchainAttestation {
  sig?: OffchainAttestationSig;
  signer?: string;
}

export type DescriptorFieldFormatType =
  | "raw"
  | "amount"
  | "tokenAmount"
  | "nftName"
  | "date"
  | "duration"
  | "unit"
  | "enum"
  | "chainId"
  | "addressName"
  | "tokenTicker"
  | "calldata"
  | "interoperableAddressName";

export type DescriptorAddressType =
  | "wallet"
  | "eoa"
  | "contract"
  | "token"
  | "collection";

export type DescriptorAddressSource = "local" | "ens";

export type DescriptorFieldEncryptionScheme = "fhevm";

export interface DescriptorFieldEncryption {
  scheme?: DescriptorFieldEncryptionScheme;
  plaintextType?: string;
  fallbackLabel?: string;
}

export interface DescriptorFieldFormatParams {
  tokenPath?: string;
  token?: string;
  nativeCurrencyAddress?: string | string[];
  threshold?: string | number;
  message?: string;
  chainIdPath?: string;
  chainId?: number;
  encoding?: "timestamp" | "blockheight";
  base?: string;
  decimals?: number;
  prefix?: boolean;
  $ref?: string;
  collectionPath?: string;
  collection?: string;
  calleePath?: string;
  callee?: string;
  selectorPath?: string;
  selector?: string;
  amountPath?: string;
  amount?: string;
  spenderPath?: string;
  spender?: string;
  types?: DescriptorAddressType[];
  sources?: DescriptorAddressSource[];
  senderAddress?: string | string[];
}

export interface DescriptorFieldFormat {
  $id?: string;
  path?: string;
  value?: unknown;
  label?: string;
  format?: DescriptorFieldFormatType;
  params?: DescriptorFieldFormatParams;
  visible?:
    | "never"
    | "always"
    | "optional"
    | { ifNotIn?: Array<string | number | boolean | null> }
    | { mustMatch?: Array<string | number | boolean | null> };
  separator?: string;
  encryption?: DescriptorFieldEncryption;
  $ref?: string;
}

export interface DescriptorFieldGroup {
  path?: string;
  label?: string;
  fields?: Array<DescriptorFieldFormat | DescriptorFieldGroup>;
  iteration?: "sequential" | "bundled";
}

export interface DescriptorFormatSpec {
  $id?: string;
  intent?: string | Record<string, string>;
  interpolatedIntent?: string;
  fields?: Array<DescriptorFieldFormat | DescriptorFieldGroup>;
}

export interface DescriptorDisplay {
  definitions?: Record<string, DescriptorFieldFormat>;
  formats?: Record<string, DescriptorFormatSpec>;
}

export interface DescriptorDeployment {
  chainId?: number;
  address?: string;
}

export interface DescriptorContractFactory {
  deployEvent?: string;
  deployments?: DescriptorDeployment[];
}

export interface DescriptorContractContext {
  deployments?: DescriptorDeployment[];
  factory?: DescriptorContractFactory;
}

export interface DescriptorEip712Context {
  $id?: string;
  domain?: Record<string, unknown>;
  deployments?: DescriptorDeployment[];
  domainSeparator?: string;
}

export interface DescriptorContext {
  $id?: string;
  contract?: DescriptorContractContext;
  eip712?: DescriptorEip712Context;
}

export interface DescriptorMetadataInfo {
  deploymentDate?: string;
  url?: string;
}

export interface DescriptorMetadataToken {
  name?: string;
  ticker?: string;
  decimals?: number;
}

export interface DescriptorMetadata {
  owner?: string;
  contractName?: string;
  info?: DescriptorMetadataInfo;
  token?: DescriptorMetadataToken;
  constants?: Record<string, string | number | boolean>;
  maps?: Record<string, unknown>;
  enums?: Record<string, Record<string, string>>;
}

export interface Descriptor {
  $schema?: string;
  includes?: string;
  context?: DescriptorContext;
  metadata?: DescriptorMetadata;
  display?: DescriptorDisplay;
  // Required for the merge algorithm in resolver.ts to iterate over arbitrary keys.
  [key: string]: unknown;
}