DEV Community: Haruki Kondo

Prediction Markets Show Your Bet Instantly — So I Hid Mine With Zero-Knowledge Proofs

Haruki Kondo — Fri, 24 Jul 2026 12:31:51 +0000

Introduction

Polymarket, and on-chain prediction markets like it, kept bothering me for one reason.

Polymarket |世界最大の予測市場™

Polymarketは世界最大の予測市場であり、さまざまなトピックにわたって将来のイベントを取引することで、最新情報を入手し、知識から利益を得ることができます。

polymarket.com

Who bet on what is visible in near real time.

The moment a whale places a big bet on one outcome, everyone watching piles in behind them, and the odds move accordingly. That's not manipulation — it's just what happens with a public ledger. But it doesn't satisfy the simple wish to not reveal your prediction before everyone else does.

So: could you build a prediction market that keeps your pick hidden until voting closes?

To find out, I built Hidden League Forecast on Midnight, a privacy-focused blockchain.

It's an MVP where you just guess the winner of a fictional soccer league (the World Cup just ended, so soccer was on my mind).

Note
What's a prediction market?

A mechanism that expresses predictions about future events as prices. Think "which team will win the World Cup match," for example.

If you want to learn more about prediction markets, this resource (Japanese) is a great start:
https://zenn.dev/barabara/books/prediction-markets-structure

The backend is written in Compact, Midnight's smart contract language.

Note
It combines the commit-reveal pattern with zero-knowledge proofs so that "the content of your prediction stays hidden, while only the aggregate stake becomes public."

In this article, I'll walk through the contract code, showing what stays hidden and what becomes public at each step.

Note
This app runs on testnet.

Demo Video

After connecting Lace Wallet, you see your Shielded Address and balance. From here you can deploy a new market or enter an existing contract address to join one.

The Overall Flow

What's actually happening is simple.

OPEN → REVEAL → AWAITING RESULT → RESOLVED → CLAIM

