@effectstream/sm 0.100.12 → 0.100.14

package/primitives/src/cardano-transfer/transfer-primitive.ts

@@ -0,0 +1,150 @@
+/**
+ * Cardano Transfer Primitive
+ *
+ * Captures ADA and native asset transfers from Dolos UTxORPC block data.
+ *
+ * Data source: Dolos streams raw Cardano blocks via gRPC. Each transaction contains
+ * `outputs` (destination UTxOs with address, lovelace coin, and native assets) and
+ * `witnesses.vkeywitness` (verification key witnesses proving input authorization).
+ *
+ * Extraction: for each matched transaction, `getPayload()` maps `tx.outputs` into
+ * structured objects with `{index, address, coin, assets[]}`. Coin values are extracted
+ * from the protobuf BigInt (either `int` for small values or `bigUInt` for large).
+ * Input credentials are extracted from `tx.witnesses.vkeywitness[].vkey` — these are
+ * the public key hashes that signed the transaction, identifying who authorized the spend.
+ * Transaction metadata is extracted from `tx.auxiliary.metadata`.
+ *
+ * Predicate: user-provided (typically `has_address` to watch specific addresses).
+ */
+
+import type { StaticDecode } from "@sinclair/typebox";
+import {
+  type CommandTuple,
+  generateRawStmInput,
+} from "@effectstream/concise";
+import type {
+  ConfigSyncProtocolType,
+  FlattenSyncProtocolIOFor,
+  ProtocolPrimitiveMap,
+  UtxorpcTxPredicate,
+} from "@effectstream/config";
+import type { StateUpdateStream } from "@effectstream/coroutine";
+import { type JsonObject, Primitive } from "@effectstream/sm";
+import {
+  type AddressAndType,
+  AddressType,
+  type EffectstreamBlockNumber,
+  uint8ArrayToHexString,
+} from "@effectstream/utils";
+import { transferGrammar } from "./transfer-grammar.ts";
+import { PrimitiveTypeCardanoTransfer } from "../builtin.ts";
+import {
+  addressToHex,
+  assetQuantityToString,
+  metadataToJson,
+} from "../cardano-utils/cardano-helpers.ts";
+
+export class CardanoTransferPrimitive extends Primitive<
+  ConfigSyncProtocolType.CARDANO_UTXORPC_PARALLEL,
+  typeof transferGrammar
+> {
+  readonly internalTypeName = PrimitiveTypeCardanoTransfer;
+  readonly predicate: UtxorpcTxPredicate;
+  override grammar = transferGrammar;
+
+  constructor(config: {
+    instanceName: string;
+    startBlockHeight: number;
+    stateMachinePrefix: string | undefined;
+    predicate: UtxorpcTxPredicate;
+  }) {
+    super(config);
+    this.predicate = config.predicate;
+  }
+
+  override getConfig(): ProtocolPrimitiveMap[ConfigSyncProtocolType.CARDANO_UTXORPC_PARALLEL] {
+    return {
+      name: this.instanceName,
+      type: this.internalTypeName,
+      startBlockHeight: this.startBlockHeight,
+      scheduledPrefix: this.stateMachinePrefix,
+      predicate: this.predicate,
+    } as const;
+  }
+
+  override *getPayload(
+    _: EffectstreamBlockNumber,
+    primitiveTransactionData: FlattenSyncProtocolIOFor<ConfigSyncProtocolType.CARDANO_UTXORPC_PARALLEL>,
+  ): StateUpdateStream<{
+    isBatched: boolean;
+    data: {
+      fromAddressAndType: AddressAndType;
+      stateMachinePayload: StaticDecode<CommandTuple<string, typeof transferGrammar>> | null;
+      accountingPayload: JsonObject;
+    }[];
+  }> {
+    const tx = primitiveTransactionData.output.payload.tx;
+
+    const txId = uint8ArrayToHexString(tx.hash);
+
+    const outputs = tx.outputs.map((out, index) => {
+      const address = addressToHex(out.address);
+      const coin = out.coin?.bigInt.case === "int"
+        ? String(out.coin.bigInt.value)
+        : out.coin?.bigInt.case === "bigUInt"
+          ? uint8ArrayToHexString(out.coin.bigInt.value)
+          : "0";
+
+      const assets: { policyId: string; assetName: string; amount: string }[] = [];
+      for (const ma of out.assets) {
+        const policyId = uint8ArrayToHexString(ma.policyId);
+        for (const asset of ma.assets) {
+          assets.push({
+            policyId,
+            assetName: uint8ArrayToHexString(asset.name),
+            amount: assetQuantityToString(asset),
+          });
+        }
+      }
+
+      return { index, address, coin, assets };
+    });
+
+    const inputCredentials: string[] = [];
+    if (tx.witnesses) {
+      for (const w of tx.witnesses.vkeywitness) {
+        const hash = uint8ArrayToHexString(w.vkey);
+        if (!inputCredentials.includes(hash)) inputCredentials.push(hash);
+      }
+    }
+
+    const metadata = metadataToJson(tx.auxiliary?.metadata ?? []);
+
+    const accountingPayload = {
+      txId,
+      metadata: metadata ? JSON.stringify(metadata) : null,
+      inputCredentials,
+      outputs,
+    };
+
+    const stateMachinePayload: any = this.stateMachinePrefix
+      ? generateRawStmInput(this.grammar, this.stateMachinePrefix, {
+          txId,
+          metadata: metadata ? JSON.stringify(metadata) : "",
+          inputCredentials: JSON.stringify(inputCredentials),
+          outputs: JSON.stringify(outputs),
+        })
+      : null;
+
+    return {
+      isBatched: false,
+      data: [
+        {
+          fromAddressAndType: { type: AddressType.NONE, address: "0x0" },
+          accountingPayload,
+          stateMachinePayload,
+        },
+      ],
+    };
+  }
+}

