📁 Full source code: midnight-apps/shielded-token

Target audience: Developers

This tutorial walks you through building a complete shielded token DApp on the Midnight network. You will deploy a Compact smart contract, implement operations such as minting, transferring, and burning tokens, generate zero-knowledge proofs, and build a React frontend that lets users interact with shielded tokens in the browser.

Shielded tokens differ from unshielded tokens in that all balances and amounts remain hidden from on-chain explorers. Only the wallet owner can decrypt their balances locally. The smart contract proves correctness via zero-knowledge proofs without revealing any sensitive values. Public state variables such as totalSupply and totalBurned track aggregate metrics, while individual coin values, recipients, and the transaction graph remain private.

Prerequisites

• Node.js installed (v20+)
• A Midnight Wallet (1AM or Lace)
• Some Preprod faucet NIGHT tokens
• A package.json with the needed packages
  • @midnight-ntwrk/compact-runtime
  • @midnight-ntwrk/dapp-connector-api
  • @midnight-ntwrk/ledger-v8
  • @midnight-ntwrk/midnight-js-contracts
  • @midnight-ntwrk/midnight-js-dapp-connector-proof-provider
  • @midnight-ntwrk/midnight-js-fetch-zk-config-provider
  • @midnight-ntwrk/midnight-js-indexer-public-data-provider
  • @midnight-ntwrk/midnight-js-level-private-state-provider
  • @midnight-ntwrk/midnight-js-network-id
  • @midnight-ntwrk/midnight-js-types
  • @midnight-ntwrk/wallet-sdk-address-format
  • react, react-dom, react-router-dom, zustand, semver

1. Building and compiling the smart contract

The smart contract for shielded tokens resides in contracts/Token.compact. It manages public counters such as totalSupply and totalBurned, and uses the Zswap shielded token primitives to create, transfer, and destroy private coins.

Public ledger state

Create these two essential public counters to track the token lifecycle:

// --- Public ledger state ---

export ledger totalSupply: Uint<64>;
export ledger totalBurned: Uint<128>;

These two are public: they do not contain any sensitive or private information. They only track totalSupply and totalBurned; the ownership of the shielded tokens remains private.

Witnesses for private data

The Compact smart contract for shielded tokens requires a source of randomness for coin nonces. Each shielded coin needs to have a unique nonce so its commitment is distinct:

// --- Witnesses for private/off-chain data ---

witness localNonce(): Bytes<32>;

For every mint, a fresh random 32-byte nonce is generated. It lives in the TypeScript layer and is bound into the zero-knowledge proof generation.

Minting a shielded token

The first circuit is createShieldedToken. It mints a new shielded token with a unique nonce and sends it to a recipient:

// --- Minting to self ---

export circuit createShieldedToken(
    amount: Uint<64>,
    recipient: Either<ZswapCoinPublicKey, ContractAddress>
): ShieldedCoinInfo {
    const domain = pad(32, "shielded:token");
    const nonce = localNonce();
    const coin = mintShieldedToken(
        disclose(domain),
        disclose(amount),
        disclose(nonce),
        disclose(recipient)
    );
    totalSupply = (totalSupply + disclose(amount)) as Uint<64>;
    return coin;
}

mintShieldedToken is a ledger primitive. It creates a new shielded token commitment. The domain separates this token from others on the network, and the nonce ensures its uniqueness.

Note: disclose() is required because the ledger needs to see the recipient on-chain in order to route the output correctly. Only the recipient can decrypt the actual amount.

The atomic mint-and-send pattern

mintAndSend is the most important circuit in this smart contract. It atomically mints a coin and forwards it to a recipient in one transaction without any Merkle qualification needed:

// --- Minting and sending ---

export circuit mintAndSend(
    amount: Uint<64>,
    recipient: Either<ZswapCoinPublicKey, ContractAddress>
): ShieldedSendResult {
    const domain = pad(32, "shielded:token");
    const nonce = localNonce();

    // Mint to contract first
    const coin = mintShieldedToken(
        disclose(domain),
        disclose(amount),
        disclose(nonce),
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );

    // Immediately forward — no Merkle qualification needed
    const result = sendImmediateShielded(
        disclose(coin),
        disclose(recipient),
        disclose(amount) as Uint<128>
    );

    totalSupply = (totalSupply + disclose(amount)) as Uint<64>;
    return result;
}

sendImmediateShielded spends a token that was created in the same transaction. The kernel pairs the mint and spend internally using mt_index: 0, meaning no on-chain Merkle path lookup is needed.

The ShieldedSendResult contains two fields:

• sent: the coin that was sent to the recipient
• change: a Maybe<ShieldedCoinInfo> containing any remainder

The Merkle tree constraint

To understand why tokens need to be committed to the on-chain Merkle tree: freshly minted shielded tokens are not immediately spendable in an independent transaction. Thus the exported circuit transferShielded requires QualifiedShieldedCoinInfo (which includes mt_index), while the mintAndSend circuit bypasses this by using sendImmediateShielded.

export circuit transferShielded(
    coin: QualifiedShieldedCoinInfo,
    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
    amount: Uint<128>
): ShieldedSendResult {
    const result = sendShielded(disclose(coin), disclose(recipient), disclose(amount));
    return result;
}