Connect Lace Wallet, then deploy a market or join an existing one
Pick one of 4 teams (Amber Foxes / Cedar Owls / Harbor Whales / Meadow Bears) and stake 10–500 points
Once the admin closes predictions, participants "reveal" their picks
The admin records the result
Participants who picked the winning team claim a pari-mutuel payout (the losing side's stakes get split among the winners)

reward = floor(total_pool × your_stake / winning_team_pool)

Note
Key point

At step 2, which team you bet on is never recorded anywhere on-chain. Only the stake amount and a commitment (a hash used to verify the pick later) are recorded.

Nobody — not even the admin — can see it until the reveal in step 3.

The Smart Contract, Written in Compact

Midnight's Compact lets you declare variables (witnesses) that "are used inside the proof but never written to the ledger." Conversely, any value you do write to the ledger must go through disclose().

That guards against the "oops, I accidentally logged a secret value" class of mistake at the type level.

The secret key, the chosen team, and the salt are all defined as witnesses.

witness local_secret_key(): Bytes<32>;
witness get_selected_team(): Team;
witness get_prediction_salt(): Bytes<32>;
witness store_prediction(team: Team, stake: Uint<64>, salt: Bytes<32>): [];

Here's the ledger side.

export ledger phase:                 MarketPhase;
export ledger admin_key:             Bytes<32>;
export ledger commitments:           Map<Bytes<32>, Bytes<32>>;
export ledger stakes:                Map<Bytes<32>, Uint<64>>;
export ledger participants:          Set<Bytes<32>>;
export ledger revealed:              Set<Bytes<32>>;
// ... per-team pools, etc.

commitments only holds hashes, and stakes only holds amounts. "Who" bet and "how much" is public, but "which team" doesn't exist anywhere yet at this point.

Commit: Only the Hash Hits the Ledger

Here's the circuit called when you place a bet.

export circuit commit_prediction(stake: Uint<64>): [] {
  const public_stake = disclose(stake);
  assert(phase == MarketPhase.open, "Predictions are closed");
  assert(public_stake >= 10 && public_stake <= 500, "Stake must be between 10 and 500 points");

  const key = derive_participant_key(local_secret_key());
  assert(!participants.member(disclose(key)), "Participant already committed");
  const team = get_selected_team();
  const salt = get_prediction_salt();
  const commitment = make_prediction_commitment(key, team, public_stake, salt);
  store_prediction(team, public_stake, salt);

  participants.insert(disclose(key));
  commitments.insert(disclose(key), disclose(commitment));
  stakes.insert(disclose(key), public_stake);
  participant_count.increment(1);
  total_pool = (total_pool + public_stake) as Uint<64>;
}

team is never disclose()d here. It's only used as an input to make_prediction_commitment(), and only that function's return value (a hash) gets written to the ledger, via disclose(commitment).

pure circuit make_prediction_commitment(
  participant_key: Bytes<32>,
  team: Team,
  stake: Uint<64>,
  salt: Bytes<32>
): Bytes<32> {
  const team_bytes = ((team as Field) as Bytes<32>);
  const stake_bytes = ((stake as Field) as Bytes<32>);
  return persistentHash<Vector<5, Bytes<32>>>([
    pad(32, "forecast:pick:v1"), participant_key, team_bytes, stake_bytes, salt
  ]);
}

Mixing the fixed string "forecast:pick:v1" into the first slot of persistentHash is a standard trick called domain separation. Tagging each circuit's hash inputs differently prevents an accidental collision where two different circuits produce the same hash for the same underlying values. The participant key derivation (derive_participant_key) uses its own tag, "forecast:participant:v1".

Note
The salt isn't there because the stake only ranges from 10 to 500. stake is already written to stakes as plaintext at commit_prediction time, so it's public information an observer doesn't even need to guess.

The real weak point is that team only has 4 possible values. Without a salt, an observer could take the (already public) participant key and stake, hash all 4 team candidates, and instantly find which one matches the on-chain commitment. Mixing in a random 256-bit salt makes that 4-way brute force infeasible.

On screen, you pick a team and a stake (Confidence points), then hit "Seal my forecast."

At this point, the team breakdown on the left is still frozen.

Staking 370 points on Harbor Whales. The team list on the left still just shows "SEALED" — nothing about the breakdown is public yet.

Pressing "Seal my forecast" kicks off ZK proof generation, and you'll see a toast like this while it runs.

The browser is generating a proof for the commit_prediction circuit. Behind the scenes, the witnesses (get_selected_team / get_prediction_salt) read their values out of local private state.

Reveal: Prove It, Then Publish It

After the deadline, participants "reveal" their prediction.

export circuit reveal_prediction(): [] {
  assert(phase == MarketPhase.reveal, "Market is not accepting reveals");
  const key = derive_participant_key(local_secret_key());
  const public_key = disclose(key);
  assert(participants.member(public_key), "Participant did not commit");
  assert(!revealed.member(public_key), "Prediction already revealed");

  const team = get_selected_team();
  const salt = get_prediction_salt();
  const stake = stakes.lookup(public_key);
  const expected = make_prediction_commitment(key, team, stake, salt);
  assert(disclose(expected == commitments.lookup(public_key)), "Prediction commitment mismatch");

  if (disclose(team == Team.amber_foxes)) { amber_foxes_pool = (amber_foxes_pool + stake) as Uint<64>; }
  // ... same for the other teams
  revealed.insert(public_key);
  revealed_count.increment(1);
}

All this circuit does is recompute the exact same hash from the values read back out of the witnesses, and prove it matches the hash already sitting on the ledger. Only once that matches does a comparison like if (disclose(team == Team.amber_foxes)) finally turn the team into public information and add the stake to that team's pool.

This guarantees that "the team you're revealing really is the one you picked at commit time." Rewriting the locally stored selectedTeam or salt afterward to switch to a more favorable team gets rejected by this assert. There's actually a Vitest simulator test for exactly this case:

it("rejects a modified private prediction", () => {
  market.setPrediction("alice", Team.amber_foxes, 100n, 11);
  market.commit("alice", 100n);
  market.closePredictions();
  market.setPrediction("alice", Team.cedar_owls, 100n, 99);
  expect(() => market.reveal("alice")).toThrow();
});

Rewriting the local selection to cedar_owls after committing, then trying to reveal, gets rejected as expected. Without this check, the whole point of the privacy mechanism — preventing after-the-fact switching to whichever side looks better — would collapse. I consider this the single most important test in the suite, unglamorous as it is.

As reveals come in, the per-team breakdown that was invisible at commit time finally starts showing up on screen.

"YOUR POSITION" on the right shows your own prediction (Cedar Owls, 100pt) as "revealed, awaiting the match result." The list on the left updates its per-team breakdown (% and points) as more reveals come in.

Verifying Division Without Doing Division

The pari-mutuel payout formula, floor(total_pool × stake / winning_team_pool), was a genuinely annoying part to get right. I didn't want to write division directly inside a ZK circuit, so the design instead has the client compute the division result, and the circuit only verifies that the result is correct.

Before the division check, though, there's actually a "is this person even allowed to claim?" section. Here's the whole circuit, nothing omitted.

export circuit claim_reward(reward: Uint<64>): [] {
  const public_reward = disclose(reward);
  assert(phase == MarketPhase.resolved && result_set, "Market is not resolved");
  const key = derive_participant_key(local_secret_key());
  const public_key = disclose(key);
  assert(revealed.member(public_key), "Prediction was not revealed");
  assert(!claimed.member(public_key), "Reward already claimed");
  const team = get_selected_team();
  const salt = get_prediction_salt();
  const stake = stakes.lookup(public_key);
  const expected = make_prediction_commitment(key, team, stake, salt);
  assert(disclose(expected == commitments.lookup(public_key)), "Prediction commitment mismatch");
  assert(disclose(team == winning_team), "Prediction did not win");

  const winning_pool = pool_for(winning_team);
  const payout_numerator = total_pool * stake;
  assert(public_reward * winning_pool <= payout_numerator, "Reward exceeds pari-mutuel entitlement");
  assert((public_reward + 1) * winning_pool > payout_numerator, "Reward is below floor-rounded entitlement");
  assert(total_claimed_rewards + public_reward <= total_pool, "Reward conservation violated");
  rewards.insert(public_key, public_reward);
  claimed.insert(public_key);
  total_claimed_rewards = (total_claimed_rewards + public_reward) as Uint<64>;
}

The first five lines repeat the same pattern as reveal_prediction — recompute the commitment from values read back out of the witnesses, and check it against the ledger. That's what stops anyone from claiming with someone else's stake or team. On top of that, revealed.member checks that the prediction was actually revealed, !claimed.member checks it hasn't already been claimed, and team == winning_team checks the caller actually picked the winner. All four asserts together are what prevent double claims and stealing someone else's winnings.

Note
Even though total_pool and stake are both Uint<64>, a multiplication like total_pool * stake doesn't silently wrap around at 64 bits — Compact's type system carries the full product range (Uint<0..(2^64-1)^2>) through the expression. I confirmed this by compiling a small overflow test with compact compile. In the actual contract, as Uint<64> casts only appear where a value is deliberately narrowed back down.

r = floor(n / p) is equivalent to the inequality r × p ≤ n < (r + 1) × p. That's exactly what these two asserts check, using only multiplication and comparison to validate "is this the correct floor-division result." Whether the caller supplies a suspiciously large reward or a suspiciously small one, one of these two inequalities catches it.

The last check, total_claimed_rewards + public_reward <= total_pool, is a conservation rule: even summing every winner's claim, the total can never exceed the pool. Any remainder left over from floor rounding simply stays in the pool unclaimed by design — I confirmed this with a test that covers the multiple-winners case too.

Once a market resolves, participants who picked the winning team see a computed reward amount and a "Claim forecast points" button.

A 100pt bet on Cedar Owls paid off, for an estimated reward of 440pts. That 440 is only a number the frontend computed — what actually lands on the ledger is whatever value you pass into claim_reward and gets past the two asserts above.

Private State Only Lives in the Browser

For the commitment check to work at all, selectedTeam and salt have to survive in the browser from commit time through reveal time. Here's the frontend implementation (pkgs/app/src/lib/prediction-market.ts):

export const savePrediction = async (
  providers: PredictionMarketProviders,
  team: Team,
  stake: bigint,
): Promise<void> => {
  const current =
    (await providers.privateStateProvider.get(PredictionMarketPrivateStateId)) ?? initialPrivateState;
  const salt = current.salt ?? crypto.getRandomValues(new Uint8Array(32));
  const next: PredictionMarketPrivateState = { ...current, selectedTeam: team, stake, salt };
  await providers.privateStateProvider.set(PredictionMarketPrivateStateId, next);
};

Before calling the circuit, the chosen team and a random salt get saved to the local private state store first. The get_selected_team and get_prediction_salt witnesses just read those values back out of that local store at proof-generation time.

The flip side is that if this local store gets wiped, you're locked out for good. The README carries this warning as-is:

Warning
This app has a constraint if you want to use multiple markets at once. PredictionMarketPrivateStateId is a fixed key scoped per network + wallet — not per contract address. That means committing to a second market with the same wallet overwrites the selectedTeam / salt that the first market needs, and you lose the ability to reveal your first prediction.

On top of that, derive_participant_key is derived purely from local_secret_key(), so the same wallet produces the same participant_key (and the same public admin_key, if you're the deployer) across every market. Within a single market, who bet on what stays hidden — but the fact that the same wallet is involved in multiple markets does not. That's an acceptable tradeoff for a single-market demo, but real multi-market use would need privateStateId scoped per contract address, plus market-specific data mixed into the key derivation.

Warning
Clearing your browser data, or switching devices, between committing and revealing means that prediction can never be revealed again.

Neither the secret key nor the salt is backed up anywhere server-side, so this is a genuine UX gap, not an oversight.

This is deliberately "temporary privacy," not "permanent anonymity." Revealing is something you choose to do, and once you reveal, that team becomes public information as a matter of course. The design doesn't try to preserve anonymity past the point where the market ends.

This "it only exists locally" feeling is easiest to see by putting two screens side by side.

In the browser that committed, "Forecast: Harbor Whales" is right there. That's not read from the ledger — this tab is just displaying its own private state.

Same resolved market, but a browser profile that never predicted just shows "No personal forecast is stored in this browser profile." The ledger only has the public result (Amber Foxes won) — who picked what is known only to whoever holds that private state.

Actually Running It

Just staring at the code, it's hard to tell whether the commit-reveal check is really doing its job. If you're curious, the fastest way to find out is to run the simulator tests yourself.

A devcontainer config is included — I'd recommend using it.

Prerequisites:

Bun 1.2.x
Compact CLI 0.30.0

bun install
bun run contract compact   # generate circuits, proving keys, and ZKIR from .compact
bun run test                # contract simulator tests

Example test output:

✓ src/test/prediction-market.test.ts (10 tests) 1142ms

 Test Files  1 passed (1)
      Tests  10 passed (10)

Those 10 tests include the cases mentioned earlier:

"rewriting local state before revealing gets rejected"
"stakes outside the allowed range, or duplicate commits, get rejected"
"a team with zero winning pool can't be selected as the result"
"floor division across multiple winners never pays out more than the pool"

If you want to see it running in a browser, deploy the contract, run bun run build and then bun run dev to start the Vite dev server, and connect Lace Wallet to the Preview network — that's the quickest way to try it.

The bundled headless CLI's (bun run cli standalone) "Show market state" command lets you follow the same 4 phases from a terminal too.

Watching phase transitions from the CLI (open → reveal → awaiting_result → resolved) ![CLI Show market state: Phase: open, Participants: 2, Total pool: 560](https://raw.githubusercontent.com/mashharuki/zenn-docs/main/images/midnight_simple_app-5/6.jpg) *Right after committing. 2 participants, 560 points total in the pool, but every per-team pool is still 0.* ![CLI Show market state: Phase: reveal, Revealed: 2, Team pools: cedar=100, meadow=340](https://raw.githubusercontent.com/mashharuki/zenn-docs/main/images/midnight_simple_app-5/8.jpg) *Both participants have revealed. This is the first time the per-team pools (cedar=100, meadow=340) get filled in.* ![CLI Show market state: Phase: awaiting_result](https://raw.githubusercontent.com/mashharuki/zenn-docs/main/images/midnight_simple_app-5/9.jpg) *The admin ran Close reveal, moving the market into the awaiting-result phase.* ![CLI Show market state: Phase: resolved, Result: cedar_owls](https://raw.githubusercontent.com/mashharuki/zenn-docs/main/images/midnight_simple_app-5/10.jpg) *The admin ran Resolve market, recording Cedar Owls as the winner. From here, only winners can call `claim_reward`.*

What This Design Doesn't Cover

Since this is a prototype, there are several things missing before it could become a real prediction market app — including anything that ingests outside information.

Trusts a single admin (steward). Whoever deployed the market has full authority to finalize the result. There's no external oracle or dispute-resolution mechanism.
Phase transitions only go one way — open → reveal → awaiting_result → resolved — with no undo or rollback. In particular, if reveals get closed while zero predictions have been revealed, that market becomes permanently unclaimable. That's a known area for future improvement.
What's at stake isn't a real asset — it's demo points specific to this app. There's no secondary market and no permissionless market creation.

Building a real privacy-preserving prediction market on this pattern would require multisig or optimistic-oracle result finalization, explicit deadline management, proper asset custody design, and an external audit.

This project's scope stops at "actually get hands-on with commit-reveal plus zero-knowledge proofs and understand it," since that's what I set out to learn.

Wrap-up

Following up on the anonymous rock-paper-scissors app, I built a prediction market app on Midnight too.

Midnight also just released an Agent Skill for AI coding tools, which makes development a lot smoother.

https://midskills.sevryn.xyz/

If you're looking for something to build, give Midnight a try.

Everything is open source, so if anything caught your interest, go read the code while running bun run test.

mashharuki / midnight-prediction-market-sample-app

Midnight Prediction Market sample dApp

Hidden League Forecast

A privacy-preserving, four-outcome football prediction market built with Midnight Compact, Midnight.js, and Lace Wallet.

Players predict which fictional club will win the Lantern Cup. During the open phase the team and salt stay in the browser's Midnight private-state store; only a salted commitment, pseudonymous participant key, and public demo-point stake reach the ledger. Picks are revealed only after predictions close, preventing followers from copying the crowd.

Educational example only. It uses demo points and a trusted market steward—not real assets or a production oracle.

Demo

Screen Shots

Market flow

OPEN → REVEAL → AWAITING RESULT → RESOLVED → CLAIM

Connect Lace and deploy or join a market.
Select Amber Foxes, Cedar Owls, Harbor Whales, or Meadow Bears.
Commit 10–500 public demo points. The team and salt remain private.
The steward closes predictions; participants reveal their committed picks.
The steward records the fictional match winner.
Correct predictions claim…

View on GitHub

Thanks for reading!

References

Building a Safe Telegram FX Bot with the Sera Protocol API and Privy

Haruki Kondo — Sun, 12 Jul 2026 07:33:48 +0000

I have previously explored Sera Protocol through its architecture, GraphQL API, smart contracts, a React frontend, an MCP server, and an Agent Skill.

For the next step, I wanted to move from “calling an API” to building something that a real user could operate without a dedicated trading interface. The result is a Telegram bot for stablecoin FX.

This article is for developers who know the basics of TypeScript and Web3. You do not need prior experience with Sera Protocol. We will cover the complete architecture, Sera REST API v2, wallet creation with Privy, EIP-712 signing, and the confirmation boundary that prevents the AI agent from moving funds by itself.

Here are the demo and source code first:

https://github.com/mashharuki/SeraProtocol-Sample/tree/main/telegram-bot

Note: This article reflects the implementation as of July 2026. Sera APIs, supported currencies, and contract addresses may change. Check the official documentation and the live response from GET /config before integrating it into your own application.

What I built

The Sera FX Telegram Bot is an onchain trading bot that uses Sera Protocol REST API v2 and Privy server wallets to perform stablecoin FX from Telegram.

Users do not need to open a separate web app or connect a browser extension wallet. Running /start creates an Ethereum wallet through Privy and takes the user directly into the guided trading flow.

The bot has four core characteristics:

Seed-phrase-free onboarding
English and Japanese support on Ethereum Mainnet and Sepolia
Swaps, cross-currency transfers, limit orders, and liquidity provision inside Telegram
The AI can prepare an action, but only the user's Confirm tap can trigger signing

The last point is the most important design decision in this project.

Giving an LLM direct access to a private key or unrestricted signing method would create an unacceptable security boundary. I separated the agent that interprets natural language from the deterministic code that authorizes and submits transactions.

Feature overview

Category	Command	What it does
Onboarding	`/start`	Select a language, create a Privy wallet, and issue a Sera API key
Assets	`/wallet`, `/balance`	Show the address, deposit QR code, wallet balance, and Vault balance
Market data	`/rate`, `/liquidity`	Show FX rates and probe which major pairs currently have executable liquidity
Instant trade	`/swap`	Execute an instant swap from a gas-inclusive quote
Transfer	`/send`	Convert a stablecoin and deliver the output to another address
Limit orders	`/order`, `/orders`	Create, inspect, and cancel resting orders
Liquidity	`/provide`	Quote multiple markets with a Virtual Liquidity batch
Vault	`/deposit`	Approve a token and deposit it into the Sera Vault
Wallet keys	`/exportkey`, `/importkey`	Export or import a private key through the guarded Privy flow
Settings	`/network`, `/language`	Switch between Mainnet/Sepolia and English/Japanese
AI	Free-form text	Ask the Mastra agent for an explanation or to prepare an action

/swap returns the output to the user's own wallet. /send uses the same swap flow but changes recipient to another address. This makes a request such as “convert 100 USDC to EURC and send it to this address” one signed Sera Intent.

Testnet warning: Sepolia liquidity can be thin. A NO_LIQUIDITY response does not necessarily indicate a bot failure. Use /liquidity to discover executable pairs, or test the /deposit → /order flow instead.

Technology stack

Layer	Technology	Role
Runtime	Bun + TypeScript	Bot, API server, and tests
Telegram	grammY 1.44	Commands, sessions, and inline keyboards
HTTP API	Hono 4.12 + Zod OpenAPI	Webhook, health endpoint, and Swagger UI
Trading	Sera REST API v2	Rates, swaps, orders, Vault, and Virtual Liquidity
Wallet	Privy Node SDK 0.25	Ethereum wallets, EIP-712 signatures, and transaction signing
Web3	viem 2.55	Addresses, typed data, and unit conversion
AI agent	Mastra 1.x + Claude	Natural-language interpretation and read/prepare tools
Database	LibSQL / Turso	Users, API keys, orders, pending actions, and agent memory
Validation	Zod 4	Environment and API response validation
Quality	Bun Test, TypeScript, Biome	Tests, type checking, and linting
Deployment	Docker + Cloud Run	Polling locally and webhook mode in production

The bot is built with grammY and runs a Hono HTTP server in the same process. Local development uses Telegram polling, while Cloud Run uses webhooks.

The HTTP server also exposes read-only public endpoints and Swagger UI. User-specific data and every fund-moving operation remain inside the Telegram flow.

Architecture

The main data flow looks like this:

Telegram user
    |
    v
grammY Bot ---------------------> Mastra Agent
    |                                  |
    v                                  v
Command / Flow Layer             Read / Prepare Tools
    |                                  |
    +---------------+------------------+
                    v
               Service Layer
              /      |       \
             v       v        v
     Sera REST API  Privy   LibSQL / Turso
                    |
                    v
              EIP-712 / Tx signing

Command handlers and Mastra tools call the same service layer. Rate lookup, swap preparation, order management, deposits, and liquidity logic all live there.

The critical property is what the diagram does not contain: there is no direct route from the Mastra agent to PrivySigner.

The AI can read data and create a pending action. Signing only becomes reachable when the user taps Confirm on a Telegram confirmation card.

How the bot uses Sera REST API v2

My earlier Sera examples used the GraphQL subgraph and the v1 Router, OrderBook, and PriceBook contracts.

This bot uses a different integration surface: Sera REST API v2. In v2, users sign an EIP-712 Order or Intent, matching happens offchain, and settlement uses the onchain Vault and Sera contracts.

For a new application, the REST API removes a large amount of integration work by constructing order typed data, routing swaps, and building transactions.

Main endpoints

Purpose	Endpoint
System	`GET /health`, `/system/time`, `/config`
Currencies and markets	`GET /tokens`, `/markets`, `/fx/rate`
API keys	`POST /api-keys`
Swaps	`POST /swap/quote`, `/swap`
Limit orders	`POST /orders/preview`, `/orders`, `/orders/cancel`
Order status	`GET /orders/{order_id}`
Virtual Liquidity	`POST /orders/vl/batch`, `/orders/vl/cancel`
Balances	`GET /balances`
Vault deposits	`POST /approve`, `/deposit`, `/tx/send`

A typed API client

All Sera access goes through SeraClient. Its shared request method handles API-key authentication, rate-limit retries, JSON parsing, and Zod response validation.

// src/sera/client.ts
private async request<T>(
  path: string,
  schema: z.ZodType<T>,
  opts: RequestOptions = {},
): Promise<T> {
  const url = new URL(this.baseUrl + path);
  for (const [key, value] of Object.entries(opts.query ?? {})) {
    if (value !== undefined) url.searchParams.set(key, String(value));
  }

  const headers: Record<string, string> = { accept: "application/json" };
  if (opts.body !== undefined) headers["content-type"] = "application/json";
  if (opts.auth) {
    if (!this.apiKey) throw new Error("API key not configured");
    headers.authorization = `Bearer ${this.apiKey.key}:${this.apiKey.secret}`;
  }

  let res: Response;
  for (let attempt = 0; ; attempt++) {
    res = await this.fetchImpl(url, {
      method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
      headers,
      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
    });
    if (res.status !== 429 || attempt >= 2) break;

    const retryAfter = Number(res.headers.get("retry-after"));
    const waitSec = Number.isFinite(retryAfter) ? retryAfter : 1;
    await new Promise((resolve) => setTimeout(resolve, waitSec * 1000 + 100));
  }

  const text = await res.text();
  const json = text ? JSON.parse(text) : {};
  if (!res.ok) {
    throw new SeraApiError(res.status, extractErrorCode(json), text, path);
  }

  const parsed = schema.safeParse(json);
  if (!parsed.success) {
    throw new SeraApiError(
      res.status,
      "SCHEMA_MISMATCH",
      parsed.error.message,
      path,
    );
  }
  return parsed.data;
}

GET /config is cached for ten minutes. Chain IDs, contract addresses, and the EIP-712 domain are not hardcoded because they can differ by network and deployment.

Address casing is another subtle integration detail:

// src/sera/client.ts
async getBalances(ownerAddress: string): Promise<SeraBalanceRow[]> {
  const res = await this.request("/balances", balancesResponseSchema, {
    auth: true,
    query: { owner_address: ownerAddress.toLowerCase() },
  });
  return res.balances;
}

Read endpoints expect lowercase owner_address values. Signed payloads use the values supplied by the API or a checksummed address. Do not run both through the same normalization function.

From quote to swap execution

The swap flow is the core of the bot:

User              Bot / Service            Sera / Privy
 |                      |                        |
 | /swap                |                        |
 |--------------------->| POST /swap/quote      |
 |                      |----------------------->|
 |                      | uuid + route_params    |
 |                      |<-----------------------|
 |  Quote + Confirm     |                        |
 |<---------------------|                        |
 | Confirm              |                        |
 |--------------------->| atomic consume         |
 |                      | EIP-712 sign via Privy |
 |                      |----------------------->|
 |                      | POST /swap             |
 |                      |----------------------->|
 |  Result              |                        |
 |<---------------------|                        |

Step 1: Request a quote

The bot validates the user's amount, converts it to raw units, reads Sera's server time, and calls POST /swap/quote.

// src/services/swap-service.ts
async prepareSwap(user: UserRow, input: PrepareSwapInput): Promise<SwapCard> {
  const [fromToken, toToken] = await Promise.all([
    this.rateService.findToken(user.network, input.fromSymbol),
    this.rateService.findToken(user.network, input.toSymbol),
  ]);
  if (!fromToken || !toToken) throw new Error("Unknown token");

  const check = validateAmount(input.amount, fromToken.decimals);
  if (!check.ok) throw new Error(`Invalid amount (${check.reason})`);

  const rawAmount = toRawUnits(input.amount, fromToken.decimals);
  const sera = this.publicSera(user.network);
  const serverTime = await sera.getSystemTime();
  const quote = await sera.swapQuote({
    from_token: fromToken.address,
    to_token: toToken.address,
    from_amount: rawAmount.toString(),
    owner_address: user.walletAddress,
    recipient: input.recipient ?? user.walletAddress,
    expiration: serverTime + 300,
    gas_mode: "receive_less",
  });

  return this.quoteToCard(user, quote, {
    fromSymbol: fromToken.symbol,
    toSymbol: toToken.symbol,
    fromAmount: input.amount,
    toDecimals: toToken.decimals,
    recipient: input.recipient,
  });
}

Using GET /system/time prevents local clock drift from invalidating the signature deadline.

With gas_mode: "receive_less", execution cost is reflected in the quoted output. A swap user does not need a separate ETH balance for gas. Depositing into the Vault for limit orders is a different flow and does require ETH.

No signing or asset movement happens here. The bot stores the quote's route_params, uuid, and expiration in a pending action, then sends a confirmation card.

Step 2: Sign only after confirmation

Privy is called only after the user taps Confirm.

// src/services/swap-service.ts
async executeSwap(user: UserRow, payload: SwapActionPayload) {
  const sera = this.publicSera(user.network);
  const config = await sera.getConfig();

  const signature = await this.signer.signTypedData(user.walletId, {
    domain: config.eip712_domain as Record<string, unknown>,
    types: INTENT_EIP712_TYPES,
    primaryType: "Intent",
    message: payload.routeParams,
  });

  const permitSignature = payload.permitEip712
    ? await this.signer.signTypedData(user.walletId, payload.permitEip712)
    : undefined;

  try {
    await sera.submitSwap({
      uuid: payload.uuid,
      signature,
      ...(permitSignature && payload.permitDeadline
        ? {
            permit_signature: permitSignature,
            permit_deadline: payload.permitDeadline,
          }
        : {}),
    });
    return { status: "success" as const };
  } catch (error) {
    if (error instanceof SeraApiError && error.isStaleQuote) {
      return {
        status: "requoted" as const,
        card: await this.prepareSwap(user, {
          fromSymbol: payload.fromSymbol,
          toSymbol: payload.toSymbol,
          amount: payload.fromAmount,
          recipient: payload.recipient,
        }),
      };
    }
    throw error;
  }
}

There is an important wire-format distinction here:

Signing warning: route_params from /swap/quote is the Intent message, not a complete typed-data envelope. The bot adds the domain from GET /config, plus the known Intent types and primary type. In contrast, permit.eip712 is a complete permit payload and must be signed without reconstruction.

Treating every API response as the same typed-data shape will break signatures. The implementation preserves the signature field values exactly as returned.

If the quote expires, the bot requests a new quote. It never silently executes at the new price; it sends a fresh confirmation card and asks the user to confirm again.

Why I chose Privy

Wallet connection is awkward in a chat interface. A web app can redirect to WalletConnect or a browser extension, but repeatedly switching applications makes a Telegram flow difficult to use.

The bot creates an Ethereum server wallet for each Telegram user with the Privy Node SDK:

// src/privy/signer.ts
async createWallet(telegramUserId: number): Promise<CreatedWallet> {
  const externalId = `tg-${telegramUserId}`;
  const wallet = await this.privy.wallets().create({
    chain_type: "ethereum",
    external_id: externalId,
    display_name: `Telegram user ${telegramUserId}`,
    idempotency_key: `create-${externalId}`,
    ...(this.walletAuth
      ? { owner: { public_key: this.walletAuth.publicKeySpki } }
      : {}),
  });

  return { walletId: wallet.id, address: wallet.address };
}

external_id creates a durable mapping to the Telegram user. idempotency_key prevents a double tap or retry from creating duplicate wallets.

The database stores walletId and the address. The normal trading path never retrieves or persists the private key.

EIP-712 signing is delegated to Privy:

// src/privy/signer.ts
async signTypedData(
  walletId: string,
  typedData: SeraTypedDataPayload,
): Promise<string> {
  const result = await this.privy
    .wallets()
    .ethereum()
    .signTypedData(walletId, {
      params: {
        typed_data: {
          domain: typedData.domain,
          types: typedData.types,
          primary_type: typedData.primaryType,
          message: typedData.message,
        },
      },
    });

  if (!result.signature) throw new Error("No signature returned");
  return result.signature;
}

An optional P-256 authorization key can be configured as the wallet owner to enable /exportkey and /importkey. Those flows use Privy's high-level SDK methods and apply additional Telegram safeguards:

An exported key message is deleted after 60 seconds
An import message is deleted immediately
Private keys are never stored in the database or logs
Key transfer is disabled when the authorization key is not configured

The backend authorization key is highly sensitive. It belongs in a managed secret store, not source control or a committed .env file.

Limit orders and the Vault

Swaps can spend from the wallet directly. Limit orders first require funds in the Sera Vault.

The order flow is:

Read tick_precision and quantity_precision from GET /markets
Validate price and amount without silently rounding
Check the available Vault balance
Call POST /orders/preview to obtain the EIP-712 Order payload
Sign the API-provided typed data through Privy
Submit it to POST /orders
Persist both order_id and uuid_int

The client creates the order UUID. A retry reuses the same order_id, allowing the server to deduplicate the request. uuid_int is the uint256 value bound into the onchain signature and must match the encoding of order_id.

When the Vault balance is insufficient, /deposit executes this sequence:

POST /approve  -> unsigned approve transaction
Privy signs it
POST /tx/send  -> broadcast approve

POST /deposit  -> unsigned deposit transaction
Privy signs it
POST /tx/send  -> broadcast deposit

A swap can include gas cost in its quote and therefore does not require the user to hold ETH. Vault approve and deposit are transactions from the user's wallet and require a small amount of ETH.

Order cancellation has a cooldown. The bot stores the placement time and reports the remaining wait instead of repeatedly submitting a request that the API will reject.

Virtual Liquidity across multiple markets

/provide uses Sera v2 Virtual Liquidity.

Suppose a market maker wants to place three orders, each spending up to 1,000 USDC:

1,000 USDC -> EURC/USDC bid
1,000 USDC -> XSGD/USDC bid
1,000 USDC -> JPYC/USDC bid

Shared collateral budget: 1,000 USDC

A Virtual Liquidity batch groups 2–50 orders across distinct markets under one collateral budget. The Vault freezes the largest single leg rather than the sum. When one order consumes budget, sibling orders are automatically reduced.

Each leg shares a VL group ID and receives a distinct leg_id inside uuid_int. The preview endpoint accepts standalone encodings, so the implementation replaces only the uuid field with the VL encoding before signing. Every other API-provided EIP-712 field remains unchanged.

The pending-action security boundary

Every operation that can move funds follows one path:

Prepare action
    -> store pending action
    -> render Telegram confirmation card
    -> user taps Confirm
    -> atomically consume the one-time action
    -> Privy signs
    -> submit to Sera

A pending action stores the payload, Telegram user ID, network, expiration, and consumption timestamp.

// src/services/pending-actions.ts
async consume<T>(
  id: string,
  telegramUserId: number,
): Promise<ConsumeResult<T>> {
  const row = await this.repo.find(id);
  if (!row) return { status: "not_found" };
  if (row.telegramUserId !== telegramUserId) return { status: "wrong_user" };
  if (row.consumedAt !== null) return { status: "already_used" };
  if (row.expiresAt < Date.now()) return { status: "expired" };

  const won = await this.repo.consume(id);
  if (!won) return { status: "already_used" };

  return {
    status: "ok",
    payload: JSON.parse(row.payload) as T,
    row,
  };
}

repo.consume() updates consumed_at only when the row is still unused. Even if Telegram resends a callback or the user taps repeatedly, only the request that wins the atomic update continues.

The action ID is a short random value that fits inside Telegram's callback_data limit. The payload stays in the database rather than being embedded in the button.

Prepared --Confirm--> Executing --success--> Success
    |                     |
    |                     +--stale quote--> Requoted --> Prepared
    +--Cancel-----------> Cancelled
    +--TTL elapsed------> Expired

This boundary rejects:

An action confirmed by a different Telegram user
An expired quote
A double Confirm tap
Reuse of a cancelled action
An AI-prepared action that the user never approved

Integrating a Mastra agent without giving it a wallet

Free-form messages are sent to a Mastra agent. For example, “swap 100 USDC to EURC” causes the agent to select a tool and prepare a confirmation card.

Only these tool categories are registered:

Read: FX rate, markets, liquidity, balances, and orders
Prepare: swap, send, and limit order

The prepare tool looks like this:

// src/mastra/tools/prepare-tools.ts
export const prepareSwapTool = createTool({
  id: "prepare-swap",
  description: "Prepare a swap. The user must tap Confirm before execution.",
  inputSchema: z.object({
    fromSymbol: z.string(),
    toSymbol: z.string(),
    amount: z.string(),
  }),
  outputSchema: z.object({ result: z.string() }),
  execute: async (input, context) => {
    const resolved = await requireUser(context?.requestContext);
    if ("error" in resolved) return { result: resolved.error };

    const card = await resolved.services.swaps.prepareSwap(
      resolved.user,
      input,
    );
    getCardCollector(context?.requestContext)?.push({
      kind: "swap",
      actionId: card.actionId,
      card,
    });

    return {
      result: "Swap prepared. Ask the user to review and tap Confirm.",
    };
  },
});

The bot places the verified Telegram user ID, language, network, and wallet address into requestContext. Identity never comes from model-generated tool arguments.

Cards created by the agent use the same confirmation callback as command-driven cards. There is no special AI signing route.

The AI prepares a trade. The human approves it. Deterministic application code performs the signature and submission.

This separation preserves the convenience of natural language while reducing the chance that a model error or prompt injection becomes an unauthorized asset movement.

Without ANTHROPIC_API_KEY, free-form chat is disabled but every guided command continues to work.

Setup

Prerequisites

Git
Bun 1.x
A Telegram Bot token
A Privy App ID and App Secret
Sepolia ETH and supported test tokens when using testnet

1. Clone and install

git clone https://github.com/mashharuki/SeraProtocol-Sample.git
cd SeraProtocol-Sample/telegram-bot
bun install
cp .env.example .env

2. Configure the required environment variables

# From Telegram @BotFather
TELEGRAM_BOT_TOKEN=

# From the Privy Dashboard
PRIVY_APP_ID=
PRIVY_APP_SECRET=

DEFAULT_NETWORK=sepolia

The AI chat, persistent production database, and key import/export flows are optional:

ANTHROPIC_API_KEY=

# Local SQLite; use Turso or another persistent LibSQL service on Cloud Run
DATABASE_URL=file:./data/bot.db
DATABASE_AUTH_TOKEN=

# Generate with: bun scripts/gen-wallet-auth-key.ts
WALLET_AUTH_PRIVATE_KEY=
WALLET_AUTH_PUBLIC_KEY=

Security warning: .env contains a Telegram token, Privy secret, and potentially an authorization private key. Never commit it. Use a managed secret store in production.

3. Start the bot

bun run dev

Polling mode is the default. Open the bot in Telegram and send /start.

4. Walk through the demo

Run /start, select a language, and create a wallet
Run /wallet to inspect the address and deposit QR code
Fund the wallet with Sepolia ETH and supported test tokens
Check /balance
Inspect a currency pair with /rate
Use /swap or /order to create a confirmation card
Review the details and tap Confirm
Send a free-form message to test the agent's prepare-only flow

Start with small amounts if you switch to Mainnet.

5. Verify the project

bun run typecheck
bun test
bun run check

The test suite covers precision rules, UUID encoding, pending-action single use, stale quotes, orders, deposits, Virtual Liquidity, and wallet key import/export.

Run with Docker

docker compose up --build -d
docker compose logs -f sera-fx-bot

Local SQLite data is mounted at ./data. A file: database on Cloud Run is ephemeral, so production should use a persistent LibSQL service such as Turso.

Lessons from the implementation

Signed payloads differ by endpoint

/orders/preview returns a complete EIP-712 payload. /swap/quote returns route_params as an Intent message. Similar-looking responses are not necessarily interchangeable.

Never “clean up” EIP-712 values

Formatting an address or numeric field changes the signed message. Display formatting and signing payloads must remain separate.

Design for quote expiration

A user may leave a confirmation card open for several minutes. Requoting and asking for confirmation again creates a safer experience than either failing permanently or silently accepting a new price.

Telegram is a constrained UI

callback_data must stay short, and thousands of markets cannot fit in an inline keyboard. Guided buttons focus on major currencies, while the agent can search the wider market set.

Cloud Run scale-out needs shared session state

Orders, users, and pending actions are stored in LibSQL, but part of an in-progress guided flow is currently in memory. The deployment therefore uses max-instances=1. Multi-instance deployment would require moving session state into shared storage.

Conclusion

This project combines Sera REST API v2, Privy, grammY, and Mastra to create a Telegram interface for onchain stablecoin FX.

The main takeaways are:

Sera REST API v2 makes it possible to integrate swaps, transfers, limit orders, Vault operations, and Virtual Liquidity from TypeScript
Privy provides server-wallet creation and EIP-712 signing without putting private keys in the normal application database
A one-time confirmation action separates AI assistance from actual authorization

The goal should not be “an AI that can trade whenever it wants.” A safer division of responsibilities is:

The AI prepares. The human confirms. Trusted deterministic code signs and executes.

Check out the demo and repository if you want to experiment with the implementation:

https://github.com/mashharuki/SeraProtocol-Sample/tree/main/telegram-bot

References

What We Did to Survive and Succeed in the AWS Summit AI-DLC Hackathon

Haruki Kondo — Sun, 28 Jun 2026 14:47:54 +0000

Introduction

Hello everyone!

I recently participated in the AWS Summit Japan 2026 AI-DLC Hackathon, which was held alongside AWS Summit Japan 2026.

The theme of this hackathon was extremely challenging: build a service that “makes people useless,” while following the AI-DLC approach!

https://pages.awscloud.com/summit-japan-2026-hackathon-reg.html

It was a highly competitive event with 117 teams entering, but in the end, we were able to win 3rd place!

https://x.com/haruki_web3/status/2070433400918553035

Product GitHub Repository

https://github.com/mashharuki/AWS-SummitHackathon-2026

In this technical blog post, I would like to share the things we did to make the most of AI-DLC and maximize its benefits throughout the hackathon.

What Is AI-DLC?

Overview of AI-DLC

AI-DLC stands for AI-Driven Development Lifecycle, a new development methodology proposed by AWS for the AI era.

It is a software development approach that restructures the entire development lifecycle around a division of roles where AI executes and humans supervise.

The details are explained in the following article and GitHub repository, so I will only briefly summarize the concept here.

https://zenn.dev/aws_japan/articles/aidlc-workflows

https://github.com/awslabs/aidlc-workflows/tree/main

The AI-DLC workflow is broadly divided into three phases:

Inception phase, which covers requirements definition and design
Construction phase, which covers implementation
Operation phase, which covers operations and deployment

How Is It Different from cc-sdd?

Another well-known approach for practicing spec-driven development is cc-sdd.

https://github.com/gotalab/cc-sdd

At a high level, the overall flow of cc-sdd and AI-DLC is similar.

Both generally follow the process of requirements definition → design → implementation, with differences in the finer details.

After actually using AI-DLC extensively, I felt that AI-DLC is designed with practical enterprise use cases very much in mind.

The instructions given to AI and summaries of the outputs generated as a result are recorded in great detail in a file called audit.md.

https://github.com/mashharuki/AWS-SummitHackathon-2026/blob/main/aidlc-docs/audit.md

This makes it possible to look back later and understand who collaborated with AI, at what timing, and based on what kind of thinking during the development of the product. I found this aspect extremely compelling.

This audit.md file is something cc-sdd does not provide by default. I also felt that the volume and richness of the documents generated during the Inception phase, such as requirements and design documents, were far more comprehensive compared to cc-sdd.

https://github.com/mashharuki/AWS-SummitHackathon-2026/tree/main/aidlc-docs

Another difference is the Operation phase. AI-DLC generates documents that even cover the deployment of the product you build.

For example, when using AWS CDK, it carefully summarizes the CDK stack for the product, setup procedures, and deployment commands.

https://github.com/mashharuki/AWS-SummitHackathon-2026/blob/main/aidlc-docs/operations/deploy-e2e-verification.md

You can do something similar with cc-sdd as well, but in that case, you need to explicitly instruct the AI to do so.

What We Did in the AI-DLC Hackathon

The standard features of AI-DLC are as described above.

From here, I will summarize the specific things we did during the hackathon.

The Quality of Requirements Documents and Shared Goal Alignment Are Crucial

The first thing our team focused on was repeatedly running the Inception phase and aligning the goal image among team members.

Unlike cc-sdd, one of the strengths of AI-DLC is that it generates a rich set of documents during the requirements definition and design phase, making it easy for the team to review them together.

Before advancing to the first screening round, we repeated the process of creating, reviewing, and updating the documents more than four or five times, thoroughly improving their quality toward our final goal.

Creating Subagents and Skills for AI-DLC

To practice AI-DLC effectively, we prepared and tested subagents and Skills in advance.

https://github.com/mashharuki/AWS-SummitHackathon-2026/blob/main/.claude/agents/aidlc-specialist.md

https://github.com/mashharuki/AWS-SummitHackathon-2026/tree/main/.claude/skills/aidlc-workflow-guide

We also created a dedicated review Skill that summarized the hackathon overview and judging criteria, as well as a strategy Skill for optimizing the product specifically for the hackathon.

These helped us improve the quality of the outputs during the Inception phase.

https://github.com/mashharuki/AWS-SummitHackathon-2026/tree/main/.claude/skills/aws-summit-hackathon-reviewer

https://github.com/mashharuki/AWS-SummitHackathon-2026/tree/main/.claude/skills/hackathon-strategist

Environment Setup Matters!

The second thing we did was manually set up the development environment in advance.

Specifically, we prepared the pnpm monorepo project setup and implemented the minimum base structure for the frontend, backend, and CDK projects before running the AI-DLC implementation phase.

Environment setup places a very heavy burden on AI, so we handled that part ourselves on the human side and let the AI focus on logic design and implementation.

We also thoroughly prepared Agent Skills for the technology stack we planned to use and expanded our subagents before moving into implementation.

We kept the number of MCPs to a minimum and focused mainly on using AWS MCP Server, Serena MCP, and CodeGraph MCP.

https://github.com/mashharuki/AWS-SummitHackathon-2026/blob/main/.claude/.mcp.json

As a result, this preparation allowed us to steadily develop the product toward our goal, even under an extremely busy schedule.

Using Lean to Mathematically Ensure Program Safety

The final thing we did was incorporate a formal verification phase using Lean into AI-DLC in order to mathematically ensure the safety of the logic we planned to implement.

https://github.com/leanprover/lean4

Lean is a programming language developed for theorem proving, which is one of several approaches used to achieve formal verification.

I believe many people practice standard test-driven development together with spec-driven development, including AI-DLC.

We decided to go one step further and integrate formal verification checks into that process.

Unlike tests, formal verification proves the absence of bugs using mathematical formulas, allowing exhaustive verification. This is one of its major characteristics.

In fact, some source code auditing companies use formal verification in their work.

https://www.certik.com/

Our product was designed to handle privacy-sensitive information such as Slack chat histories, account names, and email addresses.

Because of that, we planned to implement encryption logic to protect this information.

However, there was a potential bug where the output values of the hash function used for encryption could match under certain conditions. We were able to discover this issue in advance through formal verification using Lean.

By incorporating a formal verification phase, I believe AI-DLC became an even more robust development methodology.

Of course, we also thoroughly researched formal verification and Lean in advance, and prepared subagents and Skills for them.

https://github.com/mashharuki/AWS-SummitHackathon-2026/tree/main/.agents/skills/lean-formal-verification/agents

https://github.com/mashharuki/AWS-SummitHackathon-2026/blob/main/.agents/skills/lean-formal-verification/SKILL.md

Conclusion

That concludes my summary of what we did to survive and succeed in the AI-DLC hackathon.

There are many different approaches for achieving goals with AI, such as cc-sdd, plan mode, and the /goal command. Among them, I feel that AI-DLC was proposed especially with practical enterprise use in mind.

After using it extensively in this hackathon, I would like to actively consider applying it in real-world development projects as well.

Final Thoughts

I am truly grateful to my teammates who fought alongside me, Katryo-san for mentoring us, and everyone from the hackathon organizing team.

I sincerely appreciate the opportunity to pitch on such a major stage as AWS Summit Japan and to stand on stage as a finalist.

I will continue taking on new challenges together with AI-DLC!

Monetizing AI Agents with x402, CloudFront, and Lambda@Edge

Haruki Kondo — Mon, 11 May 2026 14:45:39 +0000

Introduction

Recently, have you been hearing the term x402 more often?

As payments between AI Agents become a reality, x402 is attracting attention as a micropayment method.

While there are several ways to "x402-ify" existing APIs, AWS has come up with a very cool architectural proposal. This time, I've used it to create an AI Agent with a chat UI!

AWS Builder Center

Connect with builders who understand your journey. Share solutions, influence AWS product development, and access useful content that accelerates your growth. Your community starts here.

builder.aws.com

I've also explained the tech stack, so please read until the end!

What I Built

Overview

This is a sample implementation that monetizes HTTP requests with micropayments using AWS CloudFront + Lambda@Edge and the x402 protocol.

Specifically, it's an app that integrates Strands Agent × AgentCore Gateway (MCP), where an AI agent autonomously pays in USDC while fetching content!

It supports both Base Sepolia (EVM) and Solana Devnet, and clients can pay on either network.

Slide Summary of the App

If you want to know just the main points, please see the slides below!

Building AI Agents on Solana〜Mastra Framework を活用した次世代エージェント開発〜 - Speaker Deck

Solana Bootcamp 2026 day3 にて登壇した際の資料になります。自分のセクションではSolana上で動くAI Agentの実装方法と選定技術スタックについてお話しさせていただきました。 Solana Bootcamp 2026 day3のイベントページ https:/…

speakerdeck.com

Screenshots

The Big Picture

The app I created is composed of 5 layers as follows:

┌──────────────────────────────────────────────────────────────────┐
│  [FrontendStack]  CloudFront (S3)                                │
│  React "Neon Noir Payment Terminal" UI                           │
│  ・Left pane: AI Chat  ・Right pane: Payment Ledger               │
└────────────────────────┬─────────────────────────────────────────┘
                         │ POST /invoke
┌────────────────────────▼─────────────────────────────────────────┐
│  [StrandsAgentStack]  API GW → Strands Agent Lambda (Python)     │
│  ・Interpret user natural language with Bedrock claude-3-5-sonnet │
│  ・Call MCP tools to fetch content                                 │
└────────────────────────┬─────────────────────────────────────────┘
                         │ MCP protocol (HTTP/Streamable)
                         │ AWS IAM Authentication
┌────────────────────────▼─────────────────────────────────────────┐
│  [AgentCoreGatewayStack]  AgentCore Gateway (MCP Server)         │
│  ・Expose Payment Proxy API as MCP tools                          │
│  ・getHelloContent / getPremiumData / getArticleContent          │
└────────────────────────┬─────────────────────────────────────────┘
                         │ HTTP call
┌────────────────────────▼─────────────────────────────────────────┐
│  [PaymentProxyStack]  API GW → Payment Proxy Lambda (TypeScript) │
│  ・Internally handle x402 flow (Recv 402 → Sign with @x402/fetch  │
│    → Retry)                                                      │
│  ・Fetch EVM private key from SecretsManager                     │
└────────────────────────┬─────────────────────────────────────────┘
                         │ HTTPS + X-Payment-Token header
┌────────────────────────▼─────────────────────────────────────────┐
│  [CdkStack]  CloudFront → Lambda@Edge → API GW → Lambda          │
│  ・origin-request: Token verification / Return 402               │
│  ・origin-response: Payment settlement (Only on origin success)  │
└──────────────────────────────────────────────────────────────────┘

The responsibilities of each stack are as follows:

Stack	File	Role
`SecretsStack`	`lib/secrets-stack.ts`	Manage EVM / Solana private keys in SecretsManager
`CdkStack`	`lib/cdk-stack.ts`	CloudFront + Lambda@Edge (x402 Edge Gateway)
`PaymentProxyStack`	`lib/payment-proxy-stack.ts`	x402 Auto-payment Proxy Lambda + API GW
`AgentCoreGatewayStack`	`lib/agent-core-gateway-stack.ts`	AgentCore Gateway (MCP Server)
`StrandsAgentStack`	`lib/strands-agent-stack.ts`	Strands Agent Lambda (Python) + API GW
`FrontendStack`	`lib/frontend-stack.ts`	CloudFront + S3 delivery of React UI

Sequence Diagrams for Each Feature

1. x402 Basic Flow — Unpaid → 402

2. x402 Basic Flow — Paid → Success

3. AI Agent Flow — End-to-End

4. On Origin Error (No Charge)

System Architecture Diagram

Key Implementation Points

Two Lambda Functions to x402-ify Any Origin

lambda-edge

The lambda@Edge function is the key component here.

lambda-edge functions on GitHub

It stands between the origin and the client, handling all x402-related logic.
In this case, we've set how much stablecoin payment to request for each path accessed on the origin.

// cdk/functions/lambda-edge/config.ts
import type { RoutesConfig } from "@x402/core/server";

// Replaced at build time via esbuild
declare const __PAY_TO_ADDRESS__: string;
declare const __SVM_PAY_TO_ADDRESS__: string;
declare const __X402_NETWORK__: string;
declare const __SOLANA_NETWORK__: string;
declare const __FACILITATOR_URL__: string;

export const FACILITATOR_URL: string = __FACILITATOR_URL__;
export const PAY_TO: string = __PAY_TO_ADDRESS__;
export const SVM_PAY_TO: string = __SVM_PAY_TO_ADDRESS__;
export const NETWORK: string = __X402_NETWORK__;
export const SOLANA_NETWORK: string = __SOLANA_NETWORK__;

// Route configuration — which paths require payment and at what price.
export const ROUTES: RoutesConfig = {
    "/api/*": {
        accepts: [
            { scheme: "exact", network: NETWORK, payTo: PAY_TO, price: "$0.001" },
            { scheme: "exact", network: SOLANA_NETWORK, payTo: SVM_PAY_TO, price: "$0.001" },
        ],
        description: "API access ($0.001 USDC)",
    },
    "/api/premium/**": {
        accepts: [
            { scheme: "exact", network: NETWORK, payTo: PAY_TO, price: "$0.01" },
            { scheme: "exact", network: SOLANA_NETWORK, payTo: SVM_PAY_TO, price: "$0.01" },
        ],
        description: "Premium API access ($0.01 USDC)",
    },
    "/content/**": {
        accepts: [
            { scheme: "exact", network: NETWORK, payTo: PAY_TO, price: "$0.005" },
            { scheme: "exact", network: SOLANA_NETWORK, payTo: SVM_PAY_TO, price: "$0.005" },
        ],
        description: "Premium content ($0.005 USDC)",
    },
};

By handling x402 requests/responses here, the origin side doesn't need to be aware of x402 at all.

payment-proxy

This is the Lambda function for the x402 automatic payment proxy.

// cdk/functions/payment-proxy/index.ts
import { GetSecretValueCommand, SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { x402Client } from "@x402/core/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
import bs58 from "bs58";

const CLOUDFRONT_URL = process.env.CLOUDFRONT_URL!;
const SVM_SECRET_ARN = process.env.SVM_PRIVATE_KEY_SECRET_ARN!;

const ROUTE_MAP: Record<string, string> = {
    "/proxy/hello": "/api/hello",
    "/proxy/premium": "/api/premium/data",
    "/proxy/article": "/content/article",
};

let payFetch: typeof fetch | null = null;

async function getPayFetch(): Promise<typeof fetch> {
    if (payFetch) return payFetch;
    const sm = new SecretsManagerClient({});
    const svmSecret = await sm.send(new GetSecretValueCommand({ SecretId: SVM_SECRET_ARN }));

    if (!svmSecret.SecretString) throw new Error("Solana private key secret is empty");

    const svmSigner = await createKeyPairSignerFromBytes(bs58.decode(svmSecret.SecretString));
    const client = new x402Client();
    client.register("solana:*", new ExactSvmScheme(svmSigner));

    payFetch = wrapFetchWithPayment(fetch, client);
    return payFetch;
}

export const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
    const proxyPath = event.path;
    const targetPath = ROUTE_MAP[proxyPath];

    if (!targetPath) {
        return {
            statusCode: 404,
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ error: `Unknown proxy path: ${proxyPath}` }),
        };
    }

    try {
        const fetchFn = await getPayFetch();
        const res = await fetchFn(`${CLOUDFRONT_URL}${targetPath}`);
        const body = await res.text();
        return {
            statusCode: res.status,
            headers: { "Content-Type": "application/json" },
            body,
        };
    } catch (err) {
        console.error("Payment proxy request failed:", err);
        return {
            statusCode: 500,
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ error: String(err) }),
        };
    }
};

