Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From core-concepts
This skill should be used when the user asks about Kachina smart contract protocol, Zswap token transfers, atomic swaps, shielded transfers, offers, coins, nullifiers, commitments, confidential smart contracts, the two-state model (public/private state), token minting, how ZK proofs enable privacy in Midnight protocol transactions, or private transaction mechanisms.
npx claudepluginhub devrelaicom/midnight-expert --plugin core-conceptsHow this skill is triggered — by the user, by Claude, or both
Slash command
/core-concepts:protocolsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Midnight uses two foundational protocols: **Kachina** for data-protecting smart contracts and **Zswap** for shielded token transfers.
This skill should be used when the user asks about Midnight network architecture, transaction structure, guaranteed vs fallible sections, Zswap/Kachina integration, ledger and state management, cryptographic binding, balance verification, nullifiers, address derivation, transaction merging, atomic swaps, fee handling, or the privacy model separating private and public domains.
This skill should be used when the user asks about Midnight transaction execution, guaranteed vs fallible phases, kernel.checkpoint(), transaction composition, state conflicts, DUST fees, gas limits, proof verification, partial transaction success, transaction merging, atomic swaps, or how Compact circuits map to on-chain execution. Also triggered by mentions of "transaction semantics", "fallible phase", "guaranteed phase", "checkpoint", "well-formedness", "Impact VM", or "Zswap offers".
This skill should be used when the user asks about the Midnight.js SDK, midnight-js packages, @midnight-ntwrk npm packages, setting up SDK providers, deploying or finding contracts with deployContract or findDeployedContract, calling circuits with callTx or submitCallTx, the transaction lifecycle, SDK provider types (WalletProvider, MidnightProvider, PublicDataProvider, ProofProvider, ZkConfigProvider, PrivateStateProvider), testkit-js testing, observable state subscriptions, contract maintenance and verifier keys, or connecting to the indexer or proof server.
Share bugs, ideas, or general feedback.
Midnight uses two foundational protocols: Kachina for data-protecting smart contracts and Zswap for shielded token transfers.
| Need | Protocol |
|---|---|
| Smart contract logic | Kachina |
| Token transfers | Zswap |
| Atomic multi-party swaps | Zswap |
| Private computation | Kachina |
| Shielded coins | Zswap |
Kachina enables confidential, general-purpose smart contracts while maintaining decentralization.
┌─────────────────────────────────────────┐
│ On-Chain (Public) │
│ - Contract code │
│ - Public state │
│ - Merkle roots │
└─────────────────────────────────────────┘
^ ZK Proofs ^
┌─────────────────────────────────────────┐
│ Off-Chain (Private) │
│ - User's private inputs │
│ - Local state │
│ - Witness data │
└─────────────────────────────────────────┘
| State Type | Location | Visibility |
|---|---|---|
| Public state | Blockchain | Everyone |
| Private state | User's machine | Owner only |
ZK proofs bridge these states: prove something about private state without revealing it.
| Property | Benefit |
|---|---|
| Concurrency | Multiple users act simultaneously without blocking |
| Privacy | Private state never leaves user's machine |
| Composability | Contracts interact via public state (cross-contract calls still under development) |
| Reordering | Conflicting transactions optimally reordered |
Zswap is a shielded token mechanism for confidential atomic swaps, based on Zerocash.
Zswap Offer = Inputs + Outputs + Transient + Deltas
| Hidden | Visible |
|---|---|
| Sender | Transaction occurred |
| Receiver | Proof validity |
| Amount | Fee payment |
| Token type (can be) | Nullifiers (unlinkable) |
An offer comprises inputs (coins being spent, each identified by a nullifier with a Merkle proof and ZK validity proof), outputs (new coins being created, each carrying a commitment and optional encrypted note), transient coins (created and destroyed within the same transaction), and a delta vector describing the net value change per token type. Each input and output also carries a separate Pedersen value commitment for balance verification.
Zswap enables multi-party atomic exchanges:
Party A: Offers 10 TokenX
Party B: Offers 5 TokenY
|
Merged off-chain
|
Single atomic transaction
(Either both happen or neither)
Two transactions can merge if at least one has an empty contract call section. Coin sets must be disjoint. Merged transaction combines:
Contracts issue custom tokens via Zswap:
Token type = Hash(domain_separator, contract_address)
Contract can mint/burn tokens through Zswap stdlib operations
New coins are created as hash-based commitments (Hash(CoinInfo, ZswapCoinPublicKey)), paired with a separate Pedersen value commitment for balance verification. See references/zswap-internals.md for details.
Important: The coin commitment is hash-based, not a Pedersen commitment. The Pedersen value commitment is a separate element used only for balance verification.
Coins are spent by publishing a nullifier (Hash(CoinInfo, ZswapCoinSecretKey)) with a Merkle proof of commitment existence and a ZK validity proof. The commitment itself is NOT an input to nullifier computation, making nullifiers unlinkable to the original commitment. See references/zswap-internals.md for the complete input structure.
Critical: The nullifier is computed from CoinInfo and the secret key -- the commitment itself is NOT an input to nullifier computation. This makes nullifiers unlinkable to the original commitment without knowledge of the secret key.
┌──────────────────────────────────────────┐
│ Transaction │
├──────────────────────────────────────────┤
│ Zswap Section | Contract Section │
│ - Guaranteed offer | - Contract calls │
│ - Fallible offer | - ZK proofs │
│ (Token transfers) | (State changes) │
└──────────────────────────────────────────┘
Transactions combine Zswap (value movement) with Kachina (computation).
See core-concepts:architecture for the full three-phase execution model.
1. Create Zswap offer with:
- Input: Your coin (nullifier + proof)
- Output: Recipient's new coin (commitment)
- Deltas: Must net to non-negative (excess becomes fees)
2. Submit transaction
1. Party A creates partial offer: NIGHT: +10, TokenX: -10
// Positive delta = inputs exceed outputs = giving that token type
2. Party B creates partial offer: TokenX: +10, NIGHT: -10
// Bob gives TokenX, wants NIGHT
3. Merge offers (deltas sum to zero — balanced)
4. Submit single transaction
5. Both transfers atomic
1. Zswap offer moves tokens
2. Contract call updates state
3. Both bound cryptographically
4. Atomic execution
For detailed technical information:
references/kachina-deep-dive.md - UC security model, transcript validationreferences/zswap-internals.md - Coin commitments, value commitments, offer constructionWorking patterns:
examples/basic-transfer.md - Simple shielded transferexamples/atomic-swap.md - Multi-party atomic exchange