sendShielded requires a Merkle inclusion proof from coin.mt_index to the current Zswap root. The prover must have this path, and the verifier checks it against the on-chain root. If the wallet’s local Zswap state is even slightly out of sync with the verifier’s expected root, then the proof fails.

This is a trade-off to be considered carefully depending on your use case(s):

Burning shielded tokens

The depositAndBurn circuit burns the received coin in the same transaction:

export circuit depositAndBurn(
    coin: ShieldedCoinInfo,
    amount: Uint<128>
): ShieldedSendResult {
    receiveShielded(disclose(coin));
    const burnAddr = shieldedBurnAddress();
    const result = sendImmediateShielded(
        disclose(coin),
        burnAddr,
        disclose(amount)
    );
    totalBurned = (totalBurned + disclose(amount)) as Uint<128>;
    return result;
}

receiveShielded declares that the smart contract receives the coin. The wallet’s balancer adds a matching input automatically. shieldedBurnAddress() is a ledger constant on the Midnight network; coins sent there are permanently removed from the circulating supply.

Important Caveat: sendImmediateShielded sends change to kernel.self() (the smart contract). Thus a partial burn leaves a contract-owned shielded output that is not tracked elsewhere. The UI enforces full burn by default to avoid this.

Additional circuits

nextNonce is used to derive a deterministic nonce sequence:

export circuit nextNonce(index: Uint<128>, currentNonce: Bytes<32>): Bytes<32> {
    return evolveNonce(disclose(index), disclose(currentNonce));
}

evolveNonce is used to derive the next nonce from a counter index and current nonce; it’s useful for applications requiring deterministic nonce sequences.

View the full contract in Token.compact.

Compiling the compact smart contract

Install the Compact compiler:

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

Then compile:

compact compile contracts/Token.compact src/contracts

This will generate files and folders such as keys and zkir, all of which are essential for deploying and interacting with the smart contract later.

Note: You can skip this step if you cloned the repo, as compiled artifacts are already included. However, if you recompile, you will not be able to use the deployed smart contract because the old verification keys will no longer match.

2. React UI implementation

Using the smart contract-generated artifacts in src/contracts from the frontend involves a few steps:

Wallet provider setup

Midnight wallets inject a global window.midnight object before page load.

Start with the constants:

// src/hooks/wallet.constants.ts
export const COMPATIBLE_CONNECTOR_API_VERSION = '4.x';
export const NETWORK_ID = 'preprod';

Note: COMPATIBLE_CONNECTOR_API_VERSION is '4.x', not '^4.0.0'. The '4.x' semver range accepts any 4.x.y version the wallet reports.

The detection function enumerates window.midnight, validates each entry, and filters by version.

// src/hooks/useWallet.ts
export function getCompatibleWallets(): InitialAPI[] {
  if (!window.midnight) return [];

  return Object.values(window.midnight).filter(
    (wallet): wallet is InitialAPI =>
      !!wallet &&
      typeof wallet === 'object' &&
      'apiVersion' in wallet &&
      semver.satisfies(wallet.apiVersion, COMPATIBLE_CONNECTOR_API_VERSION)
  );
}

When wallet.connect(networkId) is called, it triggers the wallet extension connection flow.

// src/hooks/useWallet.ts
connect: async (networkId = NETWORK_ID) => {
  const { wallet } = get();
  if (!wallet) {
    set({ error: 'No wallet selected' });
    return;
  }

  set({ isConnecting: true, error: null });

  try {
    const connectedApi = await wallet.connect(networkId);
    const status = await connectedApi.getConnectionStatus();

    if (status.status !== 'connected') {
      throw new Error(`Wallet status: ${status.status}`);
    }

    const config = await connectedApi.getConfiguration();
    const shielded = await connectedApi.getShieldedAddresses();
    const unshielded = await connectedApi.getUnshieldedAddress();
    const dustAddr = await connectedApi.getDustAddress();

    set({
      connectedApi,
      isConnected: true,
      config,
      addresses: {
        shieldedAddress: shielded.shieldedAddress,
        shieldedCoinPublicKey: shielded.shieldedCoinPublicKey,
        shieldedEncryptionPublicKey: shielded.shieldedEncryptionPublicKey,
        unshieldedAddress: unshielded.unshieldedAddress,
        dustAddress: dustAddr.dustAddress,
      },
      balances: {
        shielded: {},
        unshielded: {},
        dust: { balance: 0n, cap: 0n },
      },
    });

    localStorage.setItem('midnight_last_wallet', wallet.rdns);
  } catch (err) {
    set({
      error: err instanceof Error ? err.message : 'Connection failed',
      isConnected: false,
      connectedApi: null,
    });
  } finally {
    set({ isConnecting: false });
  }
},

Or if you want, you can use a starter I built, dapp-connect.

First, start by cloning the repository.

git clone https://github.com/0xfdbu/midnight-apps.git

Run the starter and install dependencies.

cd midnight-apps/dapp-connect
npm install
npm run dev

Building the providers and the TypeScript API

Before continuing, you need a helper function to build the providers.

// src/hooks/wallet/services/providers.ts