MCP Server

In AgentCore Gateway, you can "MCP-ify" your APIs.
What you need for that is an OpenAPI specification (YAML).

We'll turn the above proxy server into an MCP server.

# cdk/mcp/openapi.yaml
openapi: "3.0.1"
info:
  title: "x402 Payment Proxy API"
  version: "1.0.0"
  description: "MCP tools for accessing x402-protected content via auto-payment proxy"
paths:
  /proxy/hello:
    get:
      operationId: "getHelloContent"
      summary: "Get hello content"
      description: "Get hello content (costs $0.001 USDC on Base Sepolia). Payment is handled automatically."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
  /proxy/premium:
    get:
      operationId: "getPremiumData"
      summary: "Get premium analytics data"
      description: "Get premium analytics data (costs $0.01 USDC on Base Sepolia). Payment is handled automatically."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
  /proxy/article:
    get:
      operationId: "getArticleContent"
      summary: "Get article content"
      description: "Get article content (costs $0.005 USDC on Base Sepolia). Payment is handled automatically."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object

AI Agent Implemented with Strands Agent

This part handles the implementation of the AI Agent that accesses x402-supported content via MCP.
It's implemented using Python and the Strands Agent SDK, with Bedrock AgentCore as the execution environment.

# strands_agent/lambda_function.py
import json
import os
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
from strands import Agent
from strands.models import BedrockModel
from strands.tools.mcp import MCPClient

