> For the complete documentation index, see [llms.txt](https://docs.midnight.network/llms.txt)

# Build a cross-chain DApp with EffectStream

Use this guide to build a DApp whose state lives on Midnight and an EVM chain at once. You run a working template, learn how it joins the two chains, then add a field of your own end to end.

[Index contract state with EffectStream](https://docs.midnight.network/guides/index-state-with-effectstream.md) covers reading one Midnight contract. This guide covers the case EffectStream exists for: correlating two chains, and writing to them.

Community-maintained, not officially supported

[EffectStream](https://github.com/effectstream/effectstream) maintains the template and the `@effectstream/*` packages this guide uses, not the Midnight Foundation. This guide uses the template at a tested commit on the `midnight-1` branch, which EffectStream maintains for the current Midnight networks. The default branch, `v-next`, targets the next ledger release, and its template does not start from a clean clone at the moment. See [effectstream#895](https://github.com/effectstream/effectstream/issues/895). Report EffectStream problems on the [EffectStream tracker](https://github.com/effectstream/effectstream/issues), and problems with this page on the [Midnight docs repository](https://github.com/midnightntwrk/midnight-docs/issues).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

These apply to every procedure in this guide:

* [Git](https://git-scm.com/) for cloning the template repository.
* A Linux x86-64, Linux arm64, or Apple silicon machine. The orchestrator runs the Midnight node, indexer, and proof server as native binaries, so Docker is not required. The binary packages ship for only those three platforms. Anywhere else, such as an Intel Mac, the template stops with `Unsupported platform` before it downloads anything.
* [Bun](https://bun.sh). See [Set up Bun for Midnight development](https://docs.midnight.network/how-to/bun-runtime-midnight.md).
* [Foundry](https://www.getfoundry.sh/). `forge` compiles the Solidity artifacts, and the orchestrator checks for it on `PATH` before starting.
* The Compact toolchain, which the orchestrator checks on `PATH` before starting. The template's build script selects toolchain `0.31.0` explicitly, so install it alongside your default with `compact update 0.31.0 --no-set-default`. Confirm with `compact compile +0.31.0 --version`, which prints `0.31.0`. Keep this version for the template only, and compile your own contracts with the toolchain in the [support matrix](https://docs.midnight.network/relnotes/support-matrix.md).
* Enough memory for the frontend build, the heaviest step. Vite transforms about 9000 modules and uses about 3 GB. Node sizes its default heap from the machine's memory, so on a machine with less than 16 GB, export `NODE_OPTIONS=--max-old-space-size=4096` before starting.

The template launches its own Midnight stack, so you need no separately running node or proof server.

<!-- -->

## How a rollup joins two chains[​](#how-a-rollup-joins-two-chains "Direct link to How a rollup joins two chains")

Splitting a DApp across chains usually means a bridge: a message-passing contract, a relayer, and a light client that lets one chain verify the other. That machinery exists to make execution atomic across chains.

EffectStream targets the weaker requirement. When you need a consistent view of two chains rather than atomic execution across them, neither chain has to know the other exists. Both are ingested independently, and a state machine you write merges them into one database.

The template splits an NFT along that line. An ERC-721 contract on the EVM chain owns transfers, because everyone needs to agree on who holds a token. A Compact circuit on Midnight records a property for a token. It takes the contract address, token ID, property name, and value as arguments, and writes each one to the public ledger with `disclose()`. The template's circuit keeps nothing private. In a real DApp, the circuit computes the disclosed value from private inputs. The two sides share a key, `(contract_address, token_id)`, which you supply to both. The database stores and links rows by that key. The template's merged API query joins on `token_id` alone, though, so its results mix up tokens from two contracts that share an ID.

One consequence shapes the code you write. EffectStream reads Midnight's public ledger, so values a circuit discloses and writes to the ledger are what your state machine can see. Designing the circuit designs the sync surface.

A second one shows up in the logs. Each chain syncs independently, so a Midnight property can arrive before the EVM transfer that created the token. The `midnightContractState` transition handles this by inserting a placeholder row with an empty owner. It also skips the freshly deployed contract, whose fields are all still empty, and logs `empty token_id, skipping`.

<!-- -->

## Run the template[​](#run-the-template "Direct link to Run the template")

Start the whole stack and mint a token.

### Procedure[​](#procedure "Direct link to Procedure")

1. Clone the repository, check out the tested commit, and enter the template:

   ```
   git clone --branch midnight-1 https://github.com/effectstream/effectstream.git

   cd effectstream

   git checkout 667173ac79aad6c51bf5d97e87355c3438a48be8

   cd templates/evm-midnight-v2
   ```

2. Install dependencies:

   ```
   bun install
   ```

3. Start the stack. The `dev` script launches the database and the Midnight node, indexer, and proof server, and compiles the Compact circuit and the Solidity contracts. It then starts the local EVM chains, deploys both contracts, and starts the sync node, batcher, and frontend:

   ```
   bun run dev
   ```

4. Open the DApp at `http://localhost:10599` and connect both wallets. Neither needs a browser extension. Select **Connect EVM**, then **Connect Local Wallet**, which uses an account the local EVM chain funds at startup. Then select **Connect Midnight**. The page builds a wallet from the local network's genesis seed and joins the deployed contract. The button shows the wallet address when it finishes.

5. Enter a token ID next to **Mint #** and select **MINT**.

6. Select the new token, enter a name under **Update Token Name**, and select **Save**.

### Verification[​](#verification "Direct link to Verification")

The sync node runs independently of the frontend, and starts before the frontend build finishes, so check it directly. The merged view returns each token with its EVM owner and its Midnight properties:

```
curl http://localhost:9999/api/erc721
```

```
[{"token_id":"1","owner":"0x14dc79964da2c08b23698b3d3cc7ca32193d9955","block_height":348,"property_name":"Name","value":"Aurora","property_block_height":465}]
```

The owner comes from the EVM chain, and the property name and value come from Midnight. A token with no property yet shows `null` in the three property fields, and a new property can take several seconds to appear. Your values differ.

The sync node's own logs show both chains advancing together, which is the rollup working:

```
INFO effectstream-sync-block-merge: finalized block 465 @ 0x8d64ba... | {"mainNtp":[465,465],"mainEvmRPC":[2136,2138],"parallelMidnight":[87,87]}

[Midnight:undeployed] Fetching blocks from 89 to 89.
```

`finalized block 465` is EffectStream's own block number, the same number as the `mainNtp` pair. Each other pair is the lowest and highest block of one chain merged into that EffectStream block. This one carried EVM blocks 2136 to 2138 and Midnight block 87. The `parallelMidnight` pair appears only on blocks that carried a Midnight block. The API reports these EffectStream block numbers too, so `property_block_height` above is 465, not 87.

<!-- -->

## Local service endpoints[​](#local-service-endpoints "Direct link to Local service endpoints")

The template starts these services on the ports shown.

| Service                | URL                                                    |
| ---------------------- | ------------------------------------------------------ |
| Frontend               | `http://localhost:10599`                               |
| Sync node API          | `http://localhost:9999`                                |
| Sync node OpenAPI docs | `http://localhost:9999/documentation`                  |
| Batcher                | `http://localhost:3334`                                |
| Orchestrator API       | `http://localhost:4747`                                |
| EVM chain (main)       | `http://localhost:8545`                                |
| EVM chain (parallel)   | `http://localhost:8546`                                |
| Midnight node RPC      | `http://localhost:9944`                                |
| Midnight indexer       | `http://localhost:8088/api/v4/graphql`                 |
| Midnight proof server  | `http://localhost:6300`                                |
| Database               | `postgres://postgres:postgres@localhost:5432/postgres` |

<!-- -->

## The ingestion pipeline[​](#the-ingestion-pipeline "Direct link to The ingestion pipeline")

Four files carry a chain event from the wire into your API. Read them in order to understand the template.

`packages/node/config.dev.ts` declares networks, sync protocols, and primitives. One primitive per chain, each naming a `stateMachinePrefix`:

```
.addPrimitive(

  (syncProtocols) => syncProtocols.parallelMidnight,

  (network, deployments, syncProtocol) => ({

    name: "MidnightContractState",

    type: PrimitiveTypeMidnightGeneric,

    startBlockHeight: 1,

    contractAddress: readMidnightContract("contract-round-value", {

      networkId: midnightNetworkConfig.id,

    }).contractAddress,

    stateMachinePrefix: "midnightContractState",

    contract: { ledger: CounterContract.ledger },

    networkId: midnightNetworkConfig.id,

  }),

)
```

`contract: { ledger: CounterContract.ledger }` hands the primitive the reader that `compact compile` generates. That reader decodes every exported ledger field, including struct fields, lists, and Merkle trees, which is the difference from the declarative schema in [Index contract state with EffectStream](https://docs.midnight.network/guides/index-state-with-effectstream.md#what-the-ledger-schema-can-read).

`packages/node/grammar.ts` maps each prefix to a parser. Both prefixes use builtin grammars, so the template writes none of its own.

`packages/node/state-machine.ts` holds one state transition function per prefix. Each receives the parsed payload and writes to the database.

`packages/node/api.ts` serves the merged result over HTTP.

<!-- -->

## Add a field end to end[​](#add-a-field-end-to-end "Direct link to Add a field end to end")

Carry one new value from the Compact circuit to the API. Nothing generates this path for you, so a single field touches the circuit, the database schema, the queries, the state transition, and the route. Knowing that cost up front is part of choosing this pattern.

### Procedure[​](#procedure-1 "Direct link to Procedure")

1. Open `packages/contracts-midnight/contract-round-value/src/counter.compact`. Add a ledger field, take a matching argument in `increment`, and assign it through `disclose()`. The additions are marked:

   ```
   pragma language_version >= 0.17;



   import CompactStandardLibrary;



   export ledger round: Counter;

   export ledger contract_address: Bytes<64>;

   export ledger token_id: Bytes<64>;

   export ledger property_name: Bytes<32>;

   export ledger value: Bytes<32>;

   export ledger rarity: Bytes<32>;          // added



   export circuit increment(

     contract_address_: Bytes<64>,

     token_id_: Bytes<64>,

     property_name_: Bytes<32>,

     value_: Bytes<32>,

     rarity_: Bytes<32>,                     // added

   ): [] {

     round.increment(1);

     contract_address = disclose(contract_address_);

     token_id = disclose(token_id_);

     property_name = disclose(property_name_);

     value = disclose(value_);

     rarity = disclose(rarity_);             // added

   }
   ```

   Adding an argument changes the circuit's signature, so every caller needs the new value. Step 7 covers the callers.

2. Recompile the circuit so the generated ledger reader includes the new field:

   ```
   bun run build:midnight
   ```

3. Add a `rarity TEXT` column to the `evm_midnight_properties` table in `packages/database/migrations/000-init.sql`, the single migration the template ships.

4. In `packages/database/sql/sm_example.sql`, add `rarity` to the `insertEvmMidnightProperty` insert and to the columns `getEvmMidnight` selects, then regenerate the typed queries:

   ```
   bun run build:pgtypes
   ```

5. Decode the field in the `midnightContractState` transition in `packages/node/state-machine.ts`. A `Bytes<32>` ledger field arrives as fixed-width bytes, so `decodeField` turns it back into a string. Add `rarity` to the `payload` type at the top of the transition, then add a line next to the existing ones:

   ```
   const contract_address = decodeField(payload.contract_address);

   const token_id = decodeField(payload.token_id);

   const property_name = decodeField(payload.property_name);

   const value = decodeField(payload.value);

   const rarity = decodeField(payload.rarity);        // added
   ```

   Then pass `rarity` into the `insertEvmMidnightProperty` call further down the same transition, alongside the fields already written there.

6. In `packages/node/api.ts`, add `rarity: Type.String()` to `ResponseSchema`. The `GET /api/erc721` handler returns whatever `getEvmMidnight` selects, so the schema is the only change the route needs.

7. Pass the new argument where the template calls the circuit, the `callTx.increment` call in `packages/frontend/client/src/increment.ts`. The frontend has no input for `rarity`, so pass a fixed value after the property value:

   ```
   const finalizedTxData = await counterContract.callTx.increment(

     toEncodedString(contractAddress, 64),

     toEncodedString(tokenId, 64),

     toEncodedString(propertyName, 32),

     toEncodedString(propertyValue, 32),

     toEncodedString("legendary", 32),        // added

   );
   ```

   The end-to-end test in `packages/tests/stm/midnight-property.test.ts` makes the same call, so add a value there too if you run `bun run test`. Nothing in the template's build checks these calls against the circuit. A call you forget fails at runtime with `increment: expected 6 arguments (as invoked from Typescript), received 5`.

8. Restart the stack, then mint a token and set a property from the frontend as before. A restart begins from an empty database, new local chains, and a new Midnight contract, so tokens from the earlier run are gone.

### Verification[​](#verification-1 "Direct link to Verification")

The endpoint returns the new field alongside the existing ones:

```
curl http://localhost:9999/api/erc721
```

```
[{"token_id":"1","owner":"0x14dc79964da2c08b23698b3d3cc7ca32193d9955","block_height":26,"property_name":"Name","value":"Aurora","rarity":"legendary","property_block_height":129}]
```

<!-- -->

## Stop and reset the stack[​](#stop-and-reset-the-stack "Direct link to Stop and reset the stack")

Press Ctrl+C in the terminal running `bun run dev`. The orchestrator stops every process it started and frees their ports, so nothing survives in the background.

Two things survive on disk under `packages/contracts-midnight/`: the `midnight-level-db-deploy` directory, which holds private state, and `contract-round-value.undeployed.json`, which records the deployed address. The database and the local chains do not survive. The next `bun run dev` starts them empty and deploys a fresh Midnight contract at a new address, so tokens and properties from an earlier run are gone.

<!-- -->

## Template troubleshooting[​](#template-troubleshooting "Direct link to Template troubleshooting")

Failures you are likely to hit on this guide's path, and their fixes. Every quoted message comes from a real run.

| Symptom                                                                                                                                                                    | Cause                                                                                                                                                                                                            | Fix                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| The contract compile fails with `Couldn't find compiler for aarch64-darwin (0.33.0-rc.2)`, and `compact update 0.33.0-rc.2` fails with `Couldn't find version 0.33.0-rc.2` | You cloned the default branch, `v-next`. Its template compiles with a prerelease toolchain that `compact update` cannot install. See [effectstream#895](https://github.com/effectstream/effectstream/issues/895) | Clone the tested commit on `midnight-1`, as in [Run the template](#run-the-template)                                     |
| The frontend build stops with `JavaScript heap out of memory`                                                                                                              | Node sizes its default heap from the machine's memory, and on a smaller machine that heap is too small for the build                                                                                             | Export `NODE_OPTIONS=--max-old-space-size=4096`, then run `bun run dev` again                                            |
| The frontend build warns `"WebSocket" is not exported by ".../isomorphic-ws/browser.js"`                                                                                   | The Midnight.js indexer provider imports a named `WebSocket` that the browser build of `isomorphic-ws` does not export. In the browser, the provider uses the browser's own `WebSocket` instead                  | None needed. **Connect Midnight** works with this warning                                                                |
| The sync log shows `[STM:midnight] empty token_id, skipping`                                                                                                               | The sync node read the freshly deployed contract, whose fields are all still empty                                                                                                                               | None needed. It appears before you set the first property                                                                |
| A circuit call fails with `increment: expected 6 arguments (as invoked from Typescript), received 5`                                                                       | A caller still passes the old arguments after you added `rarity` to the circuit                                                                                                                                  | Add the new argument to every `callTx.increment` call, as in step 7 of [Add a field end to end](#add-a-field-end-to-end) |

## Additional resources[​](#additional-resources "Direct link to Additional resources")

* [Index contract state with EffectStream](https://docs.midnight.network/guides/index-state-with-effectstream.md): the read path, one Midnight contract, no local stack.
* [EffectStream documentation](https://effectstream.github.io/docs/): the project's own documentation, including the batcher and the other cross-chain templates.
* [Security and best practices](https://docs.midnight.network/guides/security-best-practices.md#on-chain-visibility): how `disclose()` permits private data to cross into public ledger state.