import type { ConnectedAPI } from '@midnight-ntwrk/dapp-connector-api';
import type { MidnightProviders } from '@midnight-ntwrk/midnight-js-types';
import { INDEXER_HTTP, INDEXER_WS, CONTRACT_PATH, PRIVATE_STATE_PASSWORD } from '../wallet.constants';
import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
import { FetchZkConfigProvider } from '@midnight-ntwrk/midnight-js-fetch-zk-config-provider';
import type { ZKConfigProvider } from '@midnight-ntwrk/midnight-js-types';
import { dappConnectorProofProvider } from '@midnight-ntwrk/midnight-js-dapp-connector-proof-provider';
import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
import { toHex, fromHex } from '@midnight-ntwrk/midnight-js-utils';
import { Transaction, CostModel } from '@midnight-ntwrk/ledger-v8';

Provider builder function:

export async function buildProviders(
  connectedApi: ConnectedAPI,
  coinPublicKey: string,
  encryptionPublicKey: string,
  contractAddress?: string,
  existingPrivateStateProvider?: any
): Promise<MidnightProviders> {
  const fetchProvider = new FetchZkConfigProvider(
    `${window.location.origin}${CONTRACT_PATH}`,
    fetch.bind(window)
  );
  const zkConfigProvider = new ArtifactValidatingProvider(fetchProvider);

  const privateStateProvider = existingPrivateStateProvider || levelPrivateStateProvider({
    accountId: coinPublicKey,
    privateStoragePasswordProvider: () => PRIVATE_STATE_PASSWORD,
  });

  if (contractAddress) {
    privateStateProvider.setContractAddress(contractAddress);
  }

  return {
    privateStateProvider,
    publicDataProvider: indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS),
    zkConfigProvider,
    proofProvider: await dappConnectorProofProvider(connectedApi, zkConfigProvider, CostModel.initialCostModel()),
    walletProvider: {
      getCoinPublicKey: () => coinPublicKey,
      getEncryptionPublicKey: () => encryptionPublicKey,
      async balanceTx(tx: any, _ttl?: Date): Promise<any> {
        const serializedTx = toHex(tx.serialize());
        const received = await connectedApi.balanceUnsealedTransaction(serializedTx);
        return Transaction.deserialize('signature', 'proof', 'binding', fromHex(received.tx));
      },
    },
    midnightProvider: {
      async submitTx(tx: any): Promise<string> {
        await connectedApi.submitTransaction(toHex(tx.serialize()));
        const txIdentifiers = (tx as any).identifiers();
        return txIdentifiers?.[0] ?? '';
      },
    },
  };
}

Now proceed to create the hook for the TypeScript API. These are some of the essential imports for the API

// src/hooks/wallet/services/api.ts

import type { ConnectedAPI } from '@midnight-ntwrk/dapp-connector-api';
import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
import { buildProviders } from './providers';
import { getContract, createInitialPrivateState } from './contract';
import { INDEXER_HTTP, INDEXER_WS, CONTRACT_PATH, PRIVATE_STATE_ID, PRIVATE_STATE_PASSWORD } from '../wallet.constants';
import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
import { CompiledContract } from '@midnight-ntwrk/compact-js';

Deploying the smart contract

deployTokenContract builds a CompiledContract instance, binds the localNonce witness, attaches the compiled ZK artifacts, and then calls deployContract with the providers:

// src/hooks/wallet/services/api.ts

export async function deployTokenContract(
  connectedApi: ConnectedAPI,
  coinPublicKey: string,
  encryptionPublicKey: string
): Promise<string> {
  const { deployContract } = await import('@midnight-ntwrk/midnight-js-contracts');
  const privateStateProvider = await ensurePrivateState(coinPublicKey, 'tmp-deploy');
  const providers = await buildProviders(connectedApi, coinPublicKey, encryptionPublicKey, undefined, privateStateProvider);

  const contractModule = await import(`${CONTRACT_PATH}/contract/index.js`);
  const cc: any = CompiledContract.make('shielded-token', contractModule.Contract);
  const withWitnesses = (CompiledContract as any).withWitnesses({
    localNonce: ({ privateState }: any): [any, Uint8Array] => {
      const nonce = crypto.getRandomValues(new Uint8Array(32));
      return [privateState, nonce];
    },
  });
  const withAssets = (CompiledContract as any).withCompiledFileAssets(CONTRACT_PATH);
  const compiledContract = withWitnesses(withAssets(cc));

  const deployed = await deployContract(providers as any, {
    compiledContract,
    privateStateId: PRIVATE_STATE_ID,
    initialPrivateState: createInitialPrivateState(),
    args: [],
  } as any);

  const address = deployed.deployTxData.public.contractAddress;
  localStorage.setItem('shielded_token_contract', address);
  return address;
}

Wire deployTokenContract into the frontend

// src/pages/Deploy.tsx
// Other imports
import { useWalletStore } from '../hooks/useWallet';
import { deployTokenContract } from '../hooks/wallet/services/api';

  const handleDeploy = async () => {
    if (!connectedApi || !addresses?.shieldedCoinPublicKey || !addresses?.shieldedEncryptionPublicKey) {
      setError('Wallet not fully connected');
      return;
    }
    setStatus('pending');
    setError(null);

    try {
      const addr = await deployTokenContract(
        connectedApi,
        addresses.shieldedCoinPublicKey,
        addresses.shieldedEncryptionPublicKey
      );
      setContractAddress(addr);
      setStatus('success');
    } catch (err) {
      console.error('[Deploy] Error:', err);
      setError(err instanceof Error ? err.message : 'Deployment failed');
      setStatus('error');
    }
  };