GATEWAY_MCP_URL = os.environ["AGENT_CORE_GATEWAY_MCP_URL"]
AWS_REGION = os.environ.get("AWS_REGION", "us-east-1")

model = BedrockModel(
    model_id="us.anthropic.claude-3-5-sonnet-20240620-v1:0",
    region_name=AWS_REGION,
)

mcp_client = MCPClient(
    lambda: aws_iam_streamablehttp_client(
        endpoint=GATEWAY_MCP_URL,
        aws_region=AWS_REGION,
        aws_service="bedrock-agentcore",
    )
)

agent = Agent(
    model=model,
    tools=[mcp_client],
    system_prompt="""
        You are an AI assistant that can access x402-protected premium content.
        ... (omitted for brevity) ...
    """,
)

def handler(event, context):
    # ... (omitted for brevity) ...
    try:
        response = agent(user_message)
        return {
            "statusCode": 200,
            "headers": CORS_HEADERS,
            "body": json.dumps({"session_id": session_id, "response": str(response)}),
        }
    except Exception as e:
        return {"statusCode": 500, "headers": CORS_HEADERS, "body": json.dumps({"error": str(e)})}

Frontend

The frontend is implemented with React.js and Vite.
The AI Agent functionality is implemented as a React Hook to be called as an API.

// frontend/src/hooks/useAgent.ts
import { useCallback, useRef, useState } from "react";
import { loadConfig } from "../lib/config";
import type { Message, PaymentRecord } from "../types";

export function useAgent() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [payments, setPayments] = useState<PaymentRecord[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const sessionId = useRef(crypto.randomUUID());

  const sendMessage = useCallback(async (text: string) => {
    const config = await loadConfig();
    // ... (omitted for brevity) ...
    try {
      const res = await fetch(`${config.strandsAgentApiUrl}/invoke`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ message: text, session_id: sessionId.current }),
      });
      const data = await res.json();
      // ... (omitted for brevity) ...
    } catch (err) {
      // ...
    } finally {
      setIsLoading(false);
    }
  }, []);

  return { messages, payments, isLoading, sendMessage };
}

How to Run

Phase A: Deploy Existing x402 Edge Gateway

Clone the Repo:

git clone https://github.com/mashharuki/x402-Cloudfront-LambdaEdge-Sample.git
cd x402-Cloudfront-LambdaEdge-Sample

Install Dependencies:

cd cdk && bun install
bun install --cwd functions/lambda-edge

Batch Deploy All Stacks:

bunx cdk deploy SecretsStack
# Set private keys in SecretsManager...
PAY_TO_ADDRESS=0xYourEVMAddress SVM_PAY_TO_ADDRESS=YourSolanaAddress npx cdk deploy CdkStack PaymentProxyStack AgentCoreGatewayStack StrandsAgentStack

Cleanup

Don't forget to delete resources after verification!

npx cdk destroy --all

Note: Lambda@Edge functions may need to be deleted manually after a few hours once replicas are gone.

Summary

I've tried a way to "x402-ify" any origin using CloudFront + Lambda@Edge!

The architecture is very cool because it fully utilizes managed services while requiring almost no changes to the origin-side code where the core logic resides.

While steps like blockchain knowledge, wallets, and stablecoin preparation are still necessary, it would be even more powerful if environment setup was also covered.

I expect this kind of implementation to increase in the future.

Thank you for reading!

References

Building a Solana AI Agent with AWS, Mastra, and Phantom Wallet

Haruki Kondo — Mon, 11 May 2026 14:37:45 +0000

Introduction

Hello everyone! Are you building AI Agents?

I'm sure many of you are creating various workflows to improve business efficiency.

While know-how and sample code for AI Agents are increasing, implementation examples of AI Agents that can interact with the blockchain are still relatively few, don't you think?

In this article, I've explained the construction method and technical stack of an AI Agent that operates digital assets on the Solana blockchain!

I hope you find this useful as an example!

What I Built

Overview

I created a chat application where you can perform operations on Solana DevNet (SOL transfer, NFT minting, DeFi Swap, smart contract calls) using natural language!

When a user enters natural language in the chat screen, the backend Mastra AI Agent interprets the intent and calls the appropriate Solana tool (transferSolTool / mintNftTool / jupiterSwapTool, etc.). Instead of a signed transaction, it returns an unsigned serialized transaction to the frontend. The user confirms, signs, and sends it using their Phantom Wallet, then passes the result back to the Agent to receive an explanation of the execution result.

Demo Video

Here's how the app I created works!

Feature List

#	Feature Name	Description	Agent Tool	Signature
1	SOL Balance Inquiry	Fetches and displays the SOL balance of a wallet address	`getBalanceTool`	Not required
2	SOL Transfer	Constructs a SOL transfer transaction to a specified address	`transferSolTool`	Signed with Phantom
3	NFT List Acquisition	Fetches NFTs owned by the wallet using Metaplex DAS API	`getNftsTool`	Not required
4	NFT Minting	Constructs an NFT minting transaction using Metaplex MPL Core	`mintNftTool`	Signed with Phantom
5	Token Swap	Constructs an SPL token swap TX via Jupiter v6	`jupiterSwapTool`	Signed with Phantom
6	DevNet Airdrop	Airdrops SOL on DevNet only (Max 2 SOL / request)	`airdropTool`	Not required
7	Smart Contract Call	Constructs a general Solana Program call TX	`callProgramTool`	Signed with Phantom
8	Wallet Connection	Connecting/disconnecting Phantom Wallet and network confirmation	wallet-adapter	—
9	TX Result Explanation	Explains success/failure after signing and sending in an easy-to-understand way	Agent Follow-up	—
10	Asset Panel	SOL balance and owned NFTs are constantly displayed in the side panel	hooks (UI)	—

Sequence Diagrams for Each Feature

1. SOL Balance Inquiry

2. SOL Transfer

3. NFT List Acquisition

4. NFT Minting

5. Token Swap (Jupiter v6)

6. DevNet Airdrop

System Architecture

This app is composed of three major layers:

Frontend Layer
AI Agent Layer
Storage Layer

The system configuration on the AWS side is as follows:

It's a serverless + fully managed configuration!

The list of services used and their purposes are as follows:

AWS Service	CDK Stack	Purpose
Amazon API Gateway (HTTP API v2)	BackendStack	Request routing to Mastra Agent, CORS settings
AWS Lambda (Container Image)	BackendStack	Mastra AI Agent runtime (Docker-based)
Amazon ECR	BackendStack	Registry for Lambda Docker container images
Amazon S3	FrontendStack	Static hosting of React SPA build artifacts
Amazon CloudFront	FrontendStack	CDN delivery, reverse proxy for `/chat/*` path to API Gateway
Amazon DynamoDB	StorageStack	Persistence of Agent memory/session history (with TTL)
AWS Secrets Manager	StorageStack	Secure management of LLM API keys/Solana RPC keys
Amazon EventBridge	BackendStack	Scheduled execution, asynchronous event routing
Amazon CloudWatch Logs	BackendStack	Collection and storage of Lambda logs
AWS IAM	All Stacks	Lambda execution roles, Bedrock calling permissions
Amazon Bedrock	AgentRuntime construct	Auxiliary LLM (via Anthropic Claude Haiku, for future expansion)
AWS CDK	—	Manage all AWS resources with TypeScript IaC

Key Implementation Points

I'll pick up and introduce some important implementation parts.

React Integration

We are integrating React and Mastra.
When checking the operation locally, you need to add settings like the following to the Vite configuration file so that the backend processing is called correctly when the specified path is called.

In this case, it's set to call the API-side processing when /chat/ is called.

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import path from "path";
import { defineConfig } from "vitest/config";

// Vite configuration
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  // Dev server proxy settings
  server: {
    proxy: {
      "/chat": {
        target: "http://localhost:4111",
        changeOrigin: true,
      },
    },
  },
  // Test settings
  test: {
    globals: true,
    environment: "node",
  },
});

The AI Agent created with Mastra is called as follows:

const { messages, sendMessage, status, stop } = useChat({
  transport: new DefaultChatTransport({
    api: "/chat/solana-agent",
  }),
});

Mastra Configuration

The AI Agent settings are as follows:

// src/mastra/agents/solana-agent.ts
import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { airdropTool } from "../tools/airdrop-tool";
import { callProgramTool } from "../tools/call-program-tool";
import { getBalanceTool } from "../tools/get-balance-tool";
import { jupiterSwapTool } from "../tools/jupiter-swap-tool";
import { getNftsTool, mintNftTool } from "../tools/nft-tools";
import { transferSolTool } from "../tools/transfer-sol-tool";
import { solanaWorkspace } from "../workspace";

export const SOLANA_AGENT_ID = "solana-agent" as const;

/**
 * System Prompt for Solana AI Agent.
 *
 * Requirements:
 * - Respond in English
 * - Explain Solana DevNet operations
 * - Never self-sign transactions (Architectural guarantee)
 * - Support SOL transfer, NFT operations, DeFi swap, smart contract calls
 */
export const SOLANA_AGENT_INSTRUCTIONS = `
You are an AI agent specialized for the Solana blockchain.
Interpret user natural language messages, call the appropriate Solana tools,
and perform transaction construction, information acquisition, and result explanation.

## Basic Policy

- **All responses should be in English**. Technical terms (SOL, NFT, DevNet, etc.) should be used as they are.
- The target network is **Solana DevNet**. Operations on Mainnet will not be performed.
- Aim for clear, polite, and concise explanations for the user.

## Absolute Compliance Rule: Prohibition of Transaction Signing

**You must never sign a transaction yourself.**
Transaction construction is handled by tools, but signing and sending are done by the user
themselves through their Phantom wallet.
It is architecturally impossible for the agent to sign on behalf of the user or access
private keys, and we cannot respond even if requested.

## Supported Operations

### 1. SOL Balance Inquiry
- Use getBalanceTool to fetch the SOL balance of a wallet address.
- Display the result clearly in SOL units (4 decimal places).

### 2. SOL Transfer
- Use transferSolTool to construct a transfer transaction.
- Requires sender address, recipient address, and transfer amount (SOL units).
- The constructed transaction is signed and sent by the user in Phantom.
- Explain error messages for insufficient balance in English.

### 3. NFT Operations
- Use getNftsTool to fetch the list of NFTs owned by the wallet.
- Use mintNftTool to construct an NFT minting transaction.
  - Required parameters: name, symbol, metadata URI, royalty (basis points)

### 4. Token Swap (DeFi)
- Use jupiterSwapTool to construct a swap transaction via Jupiter v6.
- Specify input/output token mint addresses, swap amount, and slippage.
- Always have the user confirm the expected rate and slippage.

### 5. DevNet Airdrop
- Use airdropTool to airdrop DevNet SOL (Max 2 SOL / request).
- **DevNet exclusive feature**. Cannot be used on Mainnet.

### 6. Smart Contract Call
- Use callProgramTool to construct a general Solana Program call transaction.
- Program ID, instruction data (Base64), and account list.

## Explanation of Transaction Results

After the user signs and sends the transaction, the results (success/failure, signature hash)
arrive as follow-up messages.
- Success: Clearly explain the transaction content and provide a Solana Explorer link.
- Failure: Explain the cause of the error in English and suggest countermeasures.

## Error Handling

- Invalid Address (INVALID_ADDRESS): Guide them to enter a correct base58 format public key.
- Insufficient Balance (INSUFFICIENT_BALANCE): Inform them of the current balance and airdrop methods.
- RPC Error (RPC_ERROR): Prompt them to retry as a network issue.
- Rate Limited (RATE_LIMITED): Guide them to wait a while before retrying.
`.trim();

