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

package/dist/public-data-provider.d.ts

@@ -45,6 +45,19 @@ export type BlockHashConfig = {
      */
     readonly blockHash: string;
 };
+/**
+ * Minimal identifying information for a block.
+ */
+export 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
@@ -58,11 +71,191 @@ export type ContractStateObservableConfig = ((TxIdConfig | BlockHashConfig | Blo
      */
     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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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`).
+ */
+export 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.
+ */
+export interface ContractEventFieldPrefix {
+    readonly fieldName: string;
+    readonly prefix: string;
+}
+/**
+ * Filter fields shared by the query and the subscription.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
  */
 export 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.
@@ -159,5 +352,55 @@ export 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>;
 }
 //# sourceMappingURL=public-data-provider.d.ts.map

package/dist/public-data-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-data-provider.d.ts","sourceRoot":"","sources":["../src/public-data-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"public-data-provider.d.ts","sourceRoot":"","sources":["../src/public-data-provider.ts"],"names":[],"mappings":"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"}

package/dist/zk-config-registry.d.ts

@@ -0,0 +1,62 @@
+import type { ZKConfig } from './midnight-types';
+import type { KeyMaterialProvider, ZKConfigProvider } from './zk-config-provider';
+import { type ContractKeyLocation } from './zk-key-location';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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;
+}
+//# sourceMappingURL=zk-config-registry.d.ts.map

package/dist/zk-config-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zk-config-registry.d.ts","sourceRoot":"","sources":["../src/zk-config-registry.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,KAAK,mBAAmB,EAAwE,MAAM,mBAAmB,CAAC;AAEnI;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,WAAW,EAAE,mBAAmB;gBAAhC,WAAW,EAAE,mBAAmB;CAQtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE;;;OAGG;gBACS,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAIvD;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAI7D;;;;;;;;OAQG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAQpF;;;OAGG;IACH,qBAAqB,IAAI,mBAAmB;YAe9B,OAAO;CAsBtB"}

package/dist/zk-key-location.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The canonical key-location grammar for contract calls.
+ *
+ * The grammar is defined once, upstream, in `@midnight-ntwrk/compact-js` (the
+ * `ContractKeyLocation` module) so that every transaction assembler and prover shares a single
+ * definition; this module re-exports it. See the upstream module for the full specification:
+ * each contract call's proof preimage carries the canonical, self-describing location
+ * `contract:<address-hex>/<circuitId>?vk=<sha-256 of the deployed verifier key>`, which provers
+ * resolve by verifier-key content rather than by circuit name (see `ZKConfigRegistry`).
+ */
+export { type ContractKeyLocation, encodeContractKeyLocation, hashVerifierKey, parseContractKeyLocation } from '@midnight-ntwrk/midnight-js-protocol/compact-js';
+//# sourceMappingURL=zk-key-location.d.ts.map

package/dist/zk-key-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zk-key-location.d.ts","sourceRoot":"","sources":["../src/zk-key-location.ts"],"names":[],"mappings":"AAeA;;;;;;;;;GASG;AACH,OAAO,EACL,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,eAAe,EACf,wBAAwB,EACzB,MAAM,iDAAiD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/midnight-js-types",
-  "version": "4.1.1",
+  "version": "5.0.0-beta.1",
   "description": "Shared data types and interfaces for MidnightJS modules",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -29,7 +29,7 @@
     "dist/"
   ],
   "dependencies": {
-    "@midnight-ntwrk/midnight-js-protocol": "4.1.1",
+    "@midnight-ntwrk/midnight-js-protocol": "5.0.0-beta.1",
     "effect": "^3.20.0",
     "pino": "^10.3.1",
     "rxjs": "^7.8.2"