The smart contract address is then saved to localStorage.

Note: The same API pattern used in deployTokenContract will be used for calling the compiled circuits. View full API api.ts

Minting tokens

The Mint page has two modes: Mint to Self and Mint & Send.

Mint to Self calls createShieldedToken and sends the minted coin into the user’s shielded coin public key:

const selfRecipient = {
  is_left: true,
  left: { bytes: parseKeyBytes(addresses.shieldedCoinPublicKey) },
  right: { bytes: ZERO_BYTES32 },
};

const result = await callCreateShieldedToken(
  connectedApi,
  addresses.shieldedCoinPublicKey,
  addresses.shieldedEncryptionPublicKey,
  value,
  selfRecipient
);

When a mint is successful, Nonce, Color, and Value are stored in localStorage so they can be referenced later during the burn phase.

Mint & Send calls mintAndSend and sends the freshly minted coins to the address the user entered:

const recipientBytes = parseShieldedAddress(recipient);
const recipientEither = {
  is_left: true,
  left: { bytes: recipientBytes },
  right: { bytes: ZERO_BYTES32 },
};

const result = await callMintAndSend(
  connectedApi,
  addresses.shieldedCoinPublicKey,
  addresses.shieldedEncryptionPublicKey,
  value,
  recipientEither
);

A small utility function, parseShieldedAddress, extracts the 32 bytes from the user-typed shielded address

/**
 * Parse a Bech32m shielded address (e.g. `m1q...`) and extract the 32-byte
 * shielded coin public key that the smart contract expects as a recipient.
 */
export function parseShieldedAddress(address: string): Uint8Array {
  try {
    const parsed = MidnightBech32m.parse(address);
    const shieldedAddr = ShieldedAddress.codec.decode(getNetworkId(), parsed);
    return new Uint8Array(shieldedAddr.coinPublicKey.data);
  } catch {
    throw new Error('Invalid shielded address. Paste a Bech32m address starting with the network prefix.');
  }
}

When a mint is successful, Nonce, Color, and Value are stored in localStorage so they can be referenced later during the burn phase. This means users won’t need to enter the values manually when they are already stored in localStorage.

Note: The createShieldedToken circuit returns ShieldedCoinInfo, while the mintAndSend circuit returns a ShieldedSendResult containing sent and change. For mintAndSend with exact amounts, change is typically None.

Coin storage

Shielded coins are different from unshielded ones: they are private, and the wallet does not expose an API to enumerate them with their nonces, so the DApp stores mint results in localStorage.

export interface StoredCoin {
  id: string;
  nonce: string;
  color: string;
  value: string;
  source: 'mint' | 'mintAndSend' | 'change';
  txId: string;
  createdAt: string;
}

Mint page writes using saveStoredCoins and burn page reads using getStoredCoins. Sending tokens from wallet does not require reading or writing.

Sending tokens

The send page uses the wallet’s native makeTransfer for shielded transfers. The wallet handles everything, including proving; however, you still need to call submitTransaction to broadcast it:

const desiredOutput = {
  kind: 'shielded' as const,
  type: selectedToken,
  value,
  recipient: recipientClean,
};

const result = await connectedApi.makeTransfer([desiredOutput]);
if (result.tx) {
  await connectedApi.submitTransaction(result.tx);
}

makeTransfer is the most convenient way of sending shielded tokens using the DApp Connector API.

Burning tokens

The Burn page uses the depositAndBurn circuit to destroy stored coins

const coin = {
  nonce: hexToUint8Array(selectedCoin.nonce),
  color: hexToUint8Array(selectedCoin.color),
  value: BigInt(selectedCoin.value),
};

const result = await callDepositAndBurn(
  connectedApi,
  addresses.shieldedCoinPublicKey,
  addresses.shieldedEncryptionPublicKey,
  coin,
  BigInt(amount)
);

After burning, the coin is removed from localStorage.

const updatedCoins = getStoredCoins().filter((c) => c.id !== selectedCoin.id);
saveStoredCoins(updatedCoins);

Caveat: sendImmediateShielded sends change to kernel.self() (smart contract). Therefore, a partial burn leaves a contract-owned shielded output that is not tracked anywhere, which is why the UI enforces a full burn by default to avoid this.

Home and balance display

The main dashboard displays 3 types of data:

Shielded balance(s) – it displays the combined balance of tokens, shieldedBalanceTotal, that enumerates across all balances. It also calls connectedApi.getShieldedBalances() internally and refreshes every 15 seconds:

const { balances, loadWalletState } = useWalletStore();

useEffect(() => {
  if (!isConnected) return;
  loadWalletState();
  const id = setInterval(() => loadWalletState(), 15_000);
  return () => clearInterval(id);
}, [isConnected, loadWalletState]);