/**
 * AI Agent exclusive for Solana DevNet.
 */
export const solanaAgent = new Agent({
  id: SOLANA_AGENT_ID,
  name: "Solana AI Agent",
  instructions: SOLANA_AGENT_INSTRUCTIONS,
  model: "google/gemini-1.5-flash",
  tools: {
    getBalanceTool,
    transferSolTool,
    getNftsTool,
    mintNftTool,
    jupiterSwapTool,
    airdropTool,
    callProgramTool,
  },
  memory: new Memory(),
  workspace: solanaWorkspace,
});

Since this is a Solana AI Agent, I've also configured an additional Agent SKILL (solanaWorkspace).
This allows the agent to refer to SKILL.md files in a specific folder to gain specialized knowledge.

// src/mastra/workspace.ts
import { LocalSkillSource, Workspace } from "@mastra/core/workspace";

/**
 * Workspace for Solana AI Agent.
 * Reads domain knowledge from SKILL.md files under src/mastra/skills/
 * to ensure the agent accurately understands Solana concepts, tools, and error codes.
 */
export const solanaWorkspace = new Workspace({
  name: "Solana AI Agent Workspace",
  skills: ["src/mastra/skills"],
  skillSource: new LocalSkillSource({ basePath: process.cwd() }),
});

Various Tools for On-Chain Operations

We've implemented a group of tools for on-chain operations.
Here's an explanation of the balance acquisition and transaction creation tools.

Balance Inquiry Tool

For balance inquiry, it basically calls the Solana RPC API to fetch and return the balance of the wallet address passed from the prompt.

// src/mastra/tools/get-balance-tool.ts
import { createTool } from "@mastra/core/tools";
import { Connection, PublicKey } from "@solana/web3.js";
import {
  GetBalanceInputSchema,
  GetBalanceOutputSchema,
  type GetBalanceOutput,
} from "../../types/solana";

const LAMPORTS_PER_SOL = 1_000_000_000;

export async function executeGetBalance(
  address: string,
  getBalanceFn: (address: string) => Promise<number>,
): Promise<GetBalanceOutput> {
  const lamports = await getBalanceFn(address);
  return {
    address,
    lamports,
    sol: lamports / LAMPORTS_PER_SOL,
    network: "devnet",
  };
}

/**
 * SOL balance inquiry tool for Solana DevNet.
 */
export const getBalanceTool = createTool({
  id: "get-balance",
  description: `Fetches the SOL balance of a Solana DevNet wallet address.
Input: address — base58 Solana public key (wallet address)
Output: Balance in lamports and sol, and target network (devnet)
Note: This tool is exclusive to Solana DevNet.`,

  inputSchema: GetBalanceInputSchema,
  outputSchema: GetBalanceOutputSchema,

  execute: async ({ address }) => {
    const rpcUrl =
      process.env.SOLANA_RPC_URL ?? "https://api.devnet.solana.com";
    const connection = new Connection(rpcUrl, "confirmed");

    let publicKey: PublicKey;
    try {
      publicKey = new PublicKey(address);
    } catch {
      throw new Error(
        `Invalid address format: "${address}". Please specify a base58 Solana public key.`,
      );
    }

    return executeGetBalance(address, () => connection.getBalance(publicKey));
  },
});

Transaction Creation Tool

The key part is this transaction creation tool!
To ensure safety, the AI Agent side does not perform electronic signatures; it only handles transaction creation.
The transaction is sent to the blockchain only when the user signs it of their own will.

// src/mastra/tools/transfer-sol-tool.ts
import { createTool } from "@mastra/core/tools";
import {
  Connection,
  PublicKey,
  SystemProgram,
  Transaction,
} from "@solana/web3.js";
import {
  SolanaTxRequestSchema,
  TransferSolInputSchema,
  type SolanaTxRequest,
} from "../../types/solana";

const LAMPORTS_PER_SOL = 1_000_000_000;

interface TransferDeps {
  getBalanceFn: (address: string) => Promise<number>;
  getRecentBlockhashFn: () => Promise<string>;
}

export async function buildTransferTransaction(
  fromAddress: string,
  toAddress: string,
  amountSol: number,
  deps: TransferDeps,
): Promise<SolanaTxRequest> {
  const lamports = Math.round(amountSol * LAMPORTS_PER_SOL);

  const balance = await deps.getBalanceFn(fromAddress);
  if (balance < lamports) {
    const currentSol = (balance / LAMPORTS_PER_SOL).toFixed(4);
    throw new Error(
      `INSUFFICIENT_BALANCE: Insufficient balance. Current balance: ${currentSol} SOL, required: ${amountSol} SOL`,
    );
  }

  const fromPubkey = new PublicKey(fromAddress);
  const toPubkey = new PublicKey(toAddress);
  const blockhash = await deps.getRecentBlockhashFn();

  const transaction = new Transaction();
  transaction.add(SystemProgram.transfer({ fromPubkey, toPubkey, lamports }));
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = fromPubkey;

  const serializedTx = transaction
    .serialize({ requireAllSignatures: false })
    .toString("base64");

  const toShort = `${toAddress.slice(0, 4)}...${toAddress.slice(-4)}`;
  const description = `Transfer ${amountSol} SOL to ${toShort}`;

  return {
    type: "solana_tx_request",
    serializedTx,
    description,
    txType: "transfer",
  };
}

/**
 * SOL transfer transaction construction tool.
 */
export const transferSolTool = createTool({
  id: "transfer-sol",
  description: `Constructs a SOL transfer transaction (signing is done in user's Phantom wallet).
Input:
  - fromAddress: Sender wallet address (base58)
  - toAddress: Recipient wallet address (base58)
  - amountSol: Transfer amount (SOL units)
Output: SolanaTxRequest signable in Phantom (serialized transaction)`,

  inputSchema: TransferSolInputSchema,
  outputSchema: SolanaTxRequestSchema,

  execute: async ({ fromAddress, toAddress, amountSol }) => {
    const rpcUrl =
      process.env.SOLANA_RPC_URL ?? "https://api.devnet.solana.com";
    const connection = new Connection(rpcUrl, "confirmed");

    try {
      new PublicKey(fromAddress);
      new PublicKey(toAddress);
    } catch {
      throw new Error(
        "Invalid address format. Please specify a base58 Solana public key.",
      );
    }

    return buildTransferTransaction(fromAddress, toAddress, amountSol, {
      getBalanceFn: (addr) => connection.getBalance(new PublicKey(addr)),
      getRecentBlockhashFn: async () => {
        const { blockhash } = await connection.getLatestBlockhash("confirmed");
        return blockhash;
      },
    });
  },
});

Solana Dev Agent SKILL

In implementing this AI Agent, the following Agent SKILL was very helpful.

Solana Dev Skill GitHub

Why not try using it when you develop apps on Solana?
There's also Deepwiki: Solana Dev Skill on Deepwiki

You can install it with:

npx skills add https://github.com/solana-foundation/solana-dev-skill

How to Run

Let's share how to run this AI Agent!

Prerequisites

Bun v1.x
Node.js v23+
Phantom Wallet browser extension installed
Google Gemini API key issued

Setup

# Clone the repository
git clone https://github.com/your-org/solana-agent-repo.git
cd solana-agent-repo/mastra-react

# Install dependencies
bun install

# Configure environment variables
cp .env.example .env
# Edit .env and set GOOGLE_GENERATIVE_AI_API_KEY etc.

Start Development Server

# Terminal 1: Frontend (localhost:5173)
bun run dev

# Terminal 2: Mastra Backend (localhost:4111)
bun run dev:mastra

Local setup is complete! Try asking for your balance by passing your wallet address.

Deploy Resources to AWS

Next, I'll explain the steps to deploy to AWS.

Must be executed under the cdk folder.

Since we're using CDK, deployment is completed with a single command!

# Install dependencies first
bun install
# Deploy
bun run deploy '*'

Once deployment is successful, all three layers mentioned above will be expanded. The app works exactly the same as locally!

Cleanup Resources on AWS

Don't forget to delete resources after verification!

bun run destroy '*' --force

Summary

That's all for now!
This was an explanation of implementing a Solana AI Agent using a modern tech stack. I'll continue to add interesting features as this can be expanded upon!

Thank you for reading!

References

Mathematically Prohibiting 'Cheating' in On-Chain RPS: A Midnight ZK dApp Case Study

Haruki Kondo — Sun, 03 May 2026 23:31:12 +0000

Introduction

Implementing Rock-Paper-Scissors (RPS) on-chain is surprisingly tricky.

The moment you choose "Rock" and send a transaction, your opponent can read your move from the public ledger. The game is over before it even starts.

I tried implementing a commit-reveal pattern manually, but managing salts, preventing front-running, and ensuring fair judging logic... it quickly became a rabbit hole.

That's when I turned to Midnight. I built a full-stack RPS dApp where "cheating" (looking at the opponent's move before playing) is mathematically impossible!

In this article, I'll share the ZK circuit design using Midnight's smart contract language, Compact, and the hurdles I faced during development.

Note
What ZK protects: The ZK proof ensures "confidentiality of the move during the commit phase" (fairness). After the reveal, both moves are recorded on the public ledger.

Here is what the dApp looks like:

What You'll Learn

Designing the "Hidden" vs. "Visible" split in Midnight.
Mastering the commit-reveal pattern with the Compact language.
Frontend UX strategies for handling ZK proof generation time (the 10-second hurdle).
Robust provider configuration with the Midnight JS SDK.

Repository

You can find the full source code here:

mashharuki / midnight-rps-sample-app

Midnight RPS sample dApp

midnight-rps-sample-app

Midnight RPS sample dApp

Overview

midnight-rps-sample-app is a sample Rock-Paper-Scissors dApp project built on Midnight, a privacy-focused blockchain.

Key Features

Fair Gameplay via Zero-Knowledge Proofs (ZK Proofs)
The app utilizes a "commit/reveal" scheme powered by Compact smart contracts. Players commit to their move (Rock, Paper, or Scissors) by submitting a hashed value. Once all players have committed, the moves are revealed. This ensures a tamper-proof gaming experience where "sniping" or reacting to an opponent's move is impossible.
Powered by the Midnight Blockchain
Contracts are deployed on the Midnight PreProd testnet, with all transactions recorded on-chain.
Full-Stack Architecture

Package Role

pkgs/contract Smart contracts written in the Compact language

pkgs/cli CLI tools for contract deployment and interaction

pkgs/app Frontend UI built with React + Vite
Lace Wallet Integration
Connects with Lace Wallet via the @midnight-ntwrk/dapp-connector-api for secure signing and transaction processing.

Package	Role
`pkgs/contract`	Smart contracts written in the Compact language
`pkgs/cli`	CLI tools for contract deployment and interaction
`pkgs/app`	Frontend UI built with React + Vite

Game Flow

Commit Phase — Each player commits their move…

View on GitHub

Quick Start

Here are the steps to get the app running locally.

To be honest, it takes about 15-20 minutes including ZK circuit compilation and the initial Docker image pull. Get your coffee ready!

Environment

Tested with the following:

Docker version 27.4.0
compact 0.2.0
bun 1.3.13
node 23.3.0

Install Lace Wallet to your browser

If you have not yet installed Lace Wallet, you must go to below page & need to install Lace Wallet

Lace | The light wallet platform to explore Web3

Discover the new light wallet platform from Input Output Global. Manage digital assets, and access NFTs, DApps, and DeFi services. Start your Web3 journey.

lace.io

Next, you need to create wallet account of Midnight

Please switch to PreProd Network

0. Clone the Repository

git clone https://github.com/mashharuki/midnight-rps-sample-app.git

1. Install Dependencies

bun install

2. Compile and Build Contracts

# Generate ZK circuit assets (This takes the most time)
bun contract compact  

# Build CLI and Frontend
bun cli build
bun app build

The bun contract compact step is where the Compact compiler generates the ZK proving and verification keys.

3. Start the Proof Server (Initial Pull: ~3 mins)

We need to run the server that handles ZK proof generation via Docker.

Without this server, you won't be able to deploy contracts or send commit/reveal transactions.

Version 8.0.3 is verified with Compact 0.2.0.
Ensure your SDK and Proof Server versions match, or proof generation will fail.

docker run -d -p 127.0.0.1:6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server

4. Deploy Contract to PreProd Network

If you don't have testnet NIGHT Token, you can get some token from below site.

https://faucet.preprod.midnight.network/

bun cli preprod-pts

If you deploy successfull, contract address shows like below.

[19:24:25.997] INFO (40223): Deploying RPS contract...
  ⠇ Deploying RPS contract[19:24:51.416] INFO (40223): Deployed RPS contract at: 23149945fed06aa010cc3e48e9f5df91625567300fae4e09371bb788d07a6bd8
  ✓ Deploying RPS contract
  Contract deployed at: 23149945fed06aa010cc3e48e9f5df91625567300fae4e09371bb788d07a6bd8

The Essence of Midnight Architecture: "Localizing" Information

Developing with Midnight requires a different mindset compared to Solidity.

As mentioned in my previous articles, Midnight has two types of states:

Public State: Visible to everyone (on-chain ledger).
Private State: Visible only to you (local storage).

The Compact ZK circuits act as the bridge between these two.

App Architecture

Code Deep Dive: Mathematically Preventing Cheating

1. Security Core: Domain Separation

When deriving a public key from a secret key, Midnight recommends using domain separation:

pure circuit derive_pk(sk: Bytes<32>): Bytes<32> {
  // Domain separation with a fixed string "rps:pk:v1"
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "rps:pk:v1"), sk]);
}

If you use the secret key as-is, using the same key in another app would result in the same public key, risking data leakage. By adding a prefix like "app name + version", we ensure that the public keys derived from the same secret key are unique to each app.

2. The Commit-Reveal Circuits

Commit Phase (Declaring a move while keeping it hidden)

export circuit commit(): [] {
  assert(!game_over,                 "Game is already over");
  assert(state == GameState.waiting, "Not in waiting state");

  const sk         = local_secret_key(); // witness: private input
  const pk         = derive_pk(sk);
  const my_move    = get_my_move();
  const my_salt    = get_my_salt();
  const commitment = make_commit(my_move, my_salt);
  store_move_and_salt(my_move, my_salt); // ⭐ Save move and salt to private state

  if (!p1_joined) {
    p1_key    = disclose(pk);
    p1_commit = disclose(commitment);
    p1_joined = true;
  } else {
    assert(!p2_joined, "Both players already committed");
    p2_key    = disclose(pk);
    p2_commit = disclose(commitment);
    p2_joined = true;
    state     = GameState.committed; // Transition to 'committed' when both joined
  }
}

Pay close attention to store_move_and_salt.

This is a witness function that saves the selected move and salt to the browser's IndexedDB (private state). To prove that the move revealed later is the same one committed earlier, this step is absolutely necessary.

The use of disclose() is also critical. It allows developers to explicitly control which results of private computations are written to the public ledger.

Game State Transitions

The coordination between commit and reveal phases is managed by these states:

3. Reveal Phase: Where ZK Proofs Shine

If the commit is the "declaration," the reveal is the "proof."

This is where Midnight's ZK stack really pays off.

export circuit reveal(): [] {
  assert(!game_over,                   "Game is already over");
  assert(state == GameState.committed, "Not in committed state");

  const sk      = local_secret_key();
  const pk      = derive_pk(sk);
  const my_move = get_my_move();   // Restore from private state
  const my_salt = get_my_salt();   // Restore from private state
  const computed = make_commit(my_move, my_salt);

  const is_p1 = disclose(p1_key == pk);
  const is_p2 = disclose(p2_key == pk);
  assert(is_p1 || is_p2, "Caller is not a registered player");

  if (is_p1) {
    assert(!p1_revealed, "Player 1 already revealed");
    assert(disclose(computed == p1_commit), "Commitment mismatch for P1");
    p1_move     = disclose(my_move); // Move is written to ledger only now
    p1_revealed = true;
  }
  if (is_p2) {
    assert(!p2_revealed, "Player 2 already revealed");
    assert(disclose(computed == p2_commit), "Commitment mismatch for P2");
    p2_move     = disclose(my_move);
    p2_revealed = true;
  }

  if (disclose(p1_revealed && p2_revealed)) {
    result    = who_wins(p1_move, p2_move); // Judge winner
    game_over = true;
    state     = GameState.finished;
  }
}

The line assert(disclose(computed == p1_commit), "Commitment mismatch for P1") is the heart of the logic:

my_move and my_salt exist only in your local private state.
make_commit(my_move, my_salt) is re-calculated, and the ZK circuit verifies it matches the p1_commit recorded on-chain during the commit phase.
You mathematically prove that "this move is the one I committed to" without revealing the move itself until the proof is valid.

Once the reveal is successful, p1_move and p2_move are finally written on-chain, and who_wins() determines the outcome.

During the commit phase, your move is hidden by ZK and remains unknown to the opponent until it is revealed. This is the mechanism that "mathematically prohibits cheating."

Overcoming the ZK dApp UX Hurdle

The biggest challenge during implementation was handling the "ZK proof generation time."

Filling the 10-Second Silence

In Midnight, before sending a transaction, you must generate a proof on your machine (or the Proof Server). This takes about 5-10 seconds.