package/primitives/src/cardano-utils/cardano-helpers.ts

@@ -0,0 +1,84 @@
+import { uint8ArrayToHexString } from "@effectstream/utils";
+import type { cardano } from "@utxorpc/spec";
+
+type CardanoNetwork = "preview" | "preprod" | "mainnet" | "yaci";
+
+const epochParams: Record<CardanoNetwork, { firstSlot: number; slotsPerEpoch: number; firstEpoch: number }> = {
+  mainnet:  { firstSlot: 4_492_800, slotsPerEpoch: 432_000, firstEpoch: 208 },
+  preprod:  { firstSlot: 86_400,    slotsPerEpoch: 432_000, firstEpoch: 4 },
+  preview:  { firstSlot: 0,         slotsPerEpoch: 86_400,  firstEpoch: 0 },
+  yaci:     { firstSlot: 0,         slotsPerEpoch: 600,     firstEpoch: 0 },
+};
+
+export function slotToEpoch(slot: number, network: CardanoNetwork): number {
+  const params = epochParams[network];
+  if (slot < params.firstSlot) return 0;
+  return params.firstEpoch + Math.floor((slot - params.firstSlot) / params.slotsPerEpoch);
+}
+
+export function stakeCredentialToHex(cred: cardano.StakeCredential): { type: "key" | "script"; hash: string } | null {
+  const inner = cred.stakeCredential;
+  if (inner.case === "addrKeyHash") {
+    return { type: "key", hash: uint8ArrayToHexString(inner.value) };
+  }
+  if (inner.case === "scriptHash") {
+    return { type: "script", hash: uint8ArrayToHexString(inner.value) };
+  }
+  return null;
+}
+
+export function addressToHex(address: Uint8Array): string {
+  return uint8ArrayToHexString(address);
+}
+
+export function metadataToJson(metadata: cardano.Metadata[]): Record<string, unknown> | null {
+  if (!metadata || metadata.length === 0) return null;
+  const result: Record<string, unknown> = {};
+  for (const entry of metadata) {
+    result[String(entry.label)] = entry.value ? metadatumToJson(entry.value) : null;
+  }
+  return result;
+}
+
+function metadatumToJson(m: cardano.Metadatum): unknown {
+  const inner = m.metadatum;
+  if (!inner || inner.case === undefined) return null;
+  switch (inner.case) {
+    case "int": return String(inner.value);
+    case "bytes": return uint8ArrayToHexString(inner.value);
+    case "text": return inner.value;
+    case "array": return inner.value.items.map(metadatumToJson);
+    case "map": return inner.value.pairs.map(p => ({
+      k: p.key ? metadatumToJson(p.key) : null,
+      v: p.value ? metadatumToJson(p.value) : null,
+    }));
+    default: return null;
+  }
+}
+
+function bigIntToString(bi: cardano.BigInt): string {
+  const inner = bi.bigInt;
+  if (inner.case === "int") return String(inner.value);
+  if (inner.case === "bigUInt") {
+    let result = 0n;
+    for (const byte of inner.value) result = (result << 8n) | BigInt(byte);
+    return String(result);
+  }
+  if (inner.case === "bigNInt") {
+    let result = 0n;
+    for (const byte of inner.value) result = (result << 8n) | BigInt(byte);
+    return String(-result);
+  }
+  return "0";
+}
+
+export function assetQuantityToString(asset: cardano.Asset): string {
+  const q = asset.quantity;
+  if (q.case === "outputCoin") return bigIntToString(q.value);
+  if (q.case === "mintCoin") return bigIntToString(q.value);
+  return "0";
+}
+
+export function isMintQuantity(asset: cardano.Asset): boolean {
+  return asset.quantity.case === "mintCoin";
+}