const shieldedBalanceTotal = (() => {
  if (!balances?.shielded) return null;
  const entries = Object.entries(balances.shielded);
  if (entries.length === 0) return 0n;
  return entries.reduce((sum, [, v]) => sum + (v ?? 0n), 0n);
})();

Contract states like totalSupply and totalBurned are fetched via the getContractState helper, which uses ledger() to deserialize the raw bytes into readable data.

const [stats, setStats] = useState<{ totalSupply: bigint; totalBurned: bigint } | null>(null);

useEffect(() => {
  if (contractAddress) {
    getContractState(contractAddress).then(setStats);
  }
}, [contractAddress]);

3. The mint-and-send atomic pattern

The mintAndSend circuit pattern solves a critical problem in shielded token design.

The main issue is that a freshly minted shielded coin is not immediately spendable via sendShielded when it has not yet been committed to the Merkle tree. If you mint a coin in transaction X, you cannot spend it in transaction X+1 without waiting for it to be included in the Merkle tree and obtaining its mt_index.

sendImmediateShielded is different, it bypasses the Merkle qualification by using mt_index: 0.

The circuit pattern:

1. mintShieldedToken(..., kernel.self()) — mint shielded coins to the kernel (smart contract)
2. sendImmediateShielded(coin, recipient, amount) — forward to the recipient

Either both steps succeed, or the entire transaction fails. The recipient receives a fully qualified shielded coin that is spendable in future transactions with sendShielded once it is committed to the Merkle tree.

depositAndBurn circuit pattern:

1. receiveShielded(coin) — deposits user coins into the transaction
2. sendImmediateShielded(coin, burnAddr, amount) — burn it immediately in the same transaction

This atomic pattern makes it possible to burn a shielded coin through the smart contract without using sendShielded with mt_index, which requires the commitment of the coin to the Merkle tree.

4. Key architectural decisions

Conclusion

You have now built a complete shielded token DApp that demonstrates the ability to mint privacy-preserving tokens with mintShieldedToken, atomically forward freshly minted coins with sendImmediateShielded, burn tokens with receiveShielded + sendImmediateShielded, and finally build a React frontend with deploy, mint, send, burn, and balance display.

It is important to distinguish between sendImmediateShielded (bypasses Merkle path before spending) and sendShielded (requires mt_index). Understanding this correctly determines whether the coins you minted are immediately spendable or locked.

Next steps

• Check the full repository source code on GitHub
• Read the Midnight Compact language docs
• Experiment with transferShielded by storing mt_index for committed coins
• Add admin authentication to restrict minting privileges

Troubleshooting

If you’re running SonarQube (or anything CPU- and memory-hungry) inside Docker Desktop on Windows and the scans feel like they’re running through molasses, your .wslconfig is probably the first place to look. That was my story this week, and the fix was satisfyingly small.

Here’s the whole journey, end to end, including the gotchas.

Symptom: scans stall, fans spin, nothing finishes

I was running a SonarQube scan on a mid-sized codebase inside a Docker container on Windows. The scan would chug along for a few minutes, then either crawl or stall outright. Nothing in the SonarQube logs screamed “out of memory” but the host felt fine, so it wasn’t a Windows-side resource problem.

Diagnosis: ask Docker what it actually has

Docker Desktop on Windows runs everything inside a WSL 2 VM called docker-desktop. Whatever resources you’ve given that VM is the ceiling for every container you run. You can ask it directly:

wsl -d docker-desktop -- nproc
wsl -d docker-desktop -- free -h

The output I got:

1
              total        used        free      shared  buff/cache   available
Mem:           907M       ...
Swap:          4.0G        ...

One CPU. Less than 1 GB of RAM. No wonder. SonarQube’s analyzer plus the Java heap alone wants more than that. Anything that hit a swap-heavy phase was going to thrash.

Fix: .wslconfig

WSL 2 reads global VM settings from a single file at %UserProfile%.wslconfig. It doesn’t exist by default you create it. Mine ended up looking like this:

[wsl2]
memory=8GB
processors=4
swap=8GB

Three lines. That’s the whole fix.

A few notes on syntax that tripped me up briefly:

• The section header must be [wsl2] — lowercase, exact.
• memory and swap are “size” values. You must include the unit (GB or MB). Per Microsoft’s spec: “Entries with the size value default to B (bytes), and the unit is omissible.” Which is a polite way of saying that swap=4 means 4 bytes, not 4 GB. Don’t do what I almost did.
• No spaces around the =.
• processors is an integer.

Apply it

Save the file to C:Users<you>.wslconfig, then in PowerShell:

wsl --shutdown

Quit Docker Desktop from the tray icon and start it again. That’s it.

The 8-second rule. Microsoft’s docs are explicit about this: even after wsl --shutdown, give it a moment for the VM to fully stop before relaunching. You can verify with:

wsl --list --running

If nothing’s listed, you’re safe to start back up.

Verify

After Docker came back up:

PS> wsl -d docker-desktop -- nproc
4

PS> wsl -d docker-desktop -- free -h
              total        used        free      shared  buff/cache   available
Mem:           7.8G      485.8M        6.6G        3.1M      697.7M        7.1G
Swap:          8.0G           0        8.0G

4 CPUs, 7.8 GB RAM (the 8 GB cap, minus a sliver of overhead), 8 GB of swap. Exactly what the config asked for.