UX improvements are essential to prevent users from thinking the app has frozen:

Optimistic UI Updates: Switch the UI state to "Generating Proof..." as soon as the process starts to communicate clearly what is happening.
Persistent Providers: Use levelPrivateStateProvider to ensure that even if the user reloads the browser during proof generation, the generated data and chosen moves are not lost.

// Example levelPrivateStateProvider configuration
privateStateProvider: levelPrivateStateProvider({ 
  accountId, 
  namespace: "rpsPrivateState", // Separate namespace for each game
  privateStoragePasswordProvider: () => storagePassword // Secure storage
}),

Sequence: From Commit to Game End

Let's recap the full flow:

Remaining Challenges

There's still a lot to learn by building with Midnight and Compact. Here are some issues I'm still working on:

1. The Abandonment Problem (Griefing Attack)

If Player 1 commits and Player 2 never joins, the contract stays locked. I need to implement a timeout/cancel mechanism in a future update.

2. Version Management of Build Assets

ZK circuit assets (proving keys) generated by bun contract compact can become invalid with even minor updates to the Compact version or compiler.

I actually ran into this during development. If you're building a similar app, double-check your library and Proof Server versions!

Solving these two will open up even more possibilities for ZK dApps on Midnight.

Conclusion

Implementing this "fair" RPS app taught me three key lessons:

Verify Versions: Proof generation can fail due to mismatched Proof Server versions.
Don't Forget store_move_and_salt: Saving private state is mandatory for the reveal phase.
UX is Priority #1: Designing a UI that handles the unique "waiting time" of ZK is critical.

Next, I'm planning to tackle multi-round support and timeout handling!

If you're interested in Midnight's privacy tech, check out the repository and my other technical blogs!

Thanks for reading!

Follow me on X!

x.com

References

Unleashing IronClaw: The Secure, Rust-Based AI Agent Framework by NearAI

Haruki Kondo — Wed, 29 Apr 2026 07:29:12 +0000

Introduction: The Rise of Secure AI Agents

By now, most of you in the AI space have probably heard of OpenClaw. It’s the AI Agent framework that took the community by storm in early 2026.

But have you heard of IronClaw?

While OpenClaw focused on accessibility and rapid prototyping, IronClaw is its security-hardened sibling, built from the ground up in Rust. Developed by the team at Near AI, it’s designed for developers who need autonomous agents that can handle sensitive data—like passwords and API keys—without exposing them to the LLM.

In this post, we’ll dive deep into what makes IronClaw the "Iron Man suit" for your AI agents.

What is IronClaw?

IronClaw is an open-source AI Agent framework developed by Near AI. It is designed to run in secure environments like NEAR AI Cloud, allowing agents to autonomously operate tools (Google Workspace, GitHub, etc.) while keeping user credentials strictly confidential.

About Near AI

Near AI Official Website

Near AI started as a prominent Layer 1 blockchain project (once considered a potential "Ethereum killer"). Today, it has evolved into an AI-native public blockchain.

Fun fact: One of its founders, Illia Polosukhin, is a co-author of the seminal "Attention Is All You Need" paper—the research that introduced the Transformer architecture to the world.

Key Features of IronClaw

Running IronClaw on the NEAR AI Cloud provides several hardware-level security benefits that standard frameworks lack:

TEE (Trusted Execution Environment): Agents run in encrypted, isolated enclaves.
Data Confidentiality: Memory data is always encrypted. Not even the cloud provider (NEAR AI) can peek into your conversations or memory.
Verifiability: Hardware-level isolation (like GPU attestation) ensures private and verifiable computing.
Secrets Protection: An "Encrypted Vault" integrates with the infrastructure to inject credentials into tools without the LLM ever seeing the raw API keys.

Capabilities at a Glance

Category	Feature	Benefit
Security	Encrypted Vault / WASM Isolation	Secrets are stored safely; tools run in sandboxes.
Connectivity	Multi-channel Support	Operate via Terminal, Telegram, Discord, or Webhooks.
Memory	Persistent Memory	Agents remember past conversations and documents for RAG.
Automation	Scheduled Jobs	Automate tasks like "Generate a report every morning at 9 AM."
Extensibility	Tool Ecosystem	Easily add tools for Google Docs, Calendar, GitHub, and Web Search.

The 4-Layer Security Architecture

IronClaw employs a "Defense in Depth" strategy, ensuring data passes through four independent protection layers before reaching any external service.

Safety Layer: Prevents prompt injection, sanitizes content, and scans for over 15 types of secret patterns.
WASM Sandbox: A lightweight execution environment for tools with strict memory limits (default 16MB) and "Fuel Metering" to prevent infinite loops.
Docker Sandbox: Container-level isolation for complex jobs and untrusted script execution.
Secret Management: A "Zero-Exposure" model using AES-256-GCM encryption where credentials are only injected at the host boundary.

WASM vs. Docker Sandbox: Which is which?

Feature	WASM Sandbox	Docker Sandbox
Runtime	`wasmtime`	Container Virtualization
Primary Use	Secure Tool Execution	Code Execution, Builds, Scripts
Footprint	Extremely Lightweight	Moderate Resource Usage
Limits	Fuel Metering (Instructions)	CPU / Memory (Standard)
Secret Access	Injected via Proxy	Environment Variables / Volumes

Getting Started with IronClaw

1. Access the Agent Dashboard

Head over to the Near AI Agent Dashboard.

2. Choose Your Plan

The Starter plan is free and perfect for getting your feet wet.

3. One-Click Deployment

Click the Deploy button to spin up your IronClaw instance on NEAR AI Cloud.

The default LLM is typically set to Qwen, but you can customize this.

4. Experiment!

Try chatting with your agent, adding new Skills, or connecting MCP (Model Context Protocol) servers.

Conclusion

With a team led by a Transformer co-author, it’s no surprise that IronClaw is a masterclass in combining AI utility with rigorous security. Its deployment process is arguably one of the smoothest in the ecosystem.

If you’re looking to build an agent that does more than just chat—an agent you can actually trust with your digital life—IronClaw is the way to go.

Thanks for reading!

Join the Hackathon!

Near AI is proud to sponsor the OpenClaw Hackathon on May 2nd!

Using IronClaw in your project will definitely put you on the radar for the security-focused tracks. We can't wait to see what you build!

References

IronClaw Official Site
Developer Documentation
nearai / ironclaw

IronClaw is OpenClaw inspired implementation in Rust focused on privacy and security
IronClaw

Your secure personal AI assistant, always on your side

English | 简体中文 | Русский | 日本語 | 한국어

Philosophy • Features • Installation • Configuration • Security • Architecture

Philosophy

IronClaw is built on a simple principle: your AI assistant should work for you, not against you.

In a world where AI systems are increasingly opaque about data handling and aligned with corporate interests, IronClaw takes a different approach:
- Your data stays yours - All information is stored locally, encrypted, and never leaves your control
- Transparency by design - Open source, auditable, no hidden telemetry or data harvesting
- Self-expanding capabilities - Build new tools on the fly without waiting for vendor updates
- Defense in depth - Multiple security layers protect against prompt injection and data exfiltration
IronClaw is the AI assistant you can actually trust with your personal and professional life.

Features

Security First
- WASM Sandbox - Untrusted…
View on GitHub
Near AI Agent Dashboard

Building a Full-Stack ZK-Privacy App on Midnight: A Step-by-Step Guide

Haruki Kondo — Sun, 26 Apr 2026 13:11:02 +0000

Introduction

Hello everyone! 🚀

In this post, we are diving deep into Midnight, the privacy-focused blockchain!

Previously, we covered how to connect a frontend application to Lace Wallet. Now, we’re taking the next big step: connecting to a smart contract!

Implementing a full-stack ZK (Zero-Knowledge) application can be tricky, but I’ve navigated the pitfalls and version mismatches so you don't have to. Let’s get started!

What You Will Learn

How to develop a full-stack application on Midnight.
Concrete source code for calling smart contract functions via Lace Wallet.
Real-world "gotchas" and how to solve them.

The Sample App: A Full-Stack Counter

We’ll build a simple app that connects to Lace Wallet, displays balances, and interacts with a Counter smart contract.

Prerequisites

Lace Wallet browser extension (Midnight-compatible version).
PreProd network selected in Lace settings.
Some test NIGHT tokens from the official faucet.
Docker installed (for running the Proof Server).

GitHub Repository

Check out the full source code here:
https://github.com/mashharuki/midnight-sample-fullstack-app

Application Preview

Technical Features

Category	Feature	Description
Contract	Build	Compiles Compact files into WASM/ZKIR/Managed Code.
Contract	Simulator	Logic verification using `CounterSimulator` without a live network.
CLI	Deploy	Deploys to Standalone/TestNet and retrieves the contract address.
CLI	Interaction	Direct CLI commands to increment and check counter values.
App	Wallet Connect	Integration with Lace Wallet extension to fetch account data.
App	Sync	Automatically joins and fetches current state from a contract address.
App	ZK Increment	One-click UI to generate ZK proofs and send transactions.

Tech Stack

