Midnight SDK Generator

Automate the creation of type-safe TypeScript SDKs for Midnight Network Compact contracts.

The Midnight SDK Generator provides a strongly-typed bridge between your Compact smart contracts and your TypeScript applications. By automating the generation of boilerplate code, it ensures that your frontend and backend integrations remain synchronized with your contract logic while benefiting from complete IDE type support.

The Problem

Developing on Midnight involves interacting with ZK-circuits and a private ledger. Manually writing the TypeScript glue code to call these circuits and read ledger state is:

• Error-prone: Manual type mapping can lead to runtime failures.
• Maintenance-heavy: Every contract change requires a manual update to the SDK.
• Boilerplate-intensive: Setting up contract stubs and providers involves repetitive code.

Midnight SDK Generator solves this by deriving a production-ready SDK directly from your contract's metadata.

Core Workflow

The SDK generation follows a simple three-step process:

1. Write your Contract: Author your logic in .compact.
2. Compile to Metadata: Use the compact compiler to generate a structured JSON representation of your contract.
3. Generate SDK: Run midnight-sdk-gen to produce a type-safe TypeScript class.

Installation

Project Dependency (Recommended)

Add the generator to your DApp project to keep it versioned with your codebase:

npm install --save-dev midnight-sdk-gen

Global Installation

Alternatively, install it globally for use across multiple projects:

npm install -g midnight-sdk-gen

Usage Guide

1. Generating the Metadata

The generator consumes the JSON structure produced by the Midnight compiler. Ensure you have the compact tool installed and run:

compact compile your-contract.compact

2. Generating the TypeScript SDK

Once you have your structure.json, use the generator to create your SDK:

midnight-sdk-gen ./path/to/structure.json --output ./src/sdk/MyContractSDK.ts

Real-World Example: Counter Contract

The Compact Source (counter.compact)

pragma language >= 0.5.0;
import './stdlib.compact';

export ledger {
    round: Uint64;
}

export circuit increment(): [] {
    round = round + 1;
}

Integrating with a TypeScript Project

After running the generator, you can import the CounterSDK directly into your application (e.g., a Vite, Next.js, or Node.js project):

import { MidnightProviders, Wallet } from "@midnight-ntwrk/midnight-js";
import { CounterSDK } from "./sdk/CounterSDK";

async function runDApp(providers: MidnightProviders, wallet: Wallet) {
  // Initialize the SDK (Deploying a new instance or finding an existing one)
  const sdk = await CounterSDK.deploy(providers, wallet, 0n);

  // Call a circuit (Mutation)
  const tx = await sdk.increment();
  await tx.submit();

  console.log(`Successfully incremented. Transaction ID: ${tx.txId}`);

  // Access the Ledger (Query)
  const currentStatus = await sdk.ledger.round();
  console.log(`Current ledger state: ${currentStatus}`);
}

Type Mapping Reference

The generator automatically maps Compact types to their most appropriate TypeScript equivalents:

| Compact Type | TypeScript Type | Note | | :------------- | :--------------- | :--------------------------- | | Boolean | boolean | Native boolean | | Uint<N> | bigint | Arbitrary-precision integers | | Bytes<N> | Uint8Array | Standard byte arrays | | Counter | bigint | Shielded increments | | Maybe<T> | T \| undefined | Nullable types | | Vector<N, T> | T[] | Fixed-size or dynamic arrays |

Project Integration

To integrate this tool into a standard development workflow, we recommend adding a generation script to your package.json:

{
  "scripts": {
    "gen:sdk": "midnight-sdk-gen ./contracts/metadata/counter.json -o ./src/sdk/counter.ts"
  }
}

This allows your team to simply run npm run gen:sdk whenever the smart contracts are updated.

Publishing to NPM

If you are a contributor and wish to publish a new version of this tool:

1. Authenticate: npm login
2. Update version: Ensure the version in package.json is bumped accordingly.
3. Publish: npm publish --access public

License

MIT © Midnight Developer Community