The SonarQube scan that had been crawling finished in a sensible amount of time on the next run.

Optional extras worth knowing about

If you want to go further, the [wsl2] section supports a bunch of other documented keys. The two I’d actually consider for a SonarQube-style workload:

[wsl2]
memory=8GB
processors=4
swap=8GB
vmIdleTimeout=60000

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

• vmIdleTimeout shuts the VM down after 60 s of idle, so it’s not hoarding 8 GB while you’re not using Docker.
• autoMemoryReclaim=gradual returns idle memory back to Windows slowly instead of dropping caches abruptly nicer for scans that have memory spikes.
• sparseVhd=true makes new WSL VHDs sparse, so disk usage actually shrinks when you free space inside the VM.

Gotchas I want to save you from

A few things I learned the hard way or almost did:

Don’t allocate everything. Setting memory to your entire physical RAM, or processors to your full core count, will starve Windows itself. Aim for roughly 75% of physical RAM and leave a couple of cores for the host.

pageReporting isn’t a real key. I saw it referenced in older blog posts. It’s not in the current Microsoft spec – WSL silently ignores unknown keys, so the file looks valid but the setting does nothing. Stick to the documented list.

Path values need escaped backslashes. If you set swapFile or kernel, write it as C:\Temp\swap.vhdx, not C:Tempswap.vhdx.

Docker Desktop’s docker-desktop VM is what you care about, not a user distro. When validating, run wsl -d docker-desktop -- free -h, not wsl -- free -h. The latter checks whatever default distro you have installed (Ubuntu or similar), which is a separate VM.

TL;DR

If Docker on Windows feels sluggish, check what WSL 2 is actually giving it:

wsl -d docker-desktop -- nproc
wsl -d docker-desktop -- free -h

If those numbers are tiny, drop a .wslconfig at %UserProfile%.wslconfig:

[wsl2]
memory=8GB
processors=4
swap=8GB

wsl --shutdown, restart Docker Desktop, verify, and get on with your day.

Reference: Microsoft’s advanced settings configuration in WSL.

The invisible bill

I was debugging why my Claude Code sessions felt sluggish after connecting a few MCP servers. Token usage was through the roof — but I hadn’t even asked the agent to do anything yet. I rewrote my prompts three times before I thought to check where the tokens were actually going.

Turns out, the moment you connect an MCP server, every tool definition gets loaded into the context window. Names, descriptions, parameter schemas, enum values — all of it, on every single conversation turn. Not just when you call a tool. Every turn.

Think of it like walking into a library to read one book, but the librarian insists you read the entire catalog first. Every time you walk in.

The measurement: 4 servers, 500x cost difference

I measured the tool-definition token overhead for four MCP servers, from minimal to massive:

PostgreSQL to full GitHub: a 1,500x difference. Same protocol, same “MCP server” label, radically different cost profiles.

And this is just the definition overhead. The actual tool calls consume additional tokens on top.

Where the tokens go

A single MCP tool definition looks harmless:

{
  "name": "gmail_create_draft",
  "description": "Creates a draft email...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "to": { "type": "string", "description": "..." },
      "subject": { "type": "string", "description": "..." },
      "body": { "type": "string", "description": "..." }
    }
  }
}

That single tool? 820 tokens. More than the entire PostgreSQL MCP server with its one tool.

Now multiply. A business API like a full accounting platform might expose 270+ tools across invoicing, HR, payroll, time tracking, and sales management. At ~65 tokens per tool average, that’s 17,500 tokens consumed before your first question.

Connect three services like that simultaneously, and you’re burning 143,000 out of 200,000 tokens on schema definitions alone. 71% of your context window is gone. Your agent is trying to think inside a closet.

At scale, the math gets uncomfortable: 1,000 requests/day with heavy MCP overhead = roughly $170/day = $5,100/month — just for loading tool schemas.

The quality cliff

Token cost isn’t even the worst part. Claude’s output quality visibly degrades after 50+ tool definitions are loaded. The model starts chasing tangents, referencing tools instead of answering your actual question.

More tools in context doesn’t mean more capability. Past a threshold, it means worse capability. I confirmed this firsthand — five servers connected, and my agent started recommending create_github_issue as the fix for a database timeout. Very confident. Very wrong.

Three strategies to cut 95%

Strategy 1: Expose only what you need

If you’re using an accounting platform’s 270 tools but only need 10 for your tax filing workflow:

{
  "mcpServers": {
    "accounting": {
      "allowedTools": [
        "create_transaction",
        "list_transactions",
        "get_trial_balance",
        "list_account_items",
        "list_partners"
      ]
    }
  }
}

10 tools instead of 270: ~650 tokens instead of ~17,500. 96% reduction.

Strategy 2: Write tighter descriptions

API docs make terrible tool descriptions. They’re written for humans who read documentation; LLMs need the compressed version.

// Before: ~80 tokens
{
  "description": "Uses the accounting API to create a new
    transaction (journal entry) for the specified company ID.
    You can specify amount, date, account item, partner name,
    memo, and more. Tax category is auto-determined."
}

// After: ~20 tokens
{
  "description": "Create transaction. Args: amount, date, account_item, partner"
}

75% fewer tokens, same functionality. The model doesn’t need a paragraph to understand what create_transaction does.

Strategy 3: Connect only when needed

Don’t keep all MCP servers connected during every conversation. Connect the accounting server when you’re doing accounting work. Disconnect it when you’re writing code. This alone zeroes out overhead for unrelated tasks.

MCP Tool Search: the protocol-level fix

In January 2026, a protocol-level solution arrived: MCP Tool Search. When tool definitions exceed 10% of your context window, the client automatically defers loading them. Instead of dumping every schema into context, the model discovers and loads tools on-demand via search.

Early reports show a 95% reduction in startup token cost. The schema bloat problem is being solved at the infrastructure level, not just through workarounds.

But Tool Search isn’t universally deployed yet. Until it is, the three strategies above are your defense.

What to check right now

1. Count your tools. Run tools/list against each connected MCP server and count the total. If you’re above 30 tools across all servers, you’re likely paying a meaningful overhead tax.

2. Audit descriptions. Look at the JSON schemas your servers return. Are the descriptions essay-length? Trim them. Every token in a description is paid on every conversation turn.

3. Use allowedTools. Most MCP clients support filtering which tools are exposed. Use it. There’s no reason to load 270 tools when you need 10.

4. Measure before/after. Token usage is visible in most LLM clients. Check your per-turn consumption before and after connecting each MCP server. The numbers will tell you exactly which servers are expensive.

The irony of MCP: the protocol designed to extend AI capabilities can end up crippling them — if you load too many tools and leave no room for actual thinking.

This article is based on Chapter 3 of MCP Security in Practice: What OWASP Won’t Tell You About AI Tool Integrations. The book covers the full token cost analysis across services, OWASP MCP Top 10 security risks, file upload limitations, and production hardening patterns.

AI is not just models.

It is a system that perceives, decides, and acts.

If you only think in terms of algorithms, you miss the bigger structure.

The real question is:

How does an AI system turn input into action?

Core Idea

An intelligent agent is the simplest way to understand AI as a system.

It takes input from the environment.

Processes that information.

Then selects an action.

That loop defines AI behavior.

The Key Structure

The basic agent loop looks like this:

Environment → Perception → State → Decision → Action → Environment

Or more compact:

Agent = Perception + Decision + Action

This is why the agent concept matters.

It connects data, reasoning, and behavior into one structure.

Implementation View

At a high level, an agent behaves like this:

observe environment

update internal state

evaluate possible actions

choose the best action

execute action

repeat

This loop appears everywhere.

Game AI.

Robotics.

Autonomous systems.

Recommendation systems.

Even large language models follow a version of this pattern.

Concrete Example

Imagine a simple robot.

It receives sensor input.

It detects obstacles.

It chooses a direction.

It moves.

That is already an intelligent agent.

Now scale that idea:

A recommendation system observes user behavior.

Updates internal preferences.

Chooses the next item to show.

That is also an agent.

Different domain.

Same structure.

Reactive vs Intelligent Agent

Not all agents are equal.

This comparison matters.

Reactive agent:

• responds directly to input
• no memory or internal model
• simple and fast
• limited flexibility

Intelligent agent:

• maintains internal state
• evaluates future outcomes
• can optimize decisions
• adapts to complex environments

So the difference is not just complexity.

It is the presence of internal reasoning.

Why Cognition Matters

As problems become more complex, simple reaction is not enough.

The agent needs internal representation.

Memory.

Inference.

That is where cognition comes in.

Cognitive systems treat thinking as information processing.

Input is transformed into internal structure.

That structure supports reasoning.

So the flow becomes:

Perception → Representation → Reasoning → Action

Without this layer, AI is limited to simple responses.

With it, AI can plan and infer.

Action vs Understanding

This is where things get interesting.

Does acting correctly mean understanding?

A system can follow rules and produce correct outputs.

But does it truly understand meaning?

This question is not just philosophical.

It affects how we interpret AI systems.

Rule-following can look like intelligence.

But it may not imply true understanding.

That distinction matters when designing or evaluating AI.

Decision vs Free Will

If an agent chooses actions, is that the same as free will?

In humans, experiments suggest decisions may begin before conscious awareness.

In AI, decisions are the result of computation.

So the deeper question becomes:

Is decision-making just a process?

Or is there something more?

Even if you do not answer it fully, this perspective helps you see AI systems differently.

They are not just tools.

They are structured decision systems.

From Agents to Modern AI Systems

The agent view scales.

Search algorithms:

• choose next state

Knowledge-based systems:

• use rules and inference

Neural networks:

• learn representations

Modern AI combines these ideas.

Perception.

Representation.

Decision.

Learning.

The agent is the unifying abstraction.

Why This Matters

If you only learn models, you miss system design.

If you understand agents, you understand AI structure.

That matters in practice.

Because real systems are not just one model.

They are pipelines.

Loops.

Decision processes.

The agent view helps you design them.

Recommended Learning Order

If this feels broad, follow this order:

1. Agent vs Intelligent Agent
2. Intelligent Agent
3. Cognitive Agents
4. Cognitivism
5. Chinese Room Argument
6. Free Will and Decision Systems

This order works because you first understand action.

Then internal reasoning.

Then the limits of understanding.

Takeaway

AI is best understood as an agent.

Not just a model.

Not just an algorithm.

A system that:

• perceives
• represents
• decides
• acts

The shortest version is:

Agent = perception + decision + action

If you remember one idea, remember this:

AI systems are decision loops, not isolated models.

Discussion

When designing AI systems, do you think more in terms of models, or in terms of agents that interact with environments?

Originally published at zeromathai.com.
Original article: https://zeromathai.com/en/intelligent-agent-and-cognition-hub-en/

GitHub Resources
AI diagrams, study notes, and visual guides:
https://github.com/zeromathai/zeromathai-ai

Before AI learned from massive datasets, many systems worked with explicit knowledge.

Facts.

Rules.

Inference.

That is the core of Knowledge-Based AI.

Core Idea

Knowledge-Based AI stores knowledge in a structured form.

Then it uses rules to derive new conclusions.

The system does not “learn” from data in the modern deep learning sense.

It reasons over what it already knows.

That makes the structure very different from machine learning.

The Key Structure

A simple Knowledge-Based AI system looks like this:

Knowledge Base → Rules → Inference Engine → Conclusion

Or more compact:

Knowledge-Based AI = Facts + Rules + Inference

The knowledge base stores information.

The rule system defines how conclusions can be derived.

The inference engine applies those rules.

Implementation View

At a high level, a rule-based system works like this:

store known facts

store IF-THEN rules

compare facts with rule conditions

apply matching rules

generate new facts or conclusions

repeat until no useful rule applies

This is why Knowledge-Based AI is easy to inspect.

You can often trace exactly which rule produced which conclusion.

That transparency is one of its biggest strengths.

Concrete Example

Imagine a simple medical expert system.

It may store facts like:

• patient has fever
• patient has cough
• patient has fatigue

And rules like:

IF fever AND cough THEN possible infection

IF possible infection AND fatigue THEN recommend further test

The system does not train on millions of examples.

It applies explicit rules.

That makes the reasoning path easier to explain.

Rule-Based AI vs Machine Learning

This comparison is important.

Rule-Based AI:

• uses explicit facts and rules
• depends on human-designed knowledge
• is easier to explain
• struggles when rules become too many or too brittle

Machine Learning:

• learns patterns from data
• improves through training
• handles noisy and complex data better
• can be harder to interpret

So the difference is not just old AI vs modern AI.

It is symbolic reasoning vs data-driven learning.

Both solve problems in different ways.

Forward Chaining vs Backward Chaining

Even with the same rules, inference can move in different directions.

Forward chaining starts from known facts.

It applies rules until it reaches conclusions.

Backward chaining starts from a goal.

It works backward to check whether the needed conditions are true.

Forward chaining:

• data-driven
• useful when you want to discover what follows from known facts
• starts with available evidence

Backward chaining:

• goal-driven
• useful when you want to prove or verify a target conclusion
• starts with the question

The difference is simple:

Forward chaining asks:

“What can I conclude from what I know?”

Backward chaining asks:

“What must be true for this goal to hold?”

Why Inference Engines Matter

The inference engine is the part that makes the system active.

A knowledge base alone only stores information.

Rules alone only define possible logic.

The inference engine applies the rules to produce conclusions.

That is why it is the execution layer of Knowledge-Based AI.

Without inference, the system is just a database.

With inference, it becomes a reasoning system.

Why Expert Systems Were Important

Expert systems are one of the clearest applications of Knowledge-Based AI.

They encode domain knowledge from human experts.

Then they use rules to make recommendations or decisions.

Examples include:

• medical diagnosis support
• troubleshooting systems
• configuration systems
• rule-based decision support

Their biggest strength is explainability.

Their biggest weakness is maintenance.

As the domain grows, the rule base can become difficult to manage.

Logical Extensions

Knowledge-Based AI also connects to formal reasoning.

Logic programming, such as PROLOG, represents knowledge as logical relations.

Theorem proving uses formal logic to verify statements.

Commonsense reasoning tries to represent everyday assumptions that humans usually take for granted.

These extensions show the same basic idea:

Represent knowledge explicitly.

Then reason over it.

Recommended Learning Order

If Knowledge-Based AI feels broad, learn it in this order:

1. Knowledge Base
2. Rule-Based System
3. Inference Engine
4. Forward Chaining
5. Backward Chaining
6. Expert System
7. Logic Programming
8. Theorem Proving
9. Commonsense Reasoning

This order works because you first understand storage.

Then rules.

Then inference.

Then practical and logical extensions.

Takeaway

Knowledge-Based AI is built on explicit knowledge and reasoning.

The shortest version is:

Knowledge-Based AI = facts + rules + inference

It is not mainly about learning from data.

It is about using stored knowledge to reach conclusions.

If you remember one idea, remember this:

A knowledge-based system becomes intelligent when stored rules can generate new conclusions from known facts.

Discussion

When building AI systems, do you prefer transparent rule-based reasoning, or flexible data-driven learning?

Originally published at zeromathai.com.
Original article: https://zeromathai.com/en/knowledge-based-ai-hub-en/

GitHub Resources
AI diagrams, study notes, and visual guides:
https://github.com/zeromathai/zeromathai-ai