package/primitives/src/grammar.ts

@@ -15,6 +15,11 @@ import { nep245Grammar } from "./near-nep245/nep245-grammar.ts";
 import { nearIntentGrammar } from "./near-intent/near-intent-grammar.ts";
 import { nearGenericGrammar } from "./near-generic/near-generic-grammar.ts";
 import { nearAccountWatchGrammar } from "./near-account-watch/near-account-watch-grammar.ts";
+import { mintBurnGrammar } from "./cardano-mint-burn/mint-burn-grammar.ts";
+import { transferGrammar } from "./cardano-transfer/transfer-grammar.ts";
+import { poolDelegationGrammar } from "./cardano-pool-delegation/pool-delegation-grammar.ts";
+import { delayedAssetGrammar } from "./cardano-delayed-asset/delayed-asset-grammar.ts";
+import { projectedNftGrammar } from "./cardano-projected-nft/projected-nft-grammar.ts";
 
 export const builtinGrammars = {
   midnightGeneric: midnightGenericGrammar,
@@ -31,4 +36,9 @@ export const builtinGrammars = {
   nearIntent: nearIntentGrammar,
   nearGeneric: nearGenericGrammar,
   nearAccountWatch: nearAccountWatchGrammar,
+  cardanoMintBurn: mintBurnGrammar,
+  cardanoTransfer: transferGrammar,
+  cardanoPoolDelegation: poolDelegationGrammar,
+  cardanoDelayedAsset: delayedAssetGrammar,
+  cardanoProjectedNft: projectedNftGrammar,
 } as const;

package/primitives/src/midnight-generic/midnight-genetic.ts

@@ -242,6 +242,14 @@ function parseLedgerField(sv: StateValue, type: LedgerFieldType): any {
   return null;
 }
 
+function isCompactMap(data: object): data is Iterable<[unknown, unknown]> {
+  return (
+    typeof (data as any).member === 'function' &&
+    typeof (data as any).lookup === 'function' &&
+    Symbol.iterator in data
+  );
+}
+
 function makeJsonSafe(data: unknown): any {
   if (typeof data === 'boolean' || typeof data === 'number' || typeof data === 'string') {
     return data;
@@ -259,6 +267,13 @@ function makeJsonSafe(data: unknown): any {
     return uint8ArrayToHexString(data);
   }
   if (typeof data === 'object') {
+    if (isCompactMap(data)) {
+      const entries: [string, any][] = [];
+      for (const [k, v] of data) {
+        entries.push([String(makeJsonSafe(k)), makeJsonSafe(v)]);
+      }
+      return Object.fromEntries(entries);
+    }
     return Object.fromEntries(Object.entries(data).map(([k, v]) => [k, makeJsonSafe(v)]));
   }
   return data;

package/primitives/src/midnight-unshielded-spend/midnight-unshielded-spend-grammar.ts

@@ -0,0 +1,8 @@
+import { Type } from "@sinclair/typebox";
+
+export const midnightUnshieldedSpendGrammar = [
+  [
+    "payload",
+    Type.Any(),
+  ],
+] as const;

package/primitives/src/midnight-unshielded-spend/midnight-unshielded-spend.ts

@@ -0,0 +1,115 @@
+import { Primitive } from "@effectstream/sm";
+import {
+  type AddressAndType,
+  AddressType,
+  type EffectstreamBlockNumber,
+} from "@effectstream/utils";
+import type { StaticDecode } from "@sinclair/typebox";
+import {
+  type CommandTuple,
+  generateRawStmInput,
+  type ParamToData,
+} from "@effectstream/concise";
+import type {
+  ConfigSyncProtocolType,
+  FlattenSyncProtocolIOFor,
+  ProtocolPrimitiveMap,
+} from "@effectstream/config";
+import type { SyncStateUpdateStream } from "@effectstream/coroutine";
+import { PrimitiveTypeMidnightUnshieldedSpend } from "../builtin.ts";
+import { midnightUnshieldedSpendGrammar } from "./midnight-unshielded-spend-grammar.ts";
+
+/**
+ * MidnightUnshieldedSpendPrimitive
+ *
+ * Watches all unshielded UTXO spend events on the Midnight ledger. The
+ * indexer's GraphQL `transactions.unshieldedSpentOutputs` field reports the
+ * `(owner, intentHash, outputIndex)` triple for each unshielded UTXO
+ * consumed in a block. One state-machine input is emitted per spend.
+ *
+ * Usage:
+ *   stm.addStateTransition("myPrefix", function* (data) {
+ *     const { payload } = data.parsedInput;
+ *     // payload = { owner, intentHash, outputIndex, txHash }
+ *   });
+ */
+export class MidnightUnshieldedSpendPrimitive extends Primitive<
+  ConfigSyncProtocolType.MIDNIGHT_PARALLEL,
+  typeof midnightUnshieldedSpendGrammar
+> {
+  readonly internalTypeName = PrimitiveTypeMidnightUnshieldedSpend;
+  override readonly grammar = midnightUnshieldedSpendGrammar;
+
+  override dynamicTables = undefined;
+  override getIntermediatePrefix(): string[] {
+    return [];
+  }
+  override getViewPrefix(): string[] {
+    return [];
+  }
+
+  constructor(config: {
+    instanceName: string;
+    startBlockHeight: number;
+    stateMachinePrefix: string;
+  }) {
+    super(config);
+  }
+
+  override *getPayload(
+    _: EffectstreamBlockNumber,
+    primitiveTransactionData: FlattenSyncProtocolIOFor<
+      ConfigSyncProtocolType.MIDNIGHT_PARALLEL
+    >,
+  ): SyncStateUpdateStream<{
+    isBatched: boolean;
+    data: {
+      fromAddressAndType: AddressAndType;
+      stateMachinePayload:
+        | StaticDecode<CommandTuple<string, typeof midnightUnshieldedSpendGrammar>>
+        | null;
+      accountingPayload: ParamToData<typeof midnightUnshieldedSpendGrammar>;
+    }[];
+  }> {
+    const payload = primitiveTransactionData.output.payload;
+
+    const accountingPayload: ParamToData<typeof this.grammar> = {
+      payload,
+    };
+
+    const stateMachinePayload:
+      | StaticDecode<CommandTuple<string, typeof this.grammar>>
+      | null = this.stateMachinePrefix
+      ? generateRawStmInput(
+        this.grammar,
+        this.stateMachinePrefix,
+        accountingPayload,
+      )
+      : null;
+
+    return {
+      isBatched: false,
+      data: [
+        {
+          fromAddressAndType: {
+            type: AddressType.NONE,
+            address: "0x0",
+          },
+          accountingPayload,
+          stateMachinePayload,
+        },
+      ],
+    };
+  }
+
+  override getConfig(): ProtocolPrimitiveMap[
+    ConfigSyncProtocolType.MIDNIGHT_PARALLEL
+  ] {
+    return {
+      name: this.instanceName,
+      type: this.internalTypeName,
+      startBlockHeight: this.startBlockHeight,
+      scheduledPrefix: this.stateMachinePrefix ?? "",
+    } as const;
+  }
+}

package/primitives/src/mod.ts

@@ -1,6 +1,7 @@
 import {
   PrimitiveTypeMidnightGeneric,
   PrimitiveTypeMidnightNullifier,
+  PrimitiveTypeMidnightUnshieldedSpend,
   PrimitiveTypeEVMEffectstreamL2,
   PrimitiveTypeEVMERC721,
   PrimitiveTypeEVMERC20,
@@ -15,11 +16,17 @@ import {
   PrimitiveTypeNEARIntent,
   PrimitiveTypeNEARGeneric,
   PrimitiveTypeNEARAccountWatch,
+  PrimitiveTypeCardanoMintBurn,
+  PrimitiveTypeCardanoTransfer,
+  PrimitiveTypeCardanoPoolDelegation,
+  PrimitiveTypeCardanoDelayedAsset,
+  PrimitiveTypeCardanoProjectedNFT,
 //   PrimitiveTypeEVMGeneric,
 } from "./builtin.ts";
 
 import { MidnightGenericPrimitive } from "./midnight-generic/midnight-genetic.ts";
 import { MidnightNullifierPrimitive } from "./midnight-nullifier/midnight-nullifier.ts";
+import { MidnightUnshieldedSpendPrimitive } from "./midnight-unshielded-spend/midnight-unshielded-spend.ts";
 import { EffectstreamL2Primitive } from "./evm-effectstream-l2/effectstream-l2-primitive.ts";
 import { Erc721Primitive } from "./evm-erc721/erc721-primitive.ts";
 import { Erc20Primitive } from "./evm-erc20/erc20-primitive.ts";
@@ -34,11 +41,17 @@ import { Nep245Primitive } from "./near-nep245/nep245-primitive.ts";
 import { NearIntentPrimitive } from "./near-intent/near-intent-primitive.ts";
 import { NearGenericPrimitive } from "./near-generic/near-generic-primitive.ts";
 import { NearAccountWatchPrimitive } from "./near-account-watch/near-account-watch-primitive.ts";
+import { CardanoMintBurnPrimitive } from "./cardano-mint-burn/mint-burn-primitive.ts";
+import { CardanoTransferPrimitive } from "./cardano-transfer/transfer-primitive.ts";
+import { CardanoPoolDelegationPrimitive } from "./cardano-pool-delegation/pool-delegation-primitive.ts";
+import { CardanoDelayedAssetPrimitive } from "./cardano-delayed-asset/delayed-asset-primitive.ts";
+import { CardanoProjectedNftPrimitive } from "./cardano-projected-nft/projected-nft-primitive.ts";
 // import { EvmGenericPrimitive } from "./evm-generic/evm-generic-primitive.ts";
 
 const builtInPrimitivesMap = {
   [PrimitiveTypeMidnightGeneric]: MidnightGenericPrimitive,
   [PrimitiveTypeMidnightNullifier]: MidnightNullifierPrimitive,
+  [PrimitiveTypeMidnightUnshieldedSpend]: MidnightUnshieldedSpendPrimitive,
   [PrimitiveTypeEVMEffectstreamL2]: EffectstreamL2Primitive,
   [PrimitiveTypeEVMERC721]: Erc721Primitive,
   [PrimitiveTypeEVMERC20]: Erc20Primitive,
@@ -53,6 +66,11 @@ const builtInPrimitivesMap = {
   [PrimitiveTypeNEARIntent]: NearIntentPrimitive,
   [PrimitiveTypeNEARGeneric]: NearGenericPrimitive,
   [PrimitiveTypeNEARAccountWatch]: NearAccountWatchPrimitive,
+  [PrimitiveTypeCardanoMintBurn]: CardanoMintBurnPrimitive,
+  [PrimitiveTypeCardanoTransfer]: CardanoTransferPrimitive,
+  [PrimitiveTypeCardanoPoolDelegation]: CardanoPoolDelegationPrimitive,
+  [PrimitiveTypeCardanoDelayedAsset]: CardanoDelayedAssetPrimitive,
+  [PrimitiveTypeCardanoProjectedNFT]: CardanoProjectedNftPrimitive,
 //   [PrimitiveTypeEVMGeneric]: EvmGenericPrimitive,
 } as const;
 
@@ -63,6 +81,7 @@ export {
   // Built-in Primitives
   MidnightGenericPrimitive,
   MidnightNullifierPrimitive,
+  MidnightUnshieldedSpendPrimitive,
   EffectstreamL2Primitive,
   Erc721Primitive,
   Erc20Primitive,
@@ -77,5 +96,10 @@ export {
   NearIntentPrimitive,
   NearGenericPrimitive,
   NearAccountWatchPrimitive,
+  CardanoMintBurnPrimitive,
+  CardanoTransferPrimitive,
+  CardanoPoolDelegationPrimitive,
+  CardanoDelayedAssetPrimitive,
+  CardanoProjectedNftPrimitive,
   // EvmGenericPrimitive,
 };

package/types.ts

@@ -1,5 +1,3 @@
-//import type { AppEvents } from "@effectstream/events";
-
 import type { PreparedQuery } from "@pgtyped/runtime";
 import type {
   AddressType,
@@ -8,11 +6,27 @@ import type {
   WalletAddress,
 } from "@effectstream/utils";
 import type { Prando } from "@effectstream/crypto";
+import type { EventPathAndDef, ResolvedPath } from "@effectstream/event-client";
+import type { Static } from "@sinclair/typebox";
 
-// TODO What is AppEvent type?
-export type AppEvents = any;
+/**
+ * Closure passed to every state transition for emitting custom app events.
+ *
+ * - The runtime collects events into a per-input buffer during STF execution.
+ * - On STF success, events are promoted to the per-block buffer.
+ * - After the block's `COMMIT` succeeds, events are flushed to MQTT.
+ * - On STF failure or block-level `ROLLBACK`, events are dropped.
+ *
+ * `blockHeight` is auto-injected by `registerEvents` and auto-filled by the
+ * runtime — apps omit it from the payload.
+ *
+ * See plan: /Users/edwardalvarado/.claude/plans/wild-kindling-reddy.md
+ */
+export type EmitFn = <E extends EventPathAndDef>(
+  event: E,
+  payload: Omit<Static<E["type"]> & ResolvedPath<E["path"]>, "blockHeight">,
+) => void;
 
-// TODO: replace any
 export type BaseStfInput = {
   blockHeight: EffectstreamBlockNumber;
   blockTimestamp: TimestampMs;
@@ -21,7 +35,15 @@ export type BaseStfInput = {
   signerAddress?: WalletAddress;
   signerAddressType?: AddressType;
   randomGenerator: Prando;
+  /** Emit a custom app event. Delivered to MQTT after the block commits. */
+  emit: EmitFn;
 };
+
+// Retained for compatibility with the existing `Stm<Grammar, Events>` generic
+// parameter. Future work: thread a real registered-events union through here so
+// `data.emit` is restricted to the app's declared events.
+export type AppEvents = any;
+
 export type BaseStfOutput<Events extends AppEvents> = {
   stateTransitions: [PreparedQuery<any, any>, any][];
   events: Events[];