Layer	Technology
Frontend	React 19, Vite 5, Tailwind CSS v4, Lucide React, RxJS
Contract	Compact (Midnight's ZK DSL)
SDK	`@midnight-ntwrk/*` (SDK v2 / DApp Connector API v4)
Infrastructure	Midnight Node, Indexer, Proof Server (via Docker)
Tooling	Bun, Biome, Vitest, TypeScript

Deep Dive: Key Implementation Logic

The core logic resides in src/lib/counter.ts and src/hooks/useCounter.ts. This was the most challenging part of the build due to SDK version transitions and compatibility issues with Lace Wallet.

`src/lib/counter.ts`

This file handles the contract instance creation, state querying, and transaction calls.

1. Contract Instance Creation

We use the SDK to wrap the compiled Compact contract.

import * as CompactJs from "@midnight-ntwrk/compact-js";

// Initialize the compiled contract instance
export const counterContractInstance: CounterContract = (CompactJs.CompiledContract.make(
  "counter",
  Counter.Contract as any,
) as any).pipe(
  CompactJs.CompiledContract.withVacantWitnesses,
);

2. Querying State

Using queryContractState, we can fetch the ledger data (in this case, the round number of our counter).

export const getCounterValue = async (
  providers: CounterProviders,
  contractAddress: ContractAddress,
): Promise<bigint | null> => {
  assertIsContractAddress(contractAddress);

  const contractState = await providers.publicDataProvider.queryContractState(
    contractAddress,
  );

  return contractState != null
    ? Counter.ledger(contractState.data as any).round
    : null;
};

3. Calling Updates (Transactions)

The magic happens in callTx. This triggers the ZK proof generation and requests a signature from Lace Wallet.

export const incrementCounter = async (
  counterContract: DeployedCounterContract,
): Promise<void> => {
  // Call the increment() method on the contract
  await (counterContract as any).callTx.increment();
};

Getting Started: Run it Locally

1. Clone & Install

git clone https://github.com/mashharuki/midnight-lace-react-sample-app.git
cd midnight-lace-react-sample-app
bun install

2. Start the Proof Server

Midnight requires a Proof Server to generate ZK Proofs locally before sending transactions to the network.

cd pkgs/cli
# Start the Proof Server (Ensure it's version 8.0.3)
docker compose -f standalone.yml up -d

3. Build & Deploy the Contract

bun contract build

# Deploy to the PreProd network
bun cli preprod

Note: Copy the contract address displayed in the terminal!

4. Setup & Start the Frontend

# Set environment variables
cp pkgs/app/.env.local.example pkgs/app/.env

# Build and start
bun app build
bun app dev

Visit localhost:5173. You should see the following:

Connect your wallet.
Enter your deployed contract address and click Join.
Click Increment. You will be prompted to sign the transaction.

Wait a few moments for the ZK proof generation and network finalization. Once done, refresh to see the updated value!

Sequence Diagrams

Unlike traditional blockchains, Midnight involves a local ZK Proof generation step in every state-changing transaction.

Contract Deployment Flow

Increment Function Call Flow

Summary

Building with ZK-privacy is a paradigm shift. While there were hurdles—especially around SDK versions and wallet compatibility—overcoming them allows you to build applications that truly respect user privacy.

I even created a custom AI Agent skill to help debug the Midnight SDK logic, which made the final stretch much smoother! You can find my Claude skills in the repo if you're interested.

Happy coding, and see you in the next one where we might tackle some hackathon challenges! 🛡️✨

References

Build a Simple App That Connects to Midnight Lace Wallet

Haruki Kondo — Fri, 24 Apr 2026 12:35:58 +0000

Introduction

Hello everyone!

In this article, we will look at Midnight, a privacy-focused blockchain, and its dedicated wallet, Lace Wallet.

Lace | The light wallet platform to explore Web3

Discover the new light wallet platform from Input Output Global. Manage digital assets, and access NFTs, DApps, and DeFi services. Start your Web3 journey.

lace.io

The official documentation explains how to deploy and run contracts, but I could not find clear guidance on connecting Lace Wallet to a frontend app. I ran into a few tricky points while trying it, so I created a simple beginner-friendly sample app.

I hope you enjoy it!

What You Will Learn

A quick overview of Lace Wallet
How to build a simple app that connects to Lace Wallet

What Is Lace Wallet?

Lace Wallet is a lightweight wallet for storing and managing Cardano-related digital assets. It was announced by IOG, the team behind Cardano, on June 9, 2022.

It can manage digital assets on blockchains in the Cardano ecosystem, including Midnight.

Even though it is lightweight, it offers rich features such as staking and asset transfers.

It is currently optimized for the Cardano ecosystem, and it appears support for other ecosystems is planned in the future.

Build a Simple App That Connects to Lace Wallet

Prerequisites

Before running the sample code, make sure you have the following:

The Lace Wallet browser extension installed (a version with Midnight support)
PreProd selected in Lace network settings

Sample Code Repository

mashharuki / midnight-lace-react-sample-app

midnight-lace-react-sample-app

A sample dApp frontend for connecting to the Midnight Network (PreProd).
Use Lace Wallet to connect your wallet, view your shielded address, and check your balance.

Screenshots

Features

Feature	Description
Lace Wallet Connection	Detects and connects to `window.midnight.mnLace` via 100ms polling
Version Validation	Verifies that the Connector API version is `>=1.0.0`
Network Detection	Automatically tries networks in order: PreProd / mainnet / undeployed / preview
Address Display	Shows the shielded address in a copyable format
Balance Display	Shows Shielded / Unshielded / Dust balances in tDUST units
Language Toggle	Instantly switch between Japanese and English via the top-right button (persisted in localStorage)

Tech Stack

Category	Library / Tool
Framework	React 19 + TypeScript
Build	Vite 8
Styling	Tailwind CSS v4 (`@tailwindcss/vite`)
UI Components	shadcn/ui (Button, Badge, Card) + Lucide React
Internationalization	i18next 26 + react-i18next 17
Wallet Integration	`@midnight-ntwrk/dapp-connector-api`
Async Processing	RxJS 7
Package Manager	Bun
Formatter

…

View on GitHub

App Preview

This sample app is intentionally simple: connect Lace Wallet and display balances.

Feature List

Feature	Description
Lace Wallet connection	Detects and connects to `window.midnight.mnLace` using 100ms polling
Version check	Confirms Connector API version is `>=1.0.0`
Network validation	Automatically tries PreProd / mainnet / undeployed / preview in order
Address display	Shows a copyable shielded address
Balance display	Shows Shielded / Unshielded / Dust balances in tDUST
Language switch	Instantly toggles Japanese ⇆ English from the top-right button (persisted via localStorage)

Tech Stack

Category	Library / Tool
Framework	React 19 + TypeScript
Build	Vite 8
Styling	Tailwind CSS v4 (`@tailwindcss/vite`)
UI Components	shadcn/ui (Button, Badge, Card) + Lucide React
Internationalization	i18next 26 + react-i18next 17
Wallet Integration	`@midnight-ntwrk/dapp-connector-api`
Async Processing	RxJS 7
Package Manager	Bun
Formatter	Biome

Key Source Code Explanations

The overall architecture is similar to many other blockchain apps.

If you understand the SDK and API specifications, you can build a working connection app quickly.

The key SDK in this project is @midnight-ntwrk/dapp-connector-api.

It is used to implement the wallet connection logic.

All important connection-related logic is consolidated in the file below.

A key point is around line 103.

// Attempt connection. If a network mismatch occurs, fall back to the next candidate.
walletAPI = await connector.connect(networkId);
// Lace v4: getConfiguration() is on walletAPI (not connector)
const walletRaw = walletAPI as unknown as Record<string, unknown>;

From walletRaw, you can extract wallet information such as addresses.

let address = "";
let coinPublicKey = "";
let encryptionPublicKey = "";

if (typeof walletRaw.getShieldedAddresses === "function") {
  // getShieldedAddresses() may return an array (old versions) or a single object (new versions), so handle both cases
  const result = await (
    walletRaw.getShieldedAddresses as () => Promise<Record<string, unknown>>
  )();
  // Lace v4 returns a single object (not array):
  // { shieldedAddress, shieldedCoinPublicKey, shieldedEncryptionPublicKey }
  const entry = (Array.isArray(result) ? result[0] : result) as
    | Record<string, unknown>
    | undefined;
  if (entry) {
    address = String(entry.shieldedAddress ?? entry.address ?? "");
    coinPublicKey = String(
      entry.shieldedCoinPublicKey ?? entry.coinPublicKey ?? "",
    );
    encryptionPublicKey = String(
      entry.shieldedEncryptionPublicKey ?? entry.encryptionPublicKey ?? "",
    );
  }
}

Balance retrieval is implemented as a dedicated React hook.

The most important part is the fetchBalances function.

It fetches balances from three wallet-related methods:

raw.getShieldedBalances
raw.getUnshieldedBalances
raw.getDustBalance

import { formatBalance } from "@/lib/utils";
import type { BalanceState } from "@/utils/types";
import type { DAppConnectorWalletAPI } from "@midnight-ntwrk/dapp-connector-api";
import { useCallback, useState } from "react";

export type { BalanceState };

/**
 * Fetch shielded / unshielded / dust balances in parallel from the wallet API.
 *
 * The Lace SDK type definitions do not include these balance methods,
 * so this function casts to unknown and checks method availability dynamically.
 * Promise.allSettled allows us to receive remaining results even if one call fails.
 */
async function fetchBalances(walletAPI: DAppConnectorWalletAPI): Promise<{
  shielded: string;
  unshielded: string;
  dust: string;
}> {
  const raw = walletAPI as unknown as Record<string, unknown>;

  // Try fetching balances in parallel. If a method is unavailable, return null.
  const [shieldedResult, unshieldedResult, dustResult] =
    await Promise.allSettled([
      typeof raw.getShieldedBalances === "function"
        ? (raw.getShieldedBalances as () => Promise<unknown>)()
        : Promise.resolve(null),
      typeof raw.getUnshieldedBalances === "function"
        ? (raw.getUnshieldedBalances as () => Promise<unknown>)()
        : Promise.resolve(null),
      typeof raw.getDustBalance === "function"
        ? (raw.getDustBalance as () => Promise<unknown>)()
        : Promise.resolve(null),
    ]);

  return {
    shielded:
      shieldedResult.status === "fulfilled"
        ? formatBalance(shieldedResult.value)
        : "--",
    unshielded:
      unshieldedResult.status === "fulfilled"
        ? formatBalance(unshieldedResult.value)
        : "--",
    dust:
      dustResult.status === "fulfilled"
        ? formatBalance(dustResult.value)
        : "--",
  };
}

/**
 * Custom hook to manage loading and refreshing balances.
 *
 * @param walletAPI - Connected wallet API. If null, no action is taken.
 * @returns balanceState: current balance state / refresh: manual refresh trigger
 */
export function useBalance(walletAPI: DAppConnectorWalletAPI | null) {
  const [balanceState, setBalanceState] = useState<BalanceState>({
    status: "idle",
  });

  /**
   * Fetch balances from the wallet API and update state.
   * If walletAPI is null, do nothing.
   * Set status to "loading" while fetching, "loaded" on success with balances,
   * and "error" if anything fails.
   */
  const refresh = useCallback(async () => {
    if (!walletAPI) return;
    setBalanceState({ status: "loading" });
    try {
      const balances = await fetchBalances(walletAPI);
      setBalanceState({ status: "loaded", ...balances });
    } catch (e: unknown) {
      console.error("[useBalance] Failed to fetch balances:", e);
      setBalanceState({ status: "error" });
    }
  }, [walletAPI]);

  return { balanceState, refresh };
}

How to Run the App

Clone

git clone https://github.com/mashharuki/midnight-lace-react-sample-app.git

# Move to the frontend app directory
cd app

Install

bun install

Build

bun run build

Start

bun run dev

Conclusion

That is all for this tutorial.

Now you have a clear path to connect a React + Vite app with Lace Wallet, which is a solid step toward building a full-stack Midnight application.

In a future article, I plan to cover how to call functions on a smart contract deployed on Midnight and continue toward a full-stack implementation.

Thank you for reading!

References

[Hands-on] Midnight Deep Dive: Start Building Smart Contracts with Compact

Haruki Kondo — Tue, 14 Apr 2026 15:25:20 +0000

Introduction: The "Too Transparent" Problem of Blockchains

Since the Bitcoin whitepaper was published, blockchain technology has transformed many industries, from finance to supply chains, thanks to its trustless design, transparency, and tamper resistance.

bitcoin.org

The idea that anyone can validate the same distributed ledger and form a trust network without centralized administrators was truly revolutionary.

But complete transparency can also become a major weakness.

What if confidential enterprise data is exposed to competitors?
What if personal transaction history is visible to the entire world?
What if private medical records or voting behavior can be inspected by anyone?

That "too transparent" problem has been one of the biggest barriers preventing public blockchain technology from being widely adopted in enterprise and daily consumer use cases.

To solve this dilemma, a breakthrough project has emerged from the Cardano ecosystem.

That project is Midnight.

Midnight is a Cardano sidechain focused on data protection and privacy.

By leveraging cutting-edge cryptography known as Zero-Knowledge Proofs (ZKPs)[^1], Midnight enables us to prove only the facts we need, without revealing anything else.

ZKPs are often discussed in the context of privacy, but they can also reduce computational overhead depending on how they are used.

Representative examples include ZkEVM and INTMAX, both of which use ZK-based approaches for EVM-related scaling.

INTMAX – Stateless Layer for Billions

INTMAX is a stateless, privacy-centric Layer 2 on Ethereum that delivers fast, secure, and cost-efficient transactions. Explore the future of private digital payments and empower your transactions with unmatched anonymity and speed.

intmax.io

I recently joined the Midnight Hackathon in London and spent a lot of time exploring Compact. In this article, I share what I learned in a hands-on format: from environment setup to contract implementation, testing, and deployment.

Home - Midnight Summit 2025

Midnight Summit 2025: An invitation-only ecosystem event with talks, breakouts and a live Hackathon shaping the future of privacy-first blockchain.

midnightsummit.io

If you want a conceptual introduction to Midnight first, check this article:

Haruki Kondo for Midnight Aliit Fellowship

Apr 13

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

#blockchain #web3 #typescript #zkp

4 min read

[^1]: Zero-Knowledge Proof (ZKP) is a cryptographic method that lets you prove a statement is true without revealing any additional information (including why it is true).

Compact: A Privacy Smart Contract Language with TypeScript-like Syntax

Another core pillar behind Midnight's innovation is its smart contract language, Compact.

"Isn't zero-knowledge technology only for cryptography experts?"

Compact is designed to dramatically lower that barrier.

TypeScript-based syntax

The biggest feature of Compact is that it is a TypeScript-based domain-specific language (DSL).

That means a large number of web developers can build privacy-preserving applications with familiar syntax, instead of learning an entirely new language from scratch.

The Compact compiler translates your logic into the cryptographic components needed for zero-knowledge proofs, so you do not have to deal with the underlying math directly.

Three data states: Public, Private, Witness

The core of data handling in Compact is clear separation of privacy levels.

Data is mainly handled in three states:

public (public state)
- Data visible on the blockchain.
- Similar to state variables in conventional smart contracts.
- Defined with the ledger keyword.
private (private state)
- Confidential data managed only in a user's local (off-chain) environment.
- The raw private data itself is not recorded on-chain.
- Defined with the private keyword.
witness (proof input)
- Input supplied during transaction execution to prove, "I know this data."
- Used as evidence when updating private state.
- Defined with the witness keyword.

Basic syntax and a Counter smart contract example

Let's look at these concepts through a simple Counter contract.

This contract only increments a number, and is also introduced in official tutorials.

It includes:

A state variable stored on the public ledger
A method to increment that state

pragma language_version >= 0.16 && <= 0.25;
import CompactStandardLibrary;

// Public state stored on the on-chain ledger
export ledger round: Counter;

// Transition function that updates public state
export circuit increment(): [] {
    round.increment(1);
}

ledger: A publicly visible on-chain state variable.
circuit: A transaction-invoked state transition function where validation and updates happen.

With Compact, you can write logic in TypeScript-like syntax while controlling data privacy in detail and proving correctness intuitively.

Hands-on: Set up your Midnight development environment

Now let's move from theory to practice.

In this section, we build the environment needed to run counter.compact.

As of November 2025, frontend integration is still unstable.

So in this hands-on, the goal is to deploy a smart contract and interact with it via CLI.

Required components:

Compact CLI Command-line tool for compiling and testing smart contracts.
Lace Midnight Preview Wallet Browser extension wallet for Midnight Testnet.
Testnet Faucet Service to get test tokens.
ZK Proof Server Local server for generating and verifying zero-knowledge proofs.
Sample repository Source code used in this tutorial.

Step 1: Install Compact CLI

First, install the compact CLI compiler:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

Then pin a specific version (0.25.0 in this article):

compact update 0.25.0

Check installation:

compact --version
# compact 0.2.0 or similar
compact compile --version
# 0.25.0

If compact compile --version returns 0.25.0, you're good.

Step 2: Prepare Lace Wallet and get Testnet tokens

Next, set up a wallet and receive test tokens.

Install Lace Wallet Add Lace Midnight Preview from the Chrome Web Store.
Create your wallet Follow the setup wizard. Store your recovery phrase securely.
Copy your address From the wallet home screen, click "Receive" and copy your address.
Request faucet funds Open Midnight Testnet Faucet, paste your address, and click "Request funds". After a short wait, test tDUST tokens should arrive.

Step 3: Start ZK Proof Server

Private processing (including proof generation) is handled through a local Proof Server.

We'll start the official Midnight Docker image:

Docker Desktop must be installed for this step.

docker run -p 6300:6300 midnightnetwork/proof-server -- 'midnight-proof-server --network testnet'

If logs start streaming, it launched successfully. Keep this terminal running.

You can also verify with:

curl -X GET "http://localhost:6300"

Expected response:

We're alive 🎉!

Step 4: Prepare sample repository

Finally, set up the repository used in this article:

mashharuki / midnight-sample

midnightでの開発事前検証用リポジトリ

midnight-sample

midnightでの開発事前検証用リポジトリ

環境

nodejs
yarn
docker
compact CLI

compact CLIのインストール

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

その後、以下でバージョン指定

compact update 0.25.0

インストールされているかの確認

compact --version
compact compile --version

それぞれ以下のようになればOK!

compact 0.2.0
0.25.0

Testnet用のZKProof serverの起動

docker run -p 6300:6300 midnightnetwork/proof-server -- 'midnight-proof-server --network testnet'

docker ps

localhost:6300でサーバーが起動していればOK

CONTAINER ID   IMAGE                          COMMAND                  CREATED          STATUS          PORTS                                         NAMES
a62d9787f7a1   midnightnetwork/proof-server   "/nix/store/qa9fb15p…"   25 seconds ago   Up 24 seconds   0.0.0.0:6300->6300/tcp, [::]:6300->6300/tcp   flamboyant_roentgen

念の為以下のコマンドでも稼働確認

curl -X GET "http://localhost:6300"

We're alive 🎉!

サンプルプログラムのコンパイル＆デプロイ手順

まず、依存関係をインストールする

yarn

以下のコマンドでコントラクトをビルドする

yarn contract compact

以下のようになればOK!

Fetching public parameters for k=10 [====================] 192.38 KiB / 192.38 KiB
  circuit "increment" (k=10, rows=29)  
Overall progress [====================] 1/1

コントラクトのユニットテストコードを実行する

yarn contract test

以下のようになればOK!

 RUN  v4.0.8 /workspaces/midnight-sample/my-mn-app/pkgs/contract
 ✓ test/counter.test.ts (3 tests) 44ms
   ✓ Counter smart contract (3)
     ✓ generates initial ledger state deterministically 36ms
     ✓ properly initializes ledger

…

View on GitHub

# Clone your own fork
# (fork the repository first)
git clone https://github.com/<user-name>/midnight-sample.git
cd midnight-sample

# Install dependencies
yarn

Replace the git clone URL with your actual repository URL.

Environment setup is now complete.

Next, let's implement and test the smart contract.

Implement and test the Counter contract

With the environment ready, let's build and test.

Code walkthrough

Put this contract in pkgs/contract/src/counter.compact:

pragma language_version >= 0.16 && <= 0.25;
import CompactStandardLibrary;

// Public state stored on the on-chain ledger
export ledger round: Counter;

// Transition function that updates public state
export circuit increment(): [] {
    round.increment(1);
}

Then compile with compact CLI:

yarn contract compact

Under the hood:

compact compile ./src/counter.compact ./src/managed/counter

On success, you will see output like:

Fetching public parameters for k=10 [====================] 192.38 KiB / 192.38 KiB
  circuit "increment" (k=10, rows=29)
Overall progress [====================] 1/1

Unit test implementation

Compact lets you simulate contract logic off-chain for testing.

See pkgs/contract/src/test/counter.test.ts:

import { CounterSimulator } from "./counter-simulator.js";
import {
  NetworkId,
  setNetworkId
} from "@midnight-ntwrk/midnight-js-network-id";
import { describe, it, expect } from "vitest";

setNetworkId(NetworkId.Undeployed);

/**
 * Unit tests for the Counter contract
 */
describe("Counter smart contract", () => {
  it("generates initial ledger state deterministically", () => {
    const simulator0 = new CounterSimulator();
    const simulator1 = new CounterSimulator();
    expect(simulator0.getLedger()).toEqual(simulator1.getLedger());
  });

  it("properly initializes ledger state and private state", () => {
    const simulator = new CounterSimulator();
    const initialLedgerState = simulator.getLedger();
    expect(initialLedgerState.round).toEqual(0n);

    const initialPrivateState = simulator.getPrivateState();
    expect(initialPrivateState).toEqual({ privateCounter: 0 });
  });

  it("increments the counter correctly", () => {
    const simulator = new CounterSimulator();
    const nextLedgerState = simulator.increment();
    expect(nextLedgerState.round).toEqual(1n);

    const nextPrivateState = simulator.getPrivateState();
    expect(nextPrivateState).toEqual({ privateCounter: 0 });
  });
});

These tests verify three scenarios:

Contract initialization is deterministic.
Initial ledger value is 0.
increment updates the counter correctly.

Run tests

Run:

yarn contract test

If all tests pass, output looks like:

RUN  v4.0.8 /workspaces/midnight-sample/my-mn-app/pkgs/contract

 ✓ test/counter.test.ts (3 tests) 44ms
   ✓ Counter smart contract (3)
     ✓ generates initial ledger state deterministically 36ms
     ✓ properly initializes ledger state and private state 3ms
     ✓ increments the counter correctly 4ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  08:27:47
   Duration  421ms (transform 95ms, setup 0ms, collect 233ms, tests 44ms, environment 0ms, prepare 13ms)

JUNIT report written to /workspaces/midnight-sample/my-mn-app/pkgs/contract/reports/report.xml
Done in 1.34s.

Now that we know the logic works, let's create the CLI flow to deploy on Testnet.

Deploy and execute from CLI on Testnet

After local testing, it's time to deploy.

The pkgs/cli package contains scripts for deployment and contract interaction.

Generate TypeScript API

First, build the contract package:

yarn contract build

This runs commands like:

rm -rf dist && tsc --project tsconfig.build.json && cp -Rf ./src/managed ./dist/managed && cp ./src/counter.compact ./dist

This generates typed APIs so circuits like increment can be called safely from the cli package.

Set environment variables

Deploying to Testnet requires the wallet seed used to sign transactions.

Create .env from template in pkgs/cli:

cp pkgs/cli/.env.example pkgs/cli/.env

Edit pkgs/cli/.env:

NETWORK_ENV_VAR=testnet
SEED_ENV_VAR=
INITIAL_COUNTER_ENV_VAR=
CACHE_FILE_ENV_VAR=
CONTRACT_ADDRESS=

Handle your seed with extreme care.

Make sure this file is excluded by .gitignore and never pushed to GitHub.

CLI unit test walkthrough

There are also unit tests for the CLI layer.

// This file is part of midnightntwrk/example-counter.
// Copyright (C) 2025 Midnight Foundation
// SPDX-License-Identifier: Apache-2.0
// Licensed under the Apache License, Version 2.0 (the "License");
// You may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import { type Resource } from '@midnight-ntwrk/wallet';
import { type Wallet } from '@midnight-ntwrk/wallet-api';
import path from 'path';
import * as api from '../api';
import { type CounterProviders } from '../utils/common-types';
import { currentDir } from '../config';
import { createLogger } from '../utils/logger-utils';
import { TestEnvironment } from './commons';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

const logDir = path.resolve(currentDir, '..', 'logs', 'tests', `${new Date().toISOString()}.log`);
const logger = await createLogger(logDir);

describe('API', () => {
  let testEnvironment: TestEnvironment;
  let wallet: Wallet & Resource;
  let providers: CounterProviders;

  beforeAll(
    async () => {
      api.setLogger(logger);
      testEnvironment = new TestEnvironment(logger);
      const testConfiguration = await testEnvironment.start();
      wallet = await testEnvironment.getWallet();
      providers = await api.configureProviders(wallet, testConfiguration.dappConfig);
    },
    1000 * 60 * 45,
  );

  afterAll(async () => {
    await testEnvironment.saveWalletCache();
    await testEnvironment.shutdown();
  });

  it('should deploy the contract and increment the counter [@slow]', async () => {
    const counterContract = await api.deploy(providers, { privateCounter: 0 });
    expect(counterContract).not.toBeNull();

    const counter = await api.displayCounterValue(providers, counterContract);
    expect(counter.counterValue).toEqual(BigInt(0));

    await new Promise((resolve) => setTimeout(resolve, 2000));

    const response = await api.increment(counterContract);
    expect(response.txHash).toMatch(/[0-9a-f]{64}/);
    expect(response.blockHeight).toBeGreaterThan(BigInt(0));

    const counterAfter = await api.displayCounterValue(providers, counterContract);
    expect(counterAfter.counterValue).toEqual(BigInt(1));
    expect(counterAfter.contractAddress).toEqual(counter.contractAddress);
  });
});

Run these tests on both local and testnet environments.

Run unit tests locally

yarn cli test-api

Expected:

Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  08:41:12
   Duration  200.97s (transform 180ms, setup 72ms, collect 1.11s, tests 199.62s, environment 0ms, prepare 10ms)

Run unit tests against testnet

yarn cli test-against-testnet

Expected:

✓ src/test/counter.api.test.ts (1 test) 151857ms
  ✓ API (1)
    ✓ should deploy the contract and increment the counter [@slow]  125059ms

Test Files  1 passed (1)
    Tests  1 passed (1)
  Start at  08:47:54
  Duration  153.65s (transform 205ms, setup 93ms, collect 1.56s, tests 151.86s, environment 0ms, prepare 8ms)

Deployment script walkthrough

pkgs/cli/scripts/deploy.ts deploys the contract to Testnet.

It uses libraries such as @midnight-ntwrk/midnight-sdk and performs the following steps:

Load wallet seed from .env.
Build wallet object from the seed.
Configure providers for Testnet connection.
Execute deployment via api.deploy.

Run deployment

Deploy with:

yarn cli deploy

On success, the deployed contract address appears in terminal output:

[12:16:24.603] INFO (39506): Deploying counter contract...
[12:17:27.488] INFO (39506): Deployed contract at address: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
[12:17:27.488] INFO (39506): Deployment transaction: 00000000c408a293e4e287285649623774b2be950bf0d385a20117ce79a99eb7315aa547
[12:17:27.489] INFO (39506): Contract address: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
Counter contract deployed at: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
[12:17:27.489] INFO (39506): Not saving cache as sync cache was not defined
Done in 90.16s.

Set that value in CONTRACT_ADDRESS inside your .env.

Execute `increment`

Finally, call the deployed contract's increment circuit.

Run:

yarn cli increment

This script reads CONTRACT_ADDRESS from .env, connects to the existing contract with api.joinContract, then calls api.increment.

If successful, you should see transaction info and the current counter value:

[12:33:37.176] INFO (47085): Incrementing...
[12:34:34.270] INFO (47085): Transaction 000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 added in block 2485067
[12:34:34.271] INFO (47085): Increment transaction: 000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 (block 2485067)
Counter incremented. txId=000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 block=2485067
[12:34:34.271] INFO (47085): Checking contract ledger state...
[12:34:34.462] INFO (47085): Ledger state: 1
[12:34:34.463] INFO (47085): Current counter value: 1
[12:34:34.463] INFO (47085): Current counter value: 1
Current counter value: 1
[12:34:34.463] INFO (47085): Not saving cache as sync cache was not defined
Done in 128.20s.

If Current counter value: 1 appears, your public counter was incremented successfully.

This completes the hands-on section.

Current limitations and what's next

As of November 2025, Midnight is still in developer Testnet phase, and Mainnet has not launched yet.

So keep the following in mind:

Performance Finality on Testnet can take time.
API changes SDK/CLI behavior may change during active development. Check official docs regularly.
Feature scope Available tooling is still limited, though development is moving quickly with community feedback.
Frontend integration This was the area that took me the most research time during the hackathon. I also confirmed with the Midnight team onsite that stable frontend-contract integration libraries were not yet available at that time, so CLI was the practical path.

Midnight is a very ambitious project tackling one of Web3's most important challenges: privacy.

With Cardano's strong security model and community behind it, this ecosystem is definitely worth watching.

Closing thoughts

In this article, we walked through Midnight, Cardano's privacy-focused sidechain, and Compact, its smart contract language, in a practical hands-on format.

Midnight's approach to the blockchain "too transparent" problem.
Compact language for intuitive private DApp development with TypeScript-like syntax.
Data modeling with public, private, and witness.
Full flow from environment setup to implementation, testing, and Testnet deployment.

I am very excited to see how this evolves.

The hackathon itself was also an amazing experience, so I will keep following upcoming updates.

Thanks for reading.

References

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

Haruki Kondo — Mon, 13 Apr 2026 14:08:48 +0000

Introduction: The "Too Transparent" Problem in Blockchain

Seventeen years have passed since the Bitcoin whitepaper was released.

bitcoin.org

Blockchain's immutability and transparency have been praised as groundbreaking mechanisms for trustworthy transactions. Because anyone can verify the ledger, blockchains created a new model of tamper-resistant trust.

However, that same "complete transparency" also creates barriers in areas involving business and personal privacy. This issue has been especially clear in enterprise settings, which is one reason private chain adoption became popular.

What if your full banking transaction history were visible to anyone in the world?
What if a company's confidential supply chain information were exposed to competitors?
What if personal medical records or voting history became public?

Even imagining this is unsettling. I believe this "too transparent" problem is one of the key reasons blockchain technology has not yet fully penetrated all parts of society.

Not everything can be public all the time. To solve this dilemma, a new light has emerged: Midnight.

Midnight Documentation | Midnight Docs

Build privacy-preserving applications with selective disclosure and zero-knowledge proofs on Midnight.

docs.midnight.network

Midnight is Cardano's partner chain (sidechain) specialized for data protection and privacy. In this article, I will guide you through Midnight in a story-driven way so you can understand its innovative technology and future potential.

Chapter 1: What Is Midnight? - A New Blockchain for Privacy

In one sentence, Midnight is a data-protection blockchain that enables Selective Disclosure. While many traditional blockchains force everything to be public, Midnight makes it possible to prove only the facts that need to be proven, without revealing anything else.

Note
There are other blockchains, such as Zcash, that adopt similar privacy-oriented approaches.

The technology that enables this is Zero-Knowledge Proofs (ZKPs).

Architecture Overview

Comparison of Traditional Blockchain vs Midnight with ZKPs

I have another article dedicated to Zero-Knowledge Proofs (ZKPs), so feel free to check that out as well:

【図解】ゼロ知識証明のPLONKとは？Groth16との違いを世界一わかりやすく解説！

zenn.dev

What Midnight aims to achieve

Midnight's mission is to remove the long-standing trade-off between data protection, ownership, and data utility.

For users: They can fully control their own data and decide who can see what, and how much.
For developers and enterprises: They can build innovative data-driven services without taking on privacy-violation risk.

This opens the door to use cases that were previously difficult or impossible on public blockchains due to confidentiality requirements.

Midnight's core: architecture and consensus

As a Cardano partner chain, Midnight is built on top of Cardano's robust security infrastructure.

Architecture: Midnight splits smart contract state into two parts:
1. Public state: Data that remains publicly available on-chain.
2. Private state: Data each user manages off-chain in their own local environment.
Kachina protocol: Public and private states are linked securely through Kachina, a research-driven unified framework. Users generate ZK proofs locally using private data, then submit only the proof to the blockchain for verification.
Consensus algorithm: Midnight adopts a hybrid consensus model combining AURA (block production) and GRANDPA (finality). Cardano stake pool operators (SPOs) participate as block producers.

Two native tokens: NIGHT and DUST

Midnight uses a unique dual-token model.

Token	Role	Characteristics
NIGHT	Governance, consensus	Unshielded token. Tradable and contributes to network security.
DUST	Transaction fees (gas)	Shielded resource. Non-transferable and privacy-preserving.

DUST acts as fuel, but because it is not a tradable asset, transaction metadata privacy is better preserved while keeping service costs more predictable.

Chapter 2: The Bond with Cardano - Why a Partner Chain?

Midnight is an independent chain, but its deep integration with Cardano is what unlocks its full potential.

Ecosystem Integration

Strategic integration between Cardano and Midnight Network

Inheriting security

Midnight addresses the challenge of network security by becoming a Cardano partner chain. It leverages Cardano's large, decentralized SPO network, allowing Midnight to access globally distributed, enterprise-grade infrastructure from day one.

How Midnight differs from Cardano

Cardano: Focuses on value storage/transfer and serving as a secure general-purpose decentralized platform.
Midnight: Uses Cardano's security as a base while specializing in データ保護とプライバシー as a dedicated computation layer.

They are complementary: Cardano provides the trust foundation, while Midnight enables privacy-sensitive applications.

Chapter 3: Compact - ZKP Smart Contracts with TypeScript-like Syntax

Note
"Aren't zero-knowledge proofs only for cryptography specialists?"

Midnight addresses this challenge with a new smart contract language: Compact.

midnightntwrk / compact

Compact Releases

Compact

Compact is the Midnight Network's smart contract language. This repository is only used to host Compact releases.

Contributing to Compact

The project welcomes contributions. If you would like to report a Compact bug, make a feature request, get the source code, etc. then you should do so at the Minokawa project's Compact repository.

View on GitHub

Why Compact is exciting

TypeScript-based DSL: Based on one of the world's most popular languages, allowing web developers to build privacy-focused apps with familiar syntax.
Abstraction of ZK complexity: The Compact compiler translates contract logic into the cryptographic material required for proof generation.
Privacy by Design: Data is treated as private by default. To expose private data, you must explicitly wrap it with disclose().

// Conceptual Compact example

// Private user vote
witness userVote: private Field;

// Public vote result
let results: public Field;

// Voting circuit
circuit vote() {
  // Update result when validation passes
  // Who voted for what remains private
  results = results + 1;

  // If you want to reveal vote content, do it explicitly
  // disclose(userVote);
}

Chapter 4: Use Cases Unlocked by Midnight

Digital ID / KYC: Prove you are over 18 without revealing your full birth date.
Anonymous voting: Truly fair voting systems with verified eligibility and ballot secrecy.
Healthcare: Private medical records used for aggregate analysis or AI research.
DeFi: Access financial services without exposing portfolios or strategies.
AI and LLMs: Use sensitive data for model training while preserving privacy.

Summary: The Dawn of a New Privacy Era

Midnight is foundational technology for a safer, fairer digital society where individuals retain data sovereignty and enterprises can innovate responsibly.

Thank you for reading! 🚀

Developer Resources

Midnight Developer Hub
midnightntwrk / midnight-awesome-dapps

Midnight Awesome Dapps
Awesome Midnight dApps

This project is built on the Midnight Network.

A curated list of awesome Midnight dApps, tools, and resources

Contents
- Awesome Midnight dApps
  
  Contents
  
  Getting Started
  
  Smart Contract Primitives
  
  Starter Templates
  
  Developer Tools
  
  Finance & DeFi
  
  Identity & Privacy
  
  Gaming
  
  Governance
  
  Dormant Projects
  
  Learning Resources
  
  Documentation
  
  Getting Started
  
  Tutorials
  
  Community
  
  Community Projects
  
  Contributing
  
  Submission Criteria
  
  License
Important

Community-contributed projects are shared for inspiration and exploration. These repositories are not maintained by the Midnight team, and their functionality may vary.

Note

🔹 = Official Midnight Ecosystem Partner
🏆 = Hackathon winners

Getting Started

Official dApps and tools maintained by the Midnight team (for education + onboarding)
- Example Counter - Simple increment/decrement app demonstrating state management
- Hello World Compact - Minimal Hello World smart contract for Midnight. Deploy to Preprod and store/read messages on-chain
- Example Bboard - Bulletin board with multi-user interactions and privacy patterns
- Example ZK Loan - ZK-powered…
View on GitHub
MeshJS / midnight-starter-template

Mesh Midnight starter template
🚀 EDDA - Midnight Starter Template
- A starter template for building on Midnight Network with React frontend and smart contract integration.
- Live Demo → counter.nebula.builders
📦 Prerequisites
- Node.js (v23+) & npm (v11+)
- Docker
- Git LFS (for large files)
- Compact (Midnight developer tools)
- Lace (Browser wallet extension)
- Faucet (Preview Network Faucet)
Known Issues
- There’s a not-yet-fixed bug in the arm64 Docker image of the proof server.
- Workaround: Use Bricktower proof server. bricktowers/proof-server:6.1.0-alpha.6
🛠️ Setup

1️⃣ Install Git LFS
# Install and initialize Git LFS sudo dnf install git-lfs # For Fedora/RHEL git lfs install
2️⃣ Install Compact Tools
# Install the latest Compact tools curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh
# Install the latest compiler # Compact compiler version 0.27 should be downloaded manually. Compact tools does not support it currently. compact update +0.27.0
3️⃣ Install Node.js and docker
- Node.js & npm
- Docker
4️⃣ Verify Installation
…
View on GitHub

References

Sera Protocol Tempo MPP: The Ultimate Cross-Border Payment Solution

Haruki Kondo — Sun, 29 Mar 2026 00:40:51 +0000

This article was written in collaboration with AI!

Introduction

Hello everyone!

In our ongoing series exploring Sera Protocol, we've built MCP servers and even developed a specialized Agent SKILL.

Today, we're diving into a fascinating concept: the synergy between Sera Protocol and the recently announced Machine Payments Protocol (MPP) from Stripe and Tempo!

Haruki Kondo

Mar 20

Deep Dive into Machine Payments Protocol (MPP): Resurrecting HTTP 402 for the AI Agent Era

#stripe #blockchain #ai #web3

4 min read

MPP has finally given AI the "hands to pay." However, the moment they cross borders, they hit a hard reality: the "Currency Wall." Let's explore how Sera Protocol smashes this barrier.

1. The "Exchange Wall" Facing AI Agents

MPP (Machine Payments Protocol) brings HTTP 402 "Payment Required" to life after 20 years, allowing AI to discover, negotiate, and settle payments in a single request.

But in practice, we encounter this tragic scenario:

API Server (USA): "This image generation costs $0.01 USDX (USD Stablecoin)."
AI Agent (Japan): "I only have JPYC (Japanese Yen Stablecoin)..."

For humans, credit cards handle this behind the scenes. For an autonomous AI agent, this currency mismatch means "Service Unavailable."

In the machine world, someone must act as an instant, on-chain middleman. This is the necessity of "OnChain FX" for machines.

2. The Tempo L1 "Highway" and Sera's "Gasoline"

According to the Tempo official documentation (OnChain FX), their goal is to eliminate the "Stablecoin Sandwich."

Traditional cross-border payments often look like "Local Currency → USD Stablecoin → Local Currency," relying on off-chain banks and exchanges that are slow and expensive.

This is where the synergy between Tempo L1 and Sera Protocol explodes.

Tempo L1's "Payment Lanes"

Tempo features dedicated block space called "Payment Lanes." Even if a sudden NFT minting craze spikes gas fees elsewhere, payment traffic glides through at 0.1 cents, completely unaffected.

TIP-20 "Multi-Currency Fees"

The genius of Tempo’s TIP-20 token standard is that "you can pay gas fees in any stablecoin—USDX, JPYC, you name it." Agents don't need to hold a separate native token (like ETH) just for gas.

On this "payment-optimized highway," Sera Protocol acts as the engine that atomically bridges different currencies.

3. Why AI Agents Need a Central Limit Order Book (CLOB)

You might wonder, "Why not just use an AMM like Uniswap?" For an AI agent, an AMM is often a "bundle of uncertainty."

"Rational" Limit Orders: AI operates on logic. It dislikes the "luck-based" slippage of AMMs. With Sera, an agent can make autonomous decisions: "I will buy at this rate; otherwise, I will wait."
The Magic of Index Management: Sera’s Arithmetic Price Model manages prices using uint16 indices. For an AI, these are easy-to-process "numeric values," allowing for lightning-fast arbitrage and price comparisons across multiple markets.
Rights Transfer via Order NFTs: Sera orders are NFTs. Instead of sending the exchanged USDX itself, an AI could transfer the "right to the completed exchange (the NFT)" directly to the service provider, enabling next-generation payment flows.

4. Synergy Breakdown: The MPP + Sera Atomic Flow

When an AI agent combines Sera and MPP for cross-border payments, the concept of "going to an exchange" disappears. Instead, "currency exchange becomes a seamless step within the payment process."

With this flow, the AI can buy resources worldwide without even caring which currency it holds.

5. Implementation Concept: Autonomous Exchange & Payment Logic

If you are giving your AI "hands and feet" using an MCP Server, the code becomes surprisingly simple.

// Internal logic for an AI agent receiving a 402 Challenge
async function onPaymentRequired(challenge: MPPChallenge) {
  const { amount: usdAmount, currency } = challenge; // 0.01 USDX

  // 1. Check the rate until satisfied
  const bestRate = await sera.getBestPrice('JPYC/USDX');
  if (bestRate > MY_ACCEPTABLE_LIMIT) {
    throw new Error("Exchange rate is too poor; aborting purchase for now.");
  }

  // 2. Exchange exactly what is needed
  // Sera's Index-based precision handles fractions like 10.5 JPYC perfectly
  const tx = await sera.swapAndClaim({
    from: 'JPYC',
    to: 'USDX',
    amount: usdAmount,
    index: bestRate
  });

  // 3. Pay immediately with the secured USDX
  return await mpp.pay(challenge, {
    useToken: 'USDX',
    gasToken: 'JPYC' // The power of Tempo!
  });
}

The AI optimizes which currency to use and which currency to pay fees with based on real-time rates. This is the true face of the "Programmable Economy" built by Stripe and Sera.

The Dawn of the Machine Economy is Here.

I’ve previously introduced Sera Protocol as a "new DEX," but seeing it paired with Tempo MPP reveals its full silhouette.

Sera is the "Currency Translator" for the Machine Economy.

With the payment network expanded by Stripe, the highway paved by Tempo, and the "shape of currency" refined by Sera Protocol, AI agents are finally ready to roam the world freely.

As an evangelist, I’m excited to implement this future with all of you. I look forward to showcasing a "Self-Exchanging Payment Agent" at an upcoming hackathon.

Why not empower your AI with Sera—the ultimate money changer?

References: