DEV Community: Toshiya Matsumoto

🔐 Practical Guide to ZKP: Learn Real Usecase of ZKP with Plonky2

Toshiya Matsumoto — Tue, 31 Mar 2026 02:48:05 +0000

It's for those who have heard of ZKP but never known the real usecase.

Before We Start

Zero-Knowledge Proof (ZKP) is a technology that proves the truth of a statement without revealing the underlying information. A common example is proving you know a password without showing it.

This article will use the Rust's fast recursive SNARK framework Plonky2 to build 3 ZKP circuits step by step. By the end of this article, you will understand the following:

How ZKP Circuits Work — Constraints, Witness, Public Inputs
Hash Chain Proof — Proving the order of data processing
State Transition Proof — Proving the update of Merkle tree

🧩 Core Model: Circuit, Prover, Verifier

Let's understand the core 3 models of ZKP:

Entity	What	Example
Circuit 📐	Define mathematical constraints	Template of Exam Questions — Define how the answer looks like
Prover 🧑‍💻	Generate proof with secret inputs	Student who solves the exam
Verifier ✅	Verify validity of proof with public inputs	Grader who checks the answer without seeing the solution

Core Concept: The circuit only defines the rules — it doesn't solve them. The prover supplies the secret answer. The verifier checks that the rules were followed without ever seeing that answer.

🌍 Real World Flow of ZKP: Who Proves, Who Verifies

Let's see how ZKP is used in the real world:

Flow Chart: Outline of Proof and Verification

┌──────────────────────────────────────────────────────────────────────┐
│ 1. Build Circuit (Developer does it once)                            │
│                                                                      │
│ Define constraints with CircuitBuilder → build() → CircuitData       │
│                                                                      │
│ Output:                                                              │
│   ・CircuitData (circuit definition)                                 │
│   ・VerifierCircuitData (verifier key) → made public                 │
└────────────────────────────────┬─────────────────────────────────────┘
                                 │
                  ┌──────────────┴──────────────┐
                  ▼                             ▼
┌───────────────────────────┐   ┌───────────────────────────┐
│ 2. Prove                  │   │ 4. Verify                 │
│                           │   │                           │
│ = The party who holds     │   │ Verifier = Only sees      │
│   the data                │   │ the result                │
│                           │   │                           │
│ ・Has secret inputs       │   │ ・Receives only the proof │
│ ・Sets secrets in         │   │ ・Sees only public inputs │
│   PartialWitness          │   │ ・Knows nothing about     │
│ ・data.prove(pw)          │   │   secret inputs           │
│   generates proof         │   │ ・data.verify(proof)      │
│                           │   │   → Ok / Error            │
└─────────────┬─────────────┘   └─────────────┬─────────────┘
              │                               │
              │  3. Send proof                │
              │  proof + public_inputs        │
              └──────────────►────────────────┘

Concrete Example: Private Database Update

┌───────────────────┐                    ┌───────────────────┐
│ Prover            │                    │ Verifier          │
│ (Data owner)      │                    │ (Auditor/Contract)│
└────────┬──────────┘                    └────────┬──────────┘
         │                                        │
         │ 1. Update the data                     │
         │    (e.g. change a balance)              │
         │    * This is secret                     │
         │                                        │
         │ 2. Generate ZK proof                   │
         │    prove(secret inputs)                │
         │    → obtain proof                      │
         │                                        │
         │ 3. Send proof ───────────────────────► │
         │    (contains no secret information)     │
         │                                        │
         │                                        │ 4. verify(proof)
         │                                        │    Public inputs only:
         │                                        │    ・old_root → new_root
         │                                        │    ・No idea what changed
         │                                        │    → Ok ✓
         │                                        │
         │                                        │ 5. Update state
         │                                        │    (record new_root)

👀 Point: What Is Public Or Not

Information	Prover knows	Verifier sees
What changed (value, position)	✅	❌
Merkle path (sibling nodes)	✅	❌
Old state root (old_root)	✅	✅
New state root (new_root)	✅	✅
Proof	✅	✅

The verifier only confirms that the state root transition is correct. It never learns what was updated. 🤫

⚙️ Setup: Plonky2 Basic Structure

All Plonky2 circuits starts from same 3 type definitions.

use plonky2::field::goldilocks_field::GoldilocksField;
use plonky2::plonk::config::PoseidonGoldilocksConfig;

const D: usize = 2;                    // Extension degree (always 2 in Plonky2)
type F = GoldilocksField;              // Finite field for arithmetic
type C = PoseidonGoldilocksConfig;     // Hash config (Poseidon over Goldilocks)

And all circuits follows the pattern of the same 3 steps

1. Build:   CircuitBuilder → Define constraints → builder.build() → CircuitData
2. Prove:   PartialWitness → Set secret inputs → data.prove(pw) → Proof
3. Verify:  data.verify(proof) → Ok(()) or Error

Let's make it run! 🚀

👋 Example 1: "Hello World" Circuit

This first circuit proves "I know two numbers that add up to a specific sum"

