MIP-0012: Contract Custody of Midnight Native Assets

[nstanford5]

Abstract

This MIP specifies how a Compact contract custodies Midnight-native values: unshielded tokens (Night and any other unshielded color) and shielded Zswap coins. It is the first building block of the multi-key account contract recommended by MPS-0018, deliberately limited to the asset surface. Who may authorise a release, how credentials are managed, and how control is recovered are the subjects of companion building blocks; this document specifies only the seam they attach to.

Deposits are permissionless. Releases are gated by a single internal authorisation seam whose observable semantics this MIP fixes and whose credential scheme it deliberately does not. Unshielded custody pairs the protocol receive and send operations with an explicit per-color balance mirror. Shielded custody is stateless: a held coin's description (nonce, color, value) never enters public ledger state. Deposits pair the protocol-level coin claim with an encrypted inbox entry, addressed to an account encryption key advertised on-ledger, and spends supply the coin description as a private witness from a wallet-local coin store. An observer learns that the custody contract acted, but never the amounts, the token types, the balances, or the counterparties of conforming payments. This removes the holdings-publicity trade-off carried by the prevailing Map<color, QualifiedShieldedCoinInfo> pattern, and the stateless custody pattern has been validated end to end against a production node, including a byte-level audit of every observer-visible surface.

The same encryption that hides holdings also separates reading from releasing: reconstructing the contract's shielded position needs only the account encryption secret, whereas releasing assets needs the authorisation seam, so that secret can be delegated as a read-only viewing capability — to an accountant, auditor, or compliance function — without ceding custody (Rationale R9).

The specification also makes normative a change-handling rule (persist the change coin that leaves the transaction live, never a coin the transaction consumed) whose violation has been observed to silently strand funds in ecosystem library code; the defect is fixed upstream, and the rule keeps the failure class out of conforming implementations.

MIP-0012
Contributors: @hbulgarini @NicolasDP

[ekacin]

Hi all — following up on a pointer from @Kanasjnr on servicedesk#213, sharing some real-world context that might be useful input for this MIP.

I'm building UBLP, an open-source logistics protocol on Midnight. My Incoterms Escrow module (Escrow.compact) holds a buyer's locked payment as a shielded coin until an independent party attests delivery. Early on I hit exactly the trade-off this MIP's abstract describes: I needed to capture the coin's allocated Merkle index (mt_index) to later spend it, but the only API that exposes an index — writeCoin into a ledger-tracked coin cell — unavoidably writes the full QualifiedShieldedCoinInfo, including value, to public ledger state. For an escrow holding a real payment amount, that's a direct privacy leak of the exact thing the contract exists to protect, confirmed by @Kanasjnr after running it through the compiler in #187.

My workaround (still in place, documented in-repo as deliberate): I never call writeCoin for the held coin at all. I recover mt_index by regex-scraping it out of the transaction's own toString(true) serialization at the point receiveShielded allocates it, then cache it locally (witness-side) for the later spend. It works and is CI-tested end to end, but it's an undocumented, fragile technique I'd drop immediately for a real API — which is exactly what this MIP's "coin never enters public ledger state" design would give me.

Happy to share more of my contract/test setup if it's useful for scoping this MIP — I'm a concrete, independently-arrived-at case of the same problem.