@midnight-ntwrk/midnight-js-types 4.1.1 → 5.0.0-beta.1

package/dist/index.d.mts

@@ -1,12 +1,13 @@
 import { ContractExecutable } from '@midnight-ntwrk/midnight-js-protocol/compact-js/effect';
+import { SigningKey, ContractAddress as ContractAddress$2, ContractState } from '@midnight-ntwrk/midnight-js-protocol/compact-runtime';
 import { ContractAddress as ContractAddress$1 } from '@midnight-ntwrk/midnight-js-protocol/platform-js';
 import { Option, Exit, ConfigError } from 'effect';
 import { ManagedRuntime } from 'effect/ManagedRuntime';
-import { Contract } from '@midnight-ntwrk/midnight-js-protocol/compact-js';
+import { Contract, ContractKeyLocation } from '@midnight-ntwrk/midnight-js-protocol/compact-js';
+export { ContractKeyLocation, encodeContractKeyLocation, hashVerifierKey, parseContractKeyLocation } from '@midnight-ntwrk/midnight-js-protocol/compact-js';
 import { Transaction, SignatureEnabled, Proof, Binding, TransactionId, TransactionHash, ContractAddress, IntentHash, RawTokenType, FinalizedTransaction, UnprovenTransaction, PreBinding, ProvingProvider, CostModel, ZswapChainState, LedgerParameters, CoinPublicKey, EncPublicKey } from '@midnight-ntwrk/midnight-js-protocol/ledger';
 export { Transaction } from '@midnight-ntwrk/midnight-js-protocol/ledger';
 import { LogFn } from 'pino';
-import { ContractAddress as ContractAddress$2, SigningKey, ContractState } from '@midnight-ntwrk/midnight-js-protocol/compact-runtime';
 import { Observable } from 'rxjs';
 
 type AnyProvableCircuitId = Contract.ProvableCircuitId<Contract.Any>;
@@ -313,7 +314,7 @@ type ContractExecutableRuntimeOptions = {
     /** The current user's ZSwap public key. */
     readonly coinPublicKey: string;
     /** The signing key to add as the to-be-deployed contract's maintenance authority. */
-    readonly signingKey?: string;
+    readonly signingKey?: SigningKey;
 };
 /**
  * Constructs an Effect managed runtime configured to execute contract executables.
@@ -896,6 +897,19 @@ type BlockHashConfig = {
      */
     readonly blockHash: string;
 };
+/**
+ * Minimal identifying information for a block.
+ */
+type BlockInfo = {
+    /**
+     * The hex-encoded block hash.
+     */
+    readonly hash: string;
+    /**
+     * The block height.
+     */
+    readonly height: number;
+};
 /**
  * The configuration for a contract state observable. The corresponding observables may begin at different
  * places (e.g. after a specific transaction identifier / block height) depending on the configuration, but
@@ -909,11 +923,191 @@ type ContractStateObservableConfig = ((TxIdConfig | BlockHashConfig | BlockHeigh
      */
     readonly inclusive?: boolean;
 }) | Latest | All;
+/**
+ * The eleven contract event variants surfaced by the indexer (MIP-0002 public
+ * contract log emission). The variant *set* is identical to compact-js's
+ * `LogEventType`; only the string casing differs (PascalCase here, kebab-case
+ * in compact-js, SCREAMING_SNAKE on the indexer wire). Adding a variant is a
+ * breaking change — the mapping, filter translation, and exhaustiveness guards
+ * all key off this union.
+ */
+type ContractEventType = 'ShieldedSpend' | 'ShieldedReceive' | 'ShieldedMint' | 'ShieldedBurn' | 'UnshieldedSpend' | 'UnshieldedReceive' | 'UnshieldedMint' | 'UnshieldedBurn' | 'Paused' | 'Unpaused' | 'Misc';
+/**
+ * A `sender` / `recipient` on an unshielded event. The indexer returns a tagged
+ * union (`Either<ZswapCoinPublicKey, ContractAddress>`); this preserves the
+ * discriminator so consumers can tell a user address from a contract address
+ * rather than receiving a bare, ambiguous string.
+ */
+interface ContractEventAddress {
+    /** Which kind of address `value` holds. */
+    readonly kind: 'user' | 'contract';
+    /** The hex-encoded address. */
+    readonly value: string;
+}
+/**
+ * Fields common to every {@link ContractEvent} variant, regardless of type.
+ */
+interface ContractEventBase {
+    /**
+     * Monotonic indexer cursor for this event. Inclusive resumption point — to
+     * resume *after* this event, pass `{ fromId: id + 1 }`.
+     */
+    readonly id: number;
+    /**
+     * Highest event id the indexer currently knows (the chain tip for events).
+     * Compare against {@link id} to detect catch-up / whether more events exist.
+     */
+    readonly maxId: number;
+    /**
+     * Payload schema version — selects the (future) per-event payload decoder.
+     * Iteration-1 events are `version: 1`.
+     */
+    readonly version: number;
+    /** Address of the contract that emitted the event. */
+    readonly contractAddress: ContractAddress;
+    /**
+     * Indexer-internal `BIGSERIAL` row id of the emitting transaction — **not**
+     * the chain transaction hash. To fetch the chain transaction, issue a
+     * separate query. Note the asymmetry with {@link ContractEventFilterBase.transactionHash},
+     * which narrows by chain hash.
+     */
+    readonly transactionId: number;
+    /**
+     * Opaque hex `VersionedLogItem` bytes, carried verbatim. Never decoded or
+     * validated by this provider — the forward bridge to a future compact-js
+     * payload decoder.
+     */
+    readonly raw: string;
+}
+/**
+ * A decoded contract event. Discriminated union keyed on `eventType`; narrow on
+ * it to access the variant-specific payload fields.
+ *
+ * `amount` is always a `string` (encodes up to a 16-byte integer) — never round
+ * it through `Number()`. Absent nullable fields are normalized to `undefined`
+ * (never `null`).
+ */
+type ContractEvent = (ContractEventBase & {
+    readonly eventType: 'ShieldedSpend';
+    readonly nullifier: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'ShieldedReceive';
+    readonly commitment: string;
+    readonly ciphertext?: string;
+    readonly receivingContractAddress?: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'ShieldedMint';
+    readonly commitment: string;
+    readonly domainSep: string;
+    readonly amount?: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'ShieldedBurn';
+    readonly nullifier: string;
+    readonly amount?: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'UnshieldedSpend';
+    readonly sender: ContractEventAddress;
+    readonly domainSep: string;
+    readonly tokenType: string;
+    readonly amount: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'UnshieldedReceive';
+    readonly recipient: ContractEventAddress;
+    readonly domainSep: string;
+    readonly tokenType: string;
+    readonly amount: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'UnshieldedMint';
+    readonly domainSep: string;
+    readonly tokenType: string;
+    readonly amount: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'UnshieldedBurn';
+    readonly sender: ContractEventAddress;
+    readonly tokenType: string;
+    readonly amount: string;
+}) | (ContractEventBase & {
+    readonly eventType: 'Paused';
+}) | (ContractEventBase & {
+    readonly eventType: 'Unpaused';
+}) | (ContractEventBase & {
+    readonly eventType: 'Misc';
+    readonly name: string;
+    readonly payload: string;
+});
+/**
+ * A single prefix filter on an indexed field of a standard event. `prefix` is
+ * hex-encoded; the empty string matches all values.
+ */
+interface ContractEventFieldPrefix {
+    readonly fieldName: string;
+    readonly prefix: string;
+}
+/**
+ * Filter fields shared by the query and the subscription.
+ */
+interface ContractEventFilterBase {
+    /** Required: the contract whose events to return. */
+    readonly contractAddress: ContractAddress;
+    /**
+     * Optional subset of event types. Omit to mean "all types". An empty array
+     * is rejected (it would silently match nothing).
+     */
+    readonly types?: ContractEventType[];
+    /**
+     * Optional prefix filters on indexed fields. Accepted only when every
+     * filtered type is a standard (non-`Misc`) variant — see method docs.
+     */
+    readonly fieldPrefixes?: ContractEventFieldPrefix[];
+    /** Optional: narrow to events emitted from the transaction with this chain hash. */
+    readonly transactionHash?: string;
+}
+/**
+ * Filter for {@link PublicDataProvider.queryContractEvents}. `fromBlock` /
+ * `toBlock` are inclusive block-height bounds for a finite, point-in-time read.
+ */
+interface ContractEventQueryFilter extends ContractEventFilterBase {
+    readonly fromBlock?: number;
+    readonly toBlock?: number;
+}
+/**
+ * Filter for {@link PublicDataProvider.contractEventsObservable}. The stream
+ * start is supplied separately via {@link ContractEventCursor}; `toBlock`
+ * terminates the stream once the chain reaches that height.
+ */
+interface ContractEventSubscriptionFilter extends ContractEventFilterBase {
+    readonly toBlock?: number;
+}
+/**
+ * Where a subscription begins. Exactly one addressing mode per call — two
+ * competing start points are unrepresentable by construction.
+ */
+type ContractEventCursor = {
+    readonly fromId: number;
+} | {
+    readonly fromBlock: number;
+};
+/**
+ * Pagination window for {@link PublicDataProvider.queryContractEvents}.
+ * `offset` is only stable within a window with a fixed upper bound — pin
+ * `toBlock` for multi-page reads.
+ */
+interface ContractEventsPage {
+    readonly limit?: number;
+    readonly offset?: number;
+}
 /**
  * Interface for a public data service. This service retrieves public data from the blockchain.
  * TODO: Add timeouts or retry limits to 'watchFor' queries.
  */
 interface PublicDataProvider {
+    /**
+     * Retrieves a block. If no block hash or block height is provided, the latest block is returned.
+     * Immediately returns null if no matching block is found.
+     * @param config The configuration of the query identifying the block of interest.
+     *               If `undefined` returns the latest block.
+     */
+    queryBlock(config?: BlockHeightConfig | BlockHashConfig): Promise<BlockInfo | null>;
     /**
      * Retrieves the on-chain state of a contract. If no block hash or block height are provided, the
      * contract state at the address in the latest block is returned.
@@ -1010,6 +1204,56 @@ interface PublicDataProvider {
      * @return {Observable<UnshieldedBalances>} An observable that emits the unshielded balances for the provided address.
      */
     unshieldedBalancesObservable(address: ContractAddress, config: ContractStateObservableConfig): Observable<UnshieldedBalances>;
+    /**
+     * Queries contract events for a contract address — a finite, paginated,
+     * point-in-time read.
+     *
+     * Results are returned in ascending `id` order. The result is a plain array
+     * with no total count: detect the end via `result.length < limit`, and read
+     * `maxId` on the last item to see how far the tip is.
+     *
+     * When `page.limit` is omitted an implementation-defined default page size is
+     * applied (never an undocumented server default). `offset` is only stable
+     * within a window with a fixed upper bound — pin `filter.toBlock` for
+     * multi-page reads, or prefer the `getAllContractEvents` helper / the
+     * subscription for tailing.
+     *
+     * Fails fast (synchronously, before any network call) on an invalid
+     * `contractAddress`, an empty `types` array, `fieldPrefixes` combined with
+     * `Misc` (or with `types` omitted), or an unknown `fieldName`. Network /
+     * GraphQL errors reject the promise — an empty array always means "no
+     * matching events", never a swallowed error.
+     *
+     * @param filter The events to return; `contractAddress` is required.
+     * @param page Optional pagination window.
+     */
+    queryContractEvents(filter: ContractEventQueryFilter, page?: ContractEventsPage): Promise<ContractEvent[]>;
+    /**
+     * Streams contract events for a contract address — replay from a cursor, then
+     * live, in one continuous stream.
+     *
+     * The start is supplied via `opts.startAt`: `{ fromId }` resumes inclusively
+     * from a known event id, `{ fromBlock }` starts from a block height. Omitting
+     * `startAt` streams from the start of history. The indexer replays historical
+     * events from that point in monotonic `id` order, then continues live — there
+     * is no separate backfill query and no client-side dedup.
+     *
+     * `{ fromId }` is **inclusive**; to resume *after* the last seen event pass
+     * `{ fromId: lastSeenId + 1 }`.
+     *
+     * `filter.toBlock` completes the stream once the chain reaches that height;
+     * without it the stream runs until unsubscribed or the provider is disposed.
+     * Delivery is **at-least-once** across transport reconnects (the provider
+     * does not advance the cursor) — persisting consumers should dedup by `id`.
+     * Transport failures surface as an observable `error`, never a silent
+     * completion.
+     *
+     * @param filter The events to stream; `contractAddress` is required.
+     * @param opts Optional stream start.
+     */
+    contractEventsObservable(filter: ContractEventSubscriptionFilter, opts?: {
+        startAt?: ContractEventCursor;
+    }): Observable<ContractEvent>;
 }
 
 /**
@@ -1065,5 +1309,64 @@ interface MidnightProviders<PCK extends AnyProvableCircuitId = AnyProvableCircui
     readonly loggerProvider?: LoggerProvider;
 }
 
-export { ExportDecryptionError, FailEntirely, FailFallible, ImportConflictError, InvalidExportFormatError, InvalidProtocolSchemeError, LogLevel, MAX_EXPORT_SIGNING_KEYS, MAX_EXPORT_STATES, PrivateStateExportError, PrivateStateImportError, SegmentFail, SegmentSuccess, SigningKeyExportError, SucceedEntirely, ZKConfigProvider, asContractAddress, asEffectOption, createProofProvider, createProverKey, createVerifierKey, createZKIR, exitResultOrError, makeContractExecutableRuntime, zkConfigToProvingKeyMaterial };
-export type { All, AnyPrivateState, AnyProvableCircuitId, BlockHash, BlockHashConfig, BlockHeightConfig, ContractExecutableRuntimeOptions, ContractStateObservableConfig, ExportPrivateStatesOptions, ExportSigningKeysOptions, Fees, FinalizedTxData, ImportPrivateStatesOptions, ImportPrivateStatesResult, ImportSigningKeysOptions, ImportSigningKeysResult, KeyMaterialProvider, Latest, LoggerProvider, MidnightProvider, MidnightProviders, PrivateStateExport, PrivateStateId, PrivateStateImportErrorCause, PrivateStateProvider, ProofProvider, ProveTxConfig, ProverKey, PublicDataProvider, SegmentStatus, SigningKeyExport, TxIdConfig, TxStatus, UnboundTransaction, UnshieldedBalance, UnshieldedBalances, UnshieldedUtxo, UnshieldedUtxos, VerifierKey, WalletProvider, ZKConfig, ZKIR };
+/**
+ * Thrown when a contract key location parses but no artifact source contains a bundle whose
+ * verifier key matches the deployed one — i.e. the local artifacts have drifted from (or were
+ * never compiled for) the deployed contract.
+ */
+declare class ZKArtifactNotFoundError extends Error {
+    readonly keyLocation: ContractKeyLocation;
+    constructor(keyLocation: ContractKeyLocation);
+}
+/**
+ * Resolves canonical contract key locations to ZK artifacts across a *set* of compiled-contract
+ * artifact sources.
+ *
+ * A cross-contract call transaction carries one proof per contract in the call tree, so proving
+ * requires artifacts for several compiled contracts, keyed by `(contractAddress, circuitId)`. No
+ * registration of addresses is required: the binding is *derived* by joining on the verifier key.
+ * Each location embeds the SHA-256 of the call's deployed verifier key (known at transaction
+ * assembly from the contract's resolved on-chain state), and resolution selects the source whose
+ * local verifier key for the circuit matches. The join is sound because it is the predicate the
+ * chain itself enforces — a proof must verify against the deployed key — and it makes the
+ * resolution immune to redeploys, multiple deployments of one contract, and circuit-name
+ * collisions across contracts.
+ *
+ * The sources are the per-contract {@link ZKConfigProvider}s the application already constructs;
+ * resolutions are memoized per location.
+ */
+declare class ZKConfigRegistry {
+    private readonly sources;
+    private readonly resolved;
+    /**
+     * @param sources The compiled-contract artifact sources to resolve against — one per compiled
+     * contract the application can call (its own contracts and any cross-contract call targets).
+     */
+    constructor(sources: Iterable<ZKConfigProvider<string>>);
+    /**
+     * Resolves the ZK artifacts for a structured contract key.
+     *
+     * @param location The contract address, circuit, and deployed verifier key hash to resolve.
+     * @throws ZKArtifactNotFoundError If no source's verifier key for the circuit matches.
+     */
+    get(location: ContractKeyLocation): Promise<ZKConfig<string>>;
+    /**
+     * Resolves the ZK artifacts for a key-location string from a proof preimage.
+     *
+     * @param keyLocation The key-location string.
+     * @returns The matched artifacts, or `undefined` if `keyLocation` is not a contract key
+     * location (for example, a `midnight/` protocol builtin, which provers resolve elsewhere).
+     * @throws ZKArtifactNotFoundError If `keyLocation` is a contract key location but no source's
+     * verifier key for the circuit matches the embedded hash.
+     */
+    resolveKeyLocation(keyLocation: string): Promise<ZKConfig<string> | undefined>;
+    /**
+     * Adapts this registry to the DApp connector's {@link KeyMaterialProvider}, allowing a wallet
+     * to resolve the key locations of a transaction assembled by this application.
+     */
+    asKeyMaterialProvider(): KeyMaterialProvider;
+    private resolve;
+}
+
+export { ExportDecryptionError, FailEntirely, FailFallible, ImportConflictError, InvalidExportFormatError, InvalidProtocolSchemeError, LogLevel, MAX_EXPORT_SIGNING_KEYS, MAX_EXPORT_STATES, PrivateStateExportError, PrivateStateImportError, SegmentFail, SegmentSuccess, SigningKeyExportError, SucceedEntirely, ZKArtifactNotFoundError, ZKConfigProvider, ZKConfigRegistry, asContractAddress, asEffectOption, createProofProvider, createProverKey, createVerifierKey, createZKIR, exitResultOrError, makeContractExecutableRuntime, zkConfigToProvingKeyMaterial };
+export type { All, AnyPrivateState, AnyProvableCircuitId, BlockHash, BlockHashConfig, BlockHeightConfig, BlockInfo, ContractEvent, ContractEventAddress, ContractEventBase, ContractEventCursor, ContractEventFieldPrefix, ContractEventFilterBase, ContractEventQueryFilter, ContractEventSubscriptionFilter, ContractEventType, ContractEventsPage, ContractExecutableRuntimeOptions, ContractStateObservableConfig, ExportPrivateStatesOptions, ExportSigningKeysOptions, Fees, FinalizedTxData, ImportPrivateStatesOptions, ImportPrivateStatesResult, ImportSigningKeysOptions, ImportSigningKeysResult, KeyMaterialProvider, Latest, LoggerProvider, MidnightProvider, MidnightProviders, PrivateStateExport, PrivateStateId, PrivateStateImportErrorCause, PrivateStateProvider, ProofProvider, ProveTxConfig, ProverKey, PublicDataProvider, SegmentStatus, SigningKeyExport, TxIdConfig, TxStatus, UnboundTransaction, UnshieldedBalance, UnshieldedBalances, UnshieldedUtxo, UnshieldedUtxos, VerifierKey, WalletProvider, ZKConfig, ZKIR };