Sum is public (Verifier can see it). Two numbers are secret (Verifier can't see them).

use plonky2::{
    field::{goldilocks_field::GoldilocksField, types::Field},
    iop::{target::Target, witness::{PartialWitness, WitnessWrite}},
    plonk::{
        circuit_builder::CircuitBuilder,
        circuit_data::{CircuitConfig, CircuitData},
        config::PoseidonGoldilocksConfig,
        proof::ProofWithPublicInputs,
    },
};

const D: usize = 2;
type F = GoldilocksField;
type C = PoseidonGoldilocksConfig;

pub struct SimpleCircuit {
    data: CircuitData<F, C, D>,
    a: Target,      // Secret input slot
    b: Target,      // Secret input slot
    sum: Target,    // Made public
}

impl SimpleCircuit {
    pub fn new() -> Self {
        let config = CircuitConfig::standard_recursion_config();
        let mut builder = CircuitBuilder::<F, D>::new(config);

        // Create slots for secret inputs (called "Targets" in Plonky2)
        let a = builder.add_virtual_target();
        let b = builder.add_virtual_target();

        // Define constraint: sum = a + b
        let sum: Target = builder.add(a, b);

        // Make sum visible to the verifier
        builder.register_public_input(sum);

        // Compile the circuit
        let data = builder.build::<C>();
        Self { data, a, b, sum }
    }

    pub fn prove(&self, a: u64, b: u64) -> ProofWithPublicInputs<F, C, D> {
        let mut pw = PartialWitness::new();
        pw.set_target(self.a, F::from_canonical_u64(a));
        pw.set_target(self.b, F::from_canonical_u64(b));
        self.data.prove(pw).unwrap()
    }

    pub fn verify(&self, proof: ProofWithPublicInputs<F, C, D>) -> anyhow::Result<()> {
        Ok(self.data.verify(proof)?)
    }
}

Usage：

let circuit = SimpleCircuit::new();

// Prover: "I know two numbers that add up to 8"
let proof = circuit.prove(3, 5);

// Verifier: "Is this proof valid?" (can't see 3 and 5 — only sees 8)
assert_eq!(proof.public_inputs[0], F::from_canonical_u64(8));
assert!(circuit.verify(proof).is_ok());

🔍 What Happened?

Build Phase                    Prove Phase                   Verify Phase
┌────────────────┐           ┌────────────────┐          ┌──────────────┐
│ builder.add    │           │ pw.set_target  │          │ data.verify  │
│ (a, b)         │           │ (a=3, b=5)     │          │ (proof)      │
│                │           │                │          │              │
│ Define         │    →      │ Set secret     │    →     │ Verify proof │
│ constraint:    │           │ inputs         │          │              │
│ "sum = a + b"  │           │ → generate     │          │ Visible:     │
│                │           │   proof        │          │  sum=8 only  │
│ * No compute   │           │                │          │              │
│  Rules only    │           │ a=3, b=5 are   │          │ Hidden:      │
│                │           │ NOT in proof   │          │  a=3, b=5    │
└────────────────┘           └────────────────┘          └──────────────┘

Build Phase: builder.add(a, b) does not compute a + b. It creates a constraint that says "sum must equal a + b". The circuit is a template of rules.
Prove Phase: When the prover sets a=3, b=5, Plonky2 generates a cryptographic proof that these values satisfy the constraints.
Verify Phase: The verifier checks the proof. It sees sum=8 in the public inputs, but has no way of knowing a=3 or b=5.

Key point: A Target in Plonky2 is not a variable — it's a "wire" in the circuit. builder.add(a, b) computes nothing. It just connects two inputs to an addition gate.

🔗 Example 2: Hashchain — Proving Ordered Processing

Alright let's create something more practical now.
It proves that the final hash is calculated from the underlying items in the right processing order.

Concept

state_0 = hash(0)
state_1 = hash(state_0 || item_0)
state_2 = hash(state_1 || item_1)
state_3 = hash(state_2 || item_2)    ← Final hash (public)

Each step feeds the previous hash into the next.
If any item in the chain is modified, the final hash changes.
The prover proves the chain was computed correctly; the verifier only checks the final hash.

Proof and Verification Flow

  Prover                                   Verifier
  ──────                                   ────────

  Holds secret items:
  items = [item_0, item_1, item_2]
         ↓
  Set secret inputs in circuit:
  pw.set_target(items[0], item_0)
  pw.set_target(items[1], item_1)
  pw.set_target(items[2], item_2)
         ↓
  Generate proof:
  proof = data.prove(pw)
         ↓
  Send proof ──────────────────────────►  Receive proof
  (items are NOT included in proof)        ↓
                                       Extract final hash from
                                       proof.public_inputs
                                         ↓
                                       data.verify(proof) → Ok ✓
                                         ↓
                                       "Does the final hash match
                                        the expected value?"
                                       ← This is business logic (outside the circuit)

Code

use crate::utils::poseidon_hash_out::PoseidonHashOutTarget;

pub struct HashChainCircuit {
    pub data: CircuitData<F, C, D>,
    pub items: Vec<Target>,
}

impl HashChainCircuit {
    pub fn new(chain_length: usize) -> Self {
        let config = CircuitConfig::standard_recursion_config();
        let mut builder = CircuitBuilder::<F, D>::new(config);

        // Create a target (slot) for each item in the chain
        let items: Vec<Target> = (0..chain_length)
            .map(|_| builder.add_virtual_target())
            .collect();

        // Start from hash(0)
        let zero = builder.zero();
        let mut state = PoseidonHashOutTarget::hash_inputs(&mut builder, &[zero]);

        // Chain: for each item, state = hash(state || item)
        for item in &items {
            let inputs = [state.to_vec(), vec![*item]].concat();
            state = PoseidonHashOutTarget::hash_inputs(&mut builder, &inputs);
        }

        // Only expose the final hash — items stay secret
        builder.register_public_inputs(&state.to_vec());

        let data = builder.build::<C>();
        Self { data, items }
    }

    pub fn prove(&self, items: &[u32]) -> ProofWithPublicInputs<F, C, D> {
        let mut pw = PartialWitness::new();
        for (target, item) in self.items.iter().zip(items.iter()) {
            pw.set_target(*target, F::from_canonical_u32(*item));
        }
        self.data.prove(pw).unwrap()
    }
}

Usage：

// Build a circuit for a chain of length 3
let circuit = HashChainCircuit::new(3);

// Prove: "I processed items [1, 2, 3] in this exact order"
let proof = circuit.prove(&[1, 2, 3]);

// Verify: proof is valid and the final hash is in proof.public_inputs
assert!(circuit.data.verify(proof).is_ok());

💡 Why is this useful?

Imagine a database with 10,000 records.
The prover generates a single proof for the entire hash chain. The verifier can confirm that all records were processed correctly by checking just that one proof — no need to recalculate anything.

Usecase Example：

📋 Watch Log: Proof that logs are not manipulated
📦 Batch Process: Proof that bulk transactions are processed in the right order
🔄 Data Pipeline: Proof that the ETL process is processed correctly.

Circuit is nothing but a calculator — hash(hash(hash(0, item0), item1), item2) = final_hash.
The verifier judges whether the final hash matches the expected value.
This separation of concerns — mathematical rules inside the circuit, business logic outside — is the fundamental pattern of ZKP design.

🌳 Example 3: State Transition — Proves Merkle Tree Update

Many systems store data in a Merkle tree.
State Transition Proof proves "I updated a leaf of the tree and the value of the root has changed from old_root to new_root"

The verifier only sees the two root values.
Which leaf was changed, and what the old or new value was, is never revealed.

Merkle Tree Update Root

                    Merkle Tree (height=2, 4 leaves)

            Before Update                       After Update
          old_root                            new_root
           /    \                              /    \
         h01     h23                         h01     h23
        /   \   /   \                       /   \   /   \
      [10] [20] [30] [40]               [10] [99] [30] [40]
             ↑                                  ↑
          index=1                            index=1
          old_value=20                       new_value=99


  What the Prover knows          What the Verifier sees
  ────────────────────          ──────────────────────
  ・index = 1                   ・old_root
  ・old_value = 20              ・new_root
  ・new_value = 99              ・proof (cryptographic)
  ・Merkle path (sibling nodes)
  ・old_root, new_root

Code

pub struct StateTransitionCircuit {
    pub data: CircuitData<F, C, D>,
    old_leaf: Target,
    new_leaf: Target,
    index: Target,
    merkle_proof: MerkleProofTarget<Target>,
    old_root: PoseidonHashOutTarget,
    new_root: PoseidonHashOutTarget,
}

impl StateTransitionCircuit {
    pub fn new(height: usize) -> Self {
        let config = CircuitConfig::standard_recursion_config();
        let mut builder = CircuitBuilder::<F, D>::new(config);

        let old_leaf = builder.add_virtual_target();
        let new_leaf = builder.add_virtual_target();
        let index = builder.add_virtual_target();
        let merkle_proof = MerkleProofTarget::<Target>::new(&mut builder, height);
        let old_root = PoseidonHashOutTarget::new(&mut builder);
        let new_root = PoseidonHashOutTarget::new(&mut builder);

        // Constraint 1: old_leaf at this index produces old_root
        merkle_proof.verify::<F, C, D>(&mut builder, &old_leaf, index, old_root);

        // Constraint 2: compute root from new_leaf with same index and siblings → computed_new_root
        let computed_new_root =
            merkle_proof.get_root::<F, C, D>(&mut builder, &new_leaf, index);

        // Constraint 3: computed root must match the provided new_root
        computed_new_root.connect(&mut builder, new_root);

        // Public inputs: only the two roots
        builder.register_public_inputs(&old_root.to_vec());
        builder.register_public_inputs(&new_root.to_vec());

        let data = builder.build::<C>();
        Self { data, old_leaf, new_leaf, index, merkle_proof, old_root, new_root }
    }
}

The prover sets the witness (secret inputs):

fn prove(
    &self,
    tree: &mut MerkleTree<u32>,
    leaf_index: u64,
    old_value: u32,
    new_value: u32,
) -> ProofWithPublicInputs<F, C, D> {
    // Get old state
    let proof = tree.prove(leaf_index);
    let old_root = tree.get_root();

    // Update the tree
    tree.update_leaf(leaf_index, new_value.hash());
    let new_root = tree.get_root();

    // Set all secret witnesses
    let mut pw = PartialWitness::new();
    pw.set_target(self.old_leaf, F::from_canonical_u32(old_value));
    pw.set_target(self.new_leaf, F::from_canonical_u32(new_value));
    pw.set_target(self.index, F::from_canonical_u64(leaf_index));
    self.merkle_proof.set_witness(&mut pw, &proof);
    self.old_root.set_witness(&mut pw, old_root);
    self.new_root.set_witness(&mut pw, new_root);

    self.data.prove(pw).unwrap()
}

Usage:

// Create a Merkle tree with 4 leaves
let mut tree = MerkleTree::<u32>::new(2);  // height=2 → 4 leaves
tree.update_leaf(0, 10u32.hash());
tree.update_leaf(1, 20u32.hash());
tree.update_leaf(2, 30u32.hash());
tree.update_leaf(3, 40u32.hash());

let circuit = StateTransitionCircuit::new(2);

// Prove: "I changed leaf 1 from 20 to 99"
let proof = circuit.prove(&mut tree, 1, 20, 99);

// Verify: the root transition is correct
circuit.data.verify(proof).expect("should verify");

🤥 Can you deceive?

When a prover tries to cheat — e.g. claiming the old value was 999 when it was actually 20 — the Merkle path won't match the old_root, and proof generation itself fails.
It's impossible to generate a valid proof for a false statement. 🛡️

// Panics — you can't prove a lie
let result = std::panic::catch_unwind(|| {
    circuit.prove(&mut tree, 1, 999, 50);  // 999 ≠ actual value
});
assert!(result.is_err());

🧱 Overall Picture: How To Combine the Patterns

The three patterns above are useful on their own, but they become truly powerful when combined.

Combining the Patterns

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│  Prover (the party who holds the data)                         │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                         │
│                                                                │
│  Step 1: Prove individual operations                           │
│  ┌──────────────────────────────────────────────────────┐      │
│  │                                                      │      │
│  │  ┌────────────────┐  ┌────────────────┐              │      │
│  │  │ Operation A    │  │ Operation B    │  ...         │      │
│  │  │                │  │                │              │      │
│  │  │ State          │  │ State          │              │      │
│  │  │ Transition     │  │ Transition     │              │      │
│  │  │ (Merkle tree)  │  │ (Merkle tree)  │              │      │
│  │  └───────┬────────┘  └───────┬────────┘              │      │
│  │          │ proof_a           │ proof_b                │      │
│  └──────────┼───────────────────┼───────────────────────┘      │
│             │                   │                               │
│             ▼                   ▼                               │
│  Step 2: Chain the proofs together (hash chain)                │
│  ┌──────────────────────────────────────────────────────┐      │
│  │                                                      │      │
│  │  hash(hash(hash(0, proof_a), proof_b), ...)          │      │
│  │    = final_hash                                      │      │
│  │                                                      │      │
│  └─────────────────────────┬────────────────────────────┘      │
│                             │                                  │
│                     Final proof                                │
│                                                                │
└─────────────────────────────┬──────────────────────────────────┘
                              │
                              │  Send proof
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                                                                │
│  Verifier (auditor / smart contract / server)                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                   │
│                                                                │
│  verify(proof) → Ok ✓                                         │
│                                                                │
│  Visible:  old_root, new_root                                  │
│  Hidden:   individual operations, data values, account details │
│                                                                │
│  * Verifying just one proof cryptographically guarantees       │
│    the correctness of ALL operations                           │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Role of Each Pattern

Pattern	What it proves	Example use cases
Hash Chain	A sequence of data was processed in the correct order	Audit logs, batch processing, data pipelines
State Transition	A Merkle tree update was performed correctly	Database updates, balance changes, config changes

By combining them:

Prove each individual update with a state transition proof
Chain those proofs together with a hash chain
The verifier checks just one final proof to confirm the correctness of everything

🛠️ Practical Tips

1. 🏎️ Always Build in Release Mode

cargo test --release test_name

Debug mode is orders of magnitude slower. A proof that takes 2 seconds in release can take minutes in debug. 🐢→🐇

2. 🔁 The Circuit Pattern Is Always the Same

struct MyCircuit {
    data: CircuitData<F, C, D>,   // Compiled circuit
    // ... targets (wire slots)
}

impl MyCircuit {
    fn new() -> Self {            // Build phase: define constraints
        let mut builder = CircuitBuilder::<F, D>::new(config);
        // ... add constraints ...
        let data = builder.build::<C>();
    }

    fn prove(&self, ...) {        // Prove phase: set witness
        let mut pw = PartialWitness::new();
        // ... set values on targets ...
        self.data.prove(pw)
    }
}

3. 🔓🔒 Public vs. Secret Is Decided at Build Time

// This value stays secret (only the prover knows it)
let secret = builder.add_virtual_target();

// This value becomes public (verifier can see it)
builder.register_public_input(secret);  // Now it's public

4. ⚠️ Constraints Are Assertions, Not Computations

// This does NOT compute a + b at build time
// It creates a gate with the constraint: sum = a + b
let sum = builder.add(a, b);

// At prove time, if the witness values don't satisfy
// the constraint, proof generation fails

🎬 Wrapping Up

Zero-knowledge proofs aren't magic. They're constraint systems wrapped in clever cryptography. The circuit defines the rules, the prover fills in the secret inputs, and the verifier checks the proof without ever seeing those inputs.

With Plonky2:

🔗 Hash Chain — prove that data was processed in the correct order
🌳 State Transition — prove a database update without revealing what changed

The code patterns are consistent and composable. Once you understand CircuitBuilder → PartialWitness → prove → verify, you can stack simple circuits to build arbitrarily complex proof systems. 🧱✨

The code in this article uses the Plonky2 framework — a fast recursive SNARK system built on Poseidon hashing over the Goldilocks field.

React Best Practices in Cursor

Toshiya Matsumoto — Sun, 01 Feb 2026 08:29:48 +0000

Goal

Use React Best Practices quickly out of the box in Cursor.
While it's been written in many blogs for Claude Code but not for Cursor.
Let's make it work!

What is React Best Practices?

10+ years of React and Next.js optimization knowledge collection provided by Vercel.
https://vercel.com/blog/introducing-react-best-practices
Setting them in the skills or rules in the AI agents, it allows the agents to work by referencing to the documents during processing.

Procedure

Run the following command to install agent-skills under a specific project.

npx add-skill vercel-labs/agent-skills

Select Cursor and follow the instructions.

It installs the files automatically under

.cursor/skills/react-best-practices/

however, Cursor is not able to detect them just out of the box because the format in md files is different from what Cursor expects.

If you go to
Cursor -> Settings... -> Cursor Settings -> Rules,Skills,Subagents
you should be seeing No Skills are set over there.

In order for Cursor to read it, you need to convert it with /migrate-to-skills command.

Here is a prompt I used.

Conversion command is officially provided by Cursor.
See: https://cursor.com/docs/context/skills#migrating-rules-and-commands-to-skills

Type /migrate-to-skills in Agent chat

Takeaway

You need to run /migrate-to-skills for Cursor to read React Best Practices in Cursor.

🚀 Type Safety Across Layers: From Messy DBs to Clean Apps

Toshiya Matsumoto — Mon, 01 Sep 2025 12:54:28 +0000

Every developer knows this pain: your database says “nullable is fine,” but your app screams “absolutely not.”

👉 Example: An event table with a date column. The DB allows null (because some events don’t have confirmed dates yet).
But in your React UI? Showing an event with date: null is not only useless — it’s a bug waiting to happen.

This mismatch creates an annoying gap between your DB schema and your application layer. Ignore it, and you’ll end up patching with type casts that look fine… until runtime crashes say otherwise.

⚠️ The Wrong Way: Casting Your Troubles Away

We’ve all done this:

let x: unknown = 'hello';
console.log((x as string).length);

Sure, TypeScript stops complaining. But you’ve effectively turned off its seatbelt.
Type assertions bypass safety checks, leaving you with runtime landmines — the exact opposite of why you chose TypeScript in the first place.

✅ The Right Way: Type Guards

Enter Type Guards — TypeScript’s built-in way to narrow types safely.

Your DB or API DTO might look like this:

// event.dto.ts
type EventDto = {
  name: string;
  date: Date | null;
};

But your app layer needs stricter guarantees:

// event.ts
type Event = {
  name: string;
  date: Date;
};

Here’s how you bridge that gap:

function hasDate(event: EventDto): event is Event {
  return event.date !== null;
}

export function filterValidEvents(events: EventDto[]): Event[] {
  return events.filter(hasDate); <== here you go.
}

Now, your UI only ever sees events with valid dates. TypeScript enforces the rule, no assertions required.

🎁 Why This Pattern Wins

Type Safety: no unsafe casts, no silent failures.

Separation of Concerns: DBs stay flexible; apps stay strict.

Scalable: extendable to any nullable fields or DTOs.

🧩 Takeaway

Nullable data is inevitable when dealing with databases or APIs.
But instead of brute-forcing types, let Type Guards do the heavy lifting.

They let you:

Accept messy, real-world data from your DB.

Hand your app layer clean, reliable objects.

Keep TypeScript as your safety net, not your afterthought.

👉 Next time you hit the null wall, don’t cast — guard.

🎙️ Building Your Own Live Audio Waveform in React Native

Toshiya Matsumoto — Sun, 31 Aug 2025 09:46:11 +0000

🚀 Motivation

There aren’t many (if any!) well-known libraries out there for live audio recording data visualization with a waveform in React Native. So… why not just build one yourself? 😉

🎬 Demo

Pretty neat, right? Let’s dive in.

⚙️ Assumptions

Here’s the setup I used:

`react-native`: 0.79.5
`expo`: 53.0.17
`expo-av`: 15.1.7
`react-native-svg`: 15.12.1

👉 Run it with:

npx expo run:ios

🎤 1. Recording Process

1-1: Enable Metering

The magic trick 🪄 is setting isMeteringEnabled: true in recording.prepareToRecordAsync() from expo-av. This unlocks audio-level metering data (like dB values).

import { Audio, InterruptionModeIOS } from 'expo-av';

const { granted, status } = await Audio.requestPermissionsAsync();
await Audio.setAudioModeAsync({
  allowsRecordingIOS: true,
  playsInSilentModeIOS: true,
  staysActiveInBackground: true,
  interruptionModeIOS: InterruptionModeIOS.DuckOthers,
});

// Adjust as you like 🎛️
const recordingOptions = {
  android: {
    extension: '.m4a',
    outputFormat: Audio.AndroidOutputFormat.MPEG_4,
    audioEncoder: Audio.AndroidAudioEncoder.AAC,
    sampleRate: 44100,
    numberOfChannels: 2,
    bitRate: 128000,
  },
  ios: {
    extension: '.m4a',
    outputFormat: Audio.IOSOutputFormat.MPEG4AAC,
    audioQuality: Audio.IOSAudioQuality.HIGH,
    sampleRate: 44100,
    numberOfChannels: 2,
    bitRate: 128000,
    linearPCMBitDepth: 16,
    linearPCMIsBigEndian: false,
    linearPCMIsFloat: false,
  },
  web: {
    mimeType: 'audio/webm;codecs=opus',
    bitsPerSecond: 128000,
  },
};

const recording = new Audio.Recording();
await recording.prepareToRecordAsync({
  ...recordingOptions,
  isMeteringEnabled: true, // 🎯 enables audio-level metering
});
await recording.startAsync();

1-2: Poll the Recording State

Now let’s grab that juicy data 📊. Use the recording object and poll its status every 100ms.

// poll metering data every 100ms
const interval = setInterval(async () => {
  if (recording) {
    const status = await recording.getStatusAsync();
    if (status.isRecording && typeof status.metering === 'number') {
      setLevels((prev) => {
        const newLevels = [...prev, status.metering];
        // keep last 100 samples 🪣
        return newLevels.slice(-100);
      });
    }
  }
}, 100);

Example of status:
{"canRecord": true, "durationMillis": 602, "isRecording": true, "mediaServicesDidReset": false, "metering": -48.3475341796875}

The metering value is what you care about 🎧.

👉 Decibel scale basics:

0 dB   → loudest possible (max recording level) 🔊  
-160 dB → silence 🤫

I only keep the latest 100 values (slice(-100)) because… who wants a million bars on screen? 🙃

Time to visualize! 🎨

Okay let's visualise it.

📊 2. Waveform Visualization with SVG

You don’t need to be a math wizard 🧙 to draw waveforms. Just rectangles on a grid!

How it works:

1. Draw a rectangle for each audio sample 📦.

Height = based on audio volume.
Width = fixed.

2. Place it at the correct (x, y) coordinate.

Visual guide (yes, it’s really this simple 👇):

Converting dB → amplitude
Formula:

Math.pow(10, db / 20); // standard dB → amplitude

For easier handling, add +40 before conversion:

// Original level: -60dB（almost silence）
Math.pow(10, (-60 + 40) / 20) = Math.pow(10, -1) = 0.1

// Original level: -20dB（small sound volume）
Math.pow(10, (-20 + 40) / 20) = Math.pow(10, 1) = 10

// Original level: 0dB（maximum sound volume）
Math.pow(10, (0 + 40) / 20) = Math.pow(10, 2) = 100

Then scale it with normalizedLevel * height * 0.05.
(That 0.05 is just a tweak factor — adjust to taste! 🎚️)

And yes, we’ll use Rect from react-native-svg to draw the bars.

Codes

// Convert levels to SVG bars
  const width = 358;
  const height = 280;
  const barWidth = 3;
  const barSpacing = 1;
  const maxBarsCount = Math.floor(width / (barWidth + barSpacing));
  const halfHeight = height / 2;

  // Create vertical bars for each level
  const bars = levels.slice(-maxBarsCount).map((level, index) => {
    const normalizedLevel = Math.max(0, Math.pow(10, (level + 40) / 20));
    const barHeight = Math.max(1, normalizedLevel * height * 0.05);

    // Calculate position so bar extends equally above and below center
    const halfBarHeight = barHeight / 2;

    const startX = 0;
    const x = startX + index * (barWidth + barSpacing);
    const y = halfHeight - halfBarHeight;

    return (
      <Rect
        key={index}
        x={x}
        y={y}
        width={barWidth}
        height={barHeight}
        fill="#8E8E93"
        rx={1}
      />
    );
  });

  return (
    <View className="bg-white p-2 flex-1">
      <Svg height={height} width={width}>
        {bars}
      </Svg>
    </View>
  );

(levels.slice(-maxBarsCount), maxBarsCount removes the stale bars that overflows in the screen)

✅ Summary

With just expo-av + a little SVG magic 🪄, you can visualize live audio waveforms in React Native — no external libraries needed, no hassle.

Next time you record 🎤, make it look cool too.

🧼 Type-Safe Filtering in TypeScript: Handling Nullable Fields from Your Database

Toshiya Matsumoto — Fri, 30 May 2025 14:09:34 +0000

🌟 The Challenge: Bridging Type Safety Between DB and App Layers

In many real-world applications, the database schema often permits null values — for good reason. For instance, a date field in an event table might be intentionally left blank if the event date hasn’t been finalized yet.

However, your application layer — especially the part that renders UI — usually prefers clean, reliable data. If a date is null, you probably don’t want to show that event in the UI at all.

This creates a gap between what your database allows and what your application expects.

You might be tempted to solve this quickly with a forced type cast like:

let x: unknown = 'hello';
console.log((x as string).length);
But relying on type assertions skips safety checks and can lead to runtime bugs — exactly what TypeScript is meant to help you avoid.

🎯 The Solution: Using Type Guards

Instead of casting, a safer and cleaner solution is to use Type Guards — a TypeScript feature that allows you to narrow types in a type-safe way.

Let’s say your application pulls in event data like this:

// event.dto.ts - from database or external API
type EventDto = {
  name: string;
  date: Date | null;
};

But your UI layer expects all events to have a valid date:

// event.ts - for use within the app
type Event = {
  name: string;
  date: Date;
};

To filter out incomplete events, define a custom type guard:

function hasDate(event: EventDto): event is Event {
  return event.date !== null;
}

Then you can filter safely and TypeScript will infer the correct type:

export function filterValidEvents(events: EventDto[]): Event[] {
  return events.filter(hasDate);
}

Now your UI layer will only receive events that have confirmed dates — and TypeScript will enforce this guarantee for you.

✅ Benefits

Type safety without unnecessary assertions.

Separation of concerns: the DB layer can remain flexible, while the app layer stays strict.

Scalability: you can extend this pattern to other nullable fields and DTOs.

🧠 Final Thoughts

Dealing with partial or nullable data from external sources is inevitable. But with TypeScript’s type guards, you don’t have to compromise safety or clarity.
Embrace the gap between layers — and bridge it elegantly.

🚀 Seamless Data Magic: From Notion to Database with MCP Server & AI Agents

Toshiya Matsumoto — Sat, 17 May 2025 02:04:14 +0000

🎯 The Goal

Build a seamless bridge between non-engineering contributors managing data in Notion and engineers who need that data formatted for database insertion.

🌟 The Challenge

Values like "Japan" or "Tokyo" don't match the foreign keys in different tables.

🛠 Tech Stack Overview

Notion: Used as the collaborative data entry platform for non-engineers.
MCP Server: Bridges Notion and external tools, enabling structured data retrieval via API.
Cursor Agent: An AI-powered agent that automates data transformation, semantic inference, and prompt execution.
TypeScript: Ensures type safety and robust data handling throughout the automation scripts.

🌟 The Solution

🚀 Let's ask Cursor Agent to infer the semantic data to be the foreign keys in one prompt!

🔗 Step 1: Integrate Notion MCP Server to Retrieve Structured Event Data

Non-engineers created and updated event entries directly in Notion—no devs required.

To extract and structure that data:
✅ I used the Notion MCP Server via Cursor Agent.

// .cursor/mcp.json
{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer {YOUR_NOTION_API_KEY}\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

This allows you to retrieve structured data from Notion in AI Agent's context.

🧠 Step 2: Let Cursor Agent to Infer Semantic Foreign Keys

Ask AI Agent to fetch the master data from the API with curl command in prior, and to infer the semantic foreign keys in each row.

The data in Notion

// countries table
-----------------
| id | name     |
-----------------
| 1  | Japan    |
| 2  | USA      |
| 3  | Germany  |
-----------------
// events table
-----------------------------------------------
| id | name         | location   | country_id |
-----------------------------------------------
| 1  | Tech Expo    | Tokyo, JPN | null       |
| 2  | Art Summit   | LA, USA    | null       |
| 3  | Music Fest   | Berlin, DE | null       |
-----------------------------------------------

Asking the Agent to infer the country_id in each row from the semantic location names to match the foreign keys from data you already fetched via API.

Ultimately the data should look like this in the Agent's context 👏

-----------------------------------------------
| id | name         | location   | country_id |
-----------------------------------------------
| 1  | Tech Expo    | Tokyo, JPN | 1          |
| 2  | Art Summit   | LA, USA    | 2          |
| 3  | Music Fest   | Berlin, DE | 3          |
-----------------------------------------------

🧠 Step 3: Ask Agent to convert the data to the payload for the events table

Finally Ask the Agent to convert the data to the payload for the events table following the schema defined in the schema.json file you put.

Voila, you can now get the payload ready to be inserted into the events table!

// ./output/events.json
{
  "name": "Tech Expo",
  "location": "Tokyo, JPN",
  "country_id": 1
},
{
  "name": "Art Summit",
  "location": "LA, USA",
  "country_id": 2
},
{
  "name": "Music Fest", 
  "location": "Berlin, DE",
  "country_id": 3
}

Prompt I used

// /prompt/create-events.md
### Prompt Instructions

## For Events

- Retrieve the rows in the Events DB, sorted by ascending startDateTime in Notion via notionGeodeworkApi in MCP settings.
- Generate the payload for the events table according to the schema defined in @schema.ts.
- Use the following API to fetch country data:

  API Endpoint: {NEXT_PUBLIC_SUPABASE_URL}/rest/v1/countries
  API Key: {NEXT_PUBLIC_SUPABASE_ANON_KEY}

  Sample curl:
  curl -H "apikey: <API_KEY>" "<API_ENDPOINT>"

- Replace the `country_id` in each row with the foreign key from the country table.

I stored the prompt in the prompt/create-events.md file so that everybody can use and reproduce the process easily.

📦 Conclusion

Successfully extracted the structured data from Notion and converted it to the payload for the events table with the help of AI Agent.

I actually integragted the process to insert the data with drizzle-kit and supabase all in one go, but I'll write about it in another blog post!

Github Actions with Vercel in 2024

Toshiya Matsumoto — Mon, 13 Jan 2025 14:07:05 +0000

When you already have the app working on Vercel but you want to integrate Github Actions on top of it. Here's the right place to check.

Vercel

You need the following data from Vercel dashboard.

ORG_ID Go to the top page > Settings > Team ID. Note that it's not under individual project page.

The URL you visit is like thishttps://vercel.com/{your_account_name}s-projects/~/settings

PROJECT_ID
Go to project page > Settings > Team ID > Project ID
VERCEL_TOKEN
Go to project page > Settings > Environment Variables
Enter VERCEL_TOKEN as a key and the arbitrary value.

Github

Go to the Github project page > Settings > Secrets and variables > Actions > Repository secrets > New repository secret

and set the ones you copied from the Vercel above and others that are needed respectively such as dotenv values depending on your implementation.

Code

Create .github/workflows/workflow.yml

name: Github Auto Deploy

on:
  push:
    branches:
      - main

env:
  VERCEL_ORG_ID: ${{ secrets.ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Bun Runtime
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install Dependencies
        run: bun install

      - name: Run Unit Tests
        run: bun unit:test

      - name: Install Playwright Browsers
        run: bunx playwright install --with-deps

      - name: Run E2E Tests
        run: bunx playwright test
        env:
          CI: true
          NODE_ENV: test
          CTF_MGMT_API_ACCESS_TOKEN: ${{ secrets.CTF_MGMT_API_ACCESS_TOKEN }}
          CTF_SPACE_ID: ${{ secrets.CTF_SPACE_ID }}
          CTF_CDA_ACCESS_TOKEN: ${{ secrets.CTF_CDA_ACCESS_TOKEN }}

      - name: Install Vercel CLI
        run: bun install -g vercel@latest

      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Page can't be indexed in Google Search Console

Toshiya Matsumoto — Thu, 09 Jan 2025 14:59:03 +0000

Problem

My personal website pages built with NextJs v14.x.x hosted by Vercel were not indexed at all for ages somewhere down the line ... very shocking...

Details in Google Search Console

When you visit Sitemap page, it says Couldn't fetch.
When I visited URL Inspection page, it says Site-wide availability issues.

Investigating Process

However I could see the content https:mypage/sitemap.xml on browser.

curl -I https:mypage/sitemap.xml shows 200 response status properly.

Then I checked more details in Site-wide availability issues on https://support.google.com/webmasters/answer/9012289#will_i_be_indexed&zippy=%2Csite-wide-availability-issues

and then found this one:

Robots.txt unreachable: Google won't crawl a website if the robots.txt file is present but not reachable. You can check your robots.txt availability in the Crawl Stats report.

Then I realised thathttps:mypage/robots.txt returns 500 status despite the fact that I didn't prepare the robots.txt in my NextJS directory.

Running production mode in NextJS hides the error details while dev mode shows you the details.

Voila, my poor error handling returns 500 status even though /robots.txt does not exist which in turn confused Google Indexer and put it the label of Not Indexable Page.

The case is closed.

Crypto/Web3 Scammers in LinkedIn 😈

Toshiya Matsumoto — Sun, 17 Nov 2024 08:25:36 +0000

I received quite a few headhunting DM in the LinkedIn from 😈scammers😈 recently.

I've played around with them for a bit to see what they are like.

Who?

They are hacked accounts. Their professions I've met are

Food Consultant
Manager at Hotel and Restaurant
Hotel Bartender
CIO in an IT corporation

What They Offer

They offer an opportunity for Engineer role in web3.0/crypto space like the followings:

Exciting opportunity to develop a Web3 food token website.
DEX project, but currently lacking the necessary hands to develop it successfully.
Platform for trading cryptocurrencies referred to as a Dex

Also they have

Github project
Job Description (using Google Document)

How They Trap You

They commonly shared the Github projects with half way done or as an assignment to measure your engineering skills, or whatever reasons they are, and attempted to make you download them.

I've seen somewhere in the LinkedIn thread but it seems those projects have a virus library and designed to skim your important data when you run it in your local.

How To Detect It 🤡

Check their professions in their LinkedIn page. None of them had any association with IT startup or crypto. Since the accounts are hacked and impersonated, they are real person and even have good reputations but have a deep breath first, and try to logically connect the dots.
They responds to you quite fast in 24 hours regardless of where they live.
Contributors in the Github account are beginners despite the fact that their main page is very decorative with prototype projects.
Unprofessional traces somewhere. For example this person's name does not start with the capital letter, although their written text looks professional overall probably due to with AI tools.

Thoughts

As you can see, making up combining Food Consultant and "food token", with the jargon such as react, node, web3 and solidity, they are not just a random scammers with lack of IT knowledge.

I guess they use AI tools to generate the most seemingly adequate questions from your CV/Resume.

Lastly

It seems reasonable to reach the conclusion that they are fraud on the spot but if you are desperate or really looking for an opportunity for your dream, it is fair enough for you to believe it.

I wish this article helps.

In React useMemo And useState From Design Philosophy Perspective.

Toshiya Matsumoto — Thu, 14 Nov 2024 14:58:15 +0000

What is useState in React?

As stated in the official documentation,

useState is a React Hook that lets you add a state variable to your component.

To fully understand the differences from useMemo, however, it’s helpful to first consider React's design philosophy ⛩️

React's design philosophy: Declarative UI

React’s declarative UI principle ensures re-renders and reconstructs the UI on each user interaction to ensure idempotency, which makes building applications simpler and more predictable than with imperative UI principles.

While React’s Virtual DOM optimises updates by changing only the parts that differ, useState is central to managing these changes.

Tradeoff

However, frequent re-renders can be costly when the codebase involves intensive computations or heavy rendering.
To address this, useMemo becomes essential. According to the official documentation,

What is useMemo in React?

useMemo is a React Hook that lets you cache the result of a calculation between re-renders.

This feature is valuable when dealing with computationally expensive tasks, as useMemo can bypass re-computation by retrieving data from the cache.

useMemo or useState

That said, there’s ongoing debate on the optimal use of useMemo, as it involves evaluating dependencies and using memory, which can add overhead. The official guidance notes,

In general, unless you’re creating or looping over thousands of objects, it’s probably not expensive."

More on this topic is available here: https://react.dev/reference/react/useMemo#how-to-tell-if-a-calculation-is-expensive

They are kind enough to share how to measure the time spent on the function execution.

console.time('filter array');
const visibleTodos = filterTodos(todos, tab);
console.timeEnd('filter array');

Pitfall (Digressing Slightly)

Lastly, an important consideration: useMemo compares dependencies with Object.is(), meaning changes within the same object reference will not trigger re-evaluation.

This is a key pitfall to keep in mind.

Take Aways

React employs the design philosophy Declarative UI which takes it granted that some functions are called more than necessary at the expense of simple code experience.
In order to reduce the overhead useMemo is here for you.

Thank you!

Method Chain: filter().map() is inefficient?

Toshiya Matsumoto — Mon, 04 Nov 2024 14:04:38 +0000

Method Chaining

You may have seen the code using Array.prototype.filter() and Array.prototype.map() to edit and remove the value in Array data in Javascript

For example:

[1,2,3]
.map((mapped) => mapped + 1)
.filter((filtered) => filtered > 1)

Question

I was always wondering if such a method chaining iterates the value in array at each iteration or v8 engine perhaps optimises the operation by performing data aggregation under the hood.

So I conducted a small research.

How?

Using console.time and console.timeEnd and measured the average execution time in 10 times with and without Method Chain.
I used Chrome browser for the investigation.

console.time('Filter Execution Time')
// YOUR CODE
console.timeEnd('Filter Execution Time')

Result: Method Chaining does not aggregate the operation.

-	Method Chain(A)	No Method Chain(B)	Aggregate Logic(C)
Iterate 10000000 values	4656 ms	4733 ms	169 ms
Iterate 100000 values	27 ms	24 ms	4 ms

As you can see, the result with/without Method Chain did not reveal much difference, while aggregating logic hit the way faster results.

Code-A. Use Method Chaining with map() and filter()

console.time('Filter Execution Time')
const result = new Array()
.fill(1).map((e) => e + 1)
.filter((e) => e !== 1)
console.timeEnd('Filter Execution Time')

Code-B. Separate map() and filter() (No Method Chaining)

console.time('Filter Execution Time')
const mapResult = new Array().fill(1).map((e) => e + 1)
const result = mapResult.filter((e) => e !== 1)
console.timeEnd('Filter Execution Time')

Code-C. Aggregate logic

console.time('Filter Execution Time')
const result = []
new Array().fill(1).forEach((e) =>  {
    if (e !== 1) result.push(e)
})
console.timeEnd('Filter Execution Time')

But Method Chain is handy isn't it?

For those who think so, I made the chart at every number of iteration from 100 up to 100,000 under the the Code Pattern A, B, and C by counting the average time by milliseconds in 10 times, likewise as the above.

Findings

There are not much difference when the number of iteration is not large such as 100 - 1,000 anyway.
It is going to matter when the number of iteration grows exponentially such as 1,000,000.

Conclusion

Method Chaining does not aggregate the operation while the difference of the results widens as the number of iteration grows exponentially.

Hence I think it's fair to say that when the number of iteration is small, it's ok to use method chain to gain the advantage of its handiness, on the other hand, if you deal with a large number of data, you should consider the algorithm carefully without the method chain.

Thanks for reading!

Handling Object Values in React useState()

Toshiya Matsumoto — Mon, 14 Oct 2024 07:22:16 +0000

What is useState in React?

useState is a React hook that allows functional components to manage and update local state.

But you have to make sure to update the state through useState(), not directly mutate the state itself.

Basic Example of `useState`

const [count, setCount] = useState(0);

setCount(count++)
console.log(count) // 1

The Problem with `object` state in `useState`

Javascript has two places where it can store the data: stack and heap, and it relates to the story of primitive values and references.

`primitive values` and `references`

stack is used in Javascript to store static data such as primitive values (strings, numbers, booleans, undefined, and null) in which the size of the data is fixed, while
heap is used to store the dynamic data such as references (objects and functions).

The values of primitive values are simply stored in the stack that's it, while the content of references itself is stored in heap referenced from the stack.

This creates a situation where a newly assigned value that references the existing object is interpreted as identical.

Lets's look at an incorrect example👺:

const [state, setState] = useState([1,2]);

const temp = state
temp.push(3)
useState(temp)

Because temp and state both reference the same values in the heap, they are effectively identical. This violates the rule of useState, which requires a new object or value to trigger a re-render. 😇

How to solve it?

⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️⛩️

Spread Syntax

[...[]]

helps you create a separate copy of the value in heap.

const a = [1,2]
const b = a
console.log(Object.is(a,b)) // true

const c = [...a]
console.log(Object.is(a,c)) // false

voila 😀

const [state, setState] = useState([1,2])
const temp = [...state].push(3)
setData(temp);

Now, the value temp is different from the original object, ensuring that it no longer shares the same reference as state.

Another pitfall `in-place` function

The in-place functions such as sort() modifies the data in place, without creating a separate copy of the data structure.

a = [1,3]
a.sort((b,c) => c-b)
console.log(a) // => [3,1]

As you can see, the values in a has changed.

Again here is an incorrect example👺:

const [state, setState] = useState([])

const sortOrder = () => {
    state.sort((a, b) => a-b)
    setState(state);
  }

state is mutated against the rule. 😇

So here is the solution with spread syntax.

const [state setState] = useState([])

const sortOrder = () => {
   const newState = [...data].sort((a, b) => a-b)
    setState(newState);
  }

but wait, before reaching to the conclusion with spread syntax, remember to look up the documentation to to catch up the latest updates.

Check a document

There is a chance that the functions is updated.

For example, toSorted() is newly introduced in 2023 that returns a copying version of the input data 🌅

const [state, newState] = useState([])

const sortOrder = () => {
   const newState = state.toSorted((a, b) => a-b)
   newState(newState);
  }

AI is not good at catching up the latest information so this traditional methodology is still worth it!

Conclusion

Let's use spread syntax [...[]]
but remember to consult the documentation as well.

Reference

https://felixgerschau.com/javascript-memory-management/
https://react.dev/reference/react/useState