@kuiralabs/midnight-account-chain 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,301 @@
-# Temporary Holding Version
+# chain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The account contract on a local ledger-9 network. This package builds the same
+`../account/contract/Account.compact` as the library, with Compact 0.35.0 in place
+of 0.34.0. The reason is the SDK: midnight-js 5.0.0-rc.1 and the wallet SDK
+2.0.0-rc.0 run on compact-runtime 0.20.0, which only a 0.35.0 build targets.
+The library keeps 0.34.0, because OpenZeppelin's simulator is still on
+runtime 0.19.0.
+
+## The stack
+
+Every component is on ledger 9.1.0.0-rc.5:
+
+| Component | Version |
+|---|---|
+| Compact | 0.35.0 (runtime 0.20.0) |
+| midnight-js | 5.0.0-rc.1, with testkit-js 5.0.0-rc.1 |
+| Wallet SDK | `@midnightntwrk/wallet-sdk` 2.0.0-rc.0 |
+| Node | `midnightntwrk/midnight-node:2.1.0-rc.2` |
+| Indexer | built from midnight-indexer main at `3e9f6374` |
+| Proof server | `midnightntwrk/proof-server:9.0.0-rc.8` |
+
+The public networks (Preview, Preprod) still run ledger 8. Midnight's
+compatibility matrix does not cover ledger 9 yet.
+
+The indexer has to be built from source:
+- Every published ledger-9 indexer image is 4.4.0-rc.2, which is on ledger rc.3.
+- Newer indexers exist only as source.
+
+Node 2.1.0-rc.2 is the newest node version the indexer carries metadata for.
+
+## Running
+
+Build the indexer image once. Use the release profile, which is the Dockerfile's default:
+
+```
+git clone https://github.com/midnightntwrk/midnight-indexer && cd midnight-indexer
+git checkout 3e9f6374
+docker build --build-arg RUST_VERSION=$(sed -nr 's/channel = "(.*)"/\1/p' rust-toolchain.toml) \
+  -t midnight-bench/indexer-standalone:4.4.0-rc.5-3e9f6374 -f indexer-standalone/Dockerfile .
+```
+
+Start the localnet. The indexer needs a 32-byte hex secret in `infra/.env`, which git ignores:
+
+```
+cd infra
+echo "APP__INFRA__SECRET=$(openssl rand -hex 32)" > .env
+docker compose up -d
+```
+
+Compile with keys, then deploy:
+
+```
+npm install                        # after npm install in the repository root, which builds the library
+npm run compile                    # 30 circuits, about 4 GB of proving keys
+node scripts/deploy.ts
+```
+
+## Deploying
+
+The whole roster's verifier keys come to 73,806 bytes. A single deploy is
+refused by the fee computation before any transaction exists: `exceeded block
+limit in transaction fee computation`. The grants draft (section 6.7) measured
+the same.
+
+`scripts/deploy.ts` therefore deploys in waves:
+1. **The deploy transaction.** It carries the two deposits and the eight
+   circuits of the arm the account is born on.
+2. **Maintenance updates.** `src/maintenance.ts` adds every other circuit's key,
+   packed to 25,000 bytes per update. That is the draft's budget, below the
+   ceiling it measured between 29,484 and 32,229 bytes.
+
+On this localnet that is four transactions in about 75 seconds. Then
+midnight-js's own `findDeployedContract` checks every on-chain key against the build.
+
+The maintenance updates are built by hand on the ledger-v9 API, not through
+midnight-js's `submitInsertVerifierKeyTx`:
+- compact-js, in every 3.0.0 release so far, wraps inserted keys at
+  contract-operation version `'v3'`, which expects a `verifier-key[v6]` header.
+- A ZKIR v3 build writes `verifier-key[v7]`, which needs version `'v4'`.
+- So the SDK path fails for any ZKIR v3 contract before a transaction exists.
+- The update built here is the one compact-js builds, at the version the key
+  actually carries.
+
+The last update also retires the maintenance authority (the grants draft,
+section 6.7): it replaces the authority with an empty committee at threshold
+1, which can sign nothing. After it, no one can change the contract's rules.
+
+`scripts/completeDeploy.ts` resumes an interrupted deploy. It inserts only
+the entry points that are still blank, and leaves a finished account as it
+is.
+
+The owner's key material is written to `.state/`, which git ignores:
+- the JubJub device key
+- the boot salt
+- the X25519 account encryption key
+
+The maintenance authority's key is written to the level private-state store in
+`midnight-level-db/`.
+
+## The account on chain
+
+After the deploy, these scripts run the account's life as its parties see
+it. Each one proves on the local proof server and submits to the node:
+
+| Script | Who | What |
+|---|---|---|
+| `scripts/deploy.ts [v1 \| k1]` | owner | deploys an account born on a JubJub or a secp256k1 device key, in waves, and retires the authority |
+| `scripts/activate.ts` | owner | activates the boot device, on either arm |
+| `scripts/owner.ts` | owner | activates the boot device; the unshielded deposit it then tries is refused (below) |
+| `scripts/depositShielded.ts` | anyone | `deposit_shielded`, with the InboxEntry sealed to `enc_key` read from chain |
+| `scripts/discoverCoins.ts` | owner | the inbox walk (MIP-0012 section 6.5) |
+| `scripts/ownerShielded.ts` | owner | a shielded withdrawal to the genesis wallet, then the change backfilled by `append_inbox` |
+| `scripts/ownerPayContract.ts <payee>` | owner | pays another contract, composed with the payee's claim |
+| `scripts/agentRequest.ts <account> [slot] [v1 \| k1] [payee contract]` | agent | a grant request: grantee key, X25519 read key, origin, slot, payee |
+| `scripts/issueGrant.ts [seconds]` | owner | rotate before share, re-seal to the other live read grants, `issue_grant`, the sealed view |
+| `scripts/agentSpend.ts [slot]` | agent | pays the merchant under the grant from its own wallet; an over-cap payment is refused |
+| `scripts/agentPayContract.ts <slot> <payee>` | agent | pays a contract under a grant pinned to it, composed with the payee's claim |
+| `scripts/admissionExpiry.ts <slot> [hold]` | agent | proves while live, holds, submits: refused after `expires_at`, included before it |
+| `scripts/inFlight.ts <slot> <deposit \| revoke>` | agent | proves, then a deposit or a revocation lands, then submits: refused |
+| `scripts/revokeGrant.ts <slot>` | owner | `revoke_grant`, then the rotation and re-seals section 8 item 6 asks |
+| `scripts/revokeAllGrants.ts` | owner | `revoke_all_grants`, then the rotation |
+| `scripts/agentStatus.ts [slot] [--mailbox-only]` | agent | what the agent sees of its grant, and where it learned it |
+| `cli/owner.ts <command>` | owner | the owner's command line: `status`, `grants`, `issue <link> [--yes]`, `revoke <id \| slot>`, `revoke-all`, `revoke-exhausted [<id>...] [--yes]`, each with `--json` |
+
+Each account is a profile (`src/profile.ts`). The first account's records
+are in `.state/`. Another account is deployed and driven under its own
+`BENCH_PROFILE`, with records in `.state/<profile>/`. For example, a
+k1-born account:
+
+```
+BENCH_PROFILE=k1 node scripts/deploy.ts k1
+BENCH_PROFILE=k1 node scripts/activate.ts
+```
+
+The owner's gated calls go through one API that picks the circuit of the
+device's arm, `_with_jubjub` or `_with_k256` (`src/ownerCalls.ts`). The
+agent's grant spends do the same by the grantee key's arm.
+
+Four wallets take part: the owner pays from genesis seed `…01`, the agent
+from `…02`, and the merchant is `…03`'s shielded address.
+
+The owner's code also runs over a wallet it did not build. Anything that offers midnight-js's wallet and submit providers (`FeeWallet` in `src/providers.ts`; a wallet behind a DApp connector, say) can pay. Such a caller imports one module, `driver.ts`: `deployOver` deploys the account on the k1 arm and activates its boot device, on a device key the caller may bring, and is safe to run again (it completes a deploy that stopped part way, and moves aside the record of one that never reached the chain); `runOwnerOver` runs one of the owner's commands and hands back the result. The caller names its endpoints as URLs (`MIDNIGHT_ACCOUNT_NODE_URL`, `MIDNIGHT_ACCOUNT_INDEXER_URL`, `MIDNIGHT_ACCOUNT_PROOF_SERVER_URL`) and keeps its accounts' records outside the repo by naming a directory in `MIDNIGHT_ACCOUNT_STATE_DIR`; profiles live under it as they do under `.state/`.
+
+Nothing is kept that the chain can give back:
+- The owner's device use counter is recovered from the `devices` set.
+- Both coin stores are rebuilt by the inbox walk on every session.
+- The owner keeps every encryption secret it has held, so its walk reads the
+  whole inbox. A delegate holds only the current one.
+
+### Coin discovery
+
+The walk verifies each opened entry against the ledger's own `zswapOutput`
+events for the account:
+- The commitment is recomputed with the ledger's `runtimeCoinCommitment`.
+- The event carries the coin's `mt_index`, so no position window or candidate
+  retry is needed.
+- A coin is spent when its nullifier (`runtimeCoinNullifier`, with the
+  contract as sender) is among the account's `zswapInput` events.
+
+`deposit_shielded` is permissionless, so the inbox can hold anything
+192 bytes long. The walk skips any entry it cannot open, including one whose
+ephemeral key is of low order, where the X25519 derivation itself fails. It
+treats every such entry as inert noise (grants draft section 8 item 4), so no
+depositor can stop the walk.
+
+The events come from the indexer's `contractActions` subscription, which
+lists a contract's transactions by address. MIP-0012 records that surface as
+an ecosystem dependency; the indexer at `3e9f6374` has it.
+
+### A grant, end to end
+
+The draft's flow, with no step skipped:
+1. **The agent's request** carries its grantee key, its read key and the
+   merchant's coin key.
+2. **The owner** checks both keys (section 3.3, section 8 item 1), then
+   rotates before share (section 8 item 2):
+   - `rotate_enc_key_with_jubjub`
+   - one `append_inbox_with_jubjub` per held coin
+   - a re-seal of the new secret to every other live read grant
+3. **The owner issues** the grant under the boot device and seals the new
+   secret to the read key in a 94-byte GrantViewSeal (section 8 item 3).
+4. **The agent** opens the view and checks that `X25519(secret, 9)` is
+   `enc_key`. Then it walks the inbox and pays the merchant with
+   `withdraw_shielded_with_grant_jubjub`, sealing the change entry itself.
+
+Neither party can lose track through a crash:
+- **The owner** writes its roster before each step. A read grant is marked
+  for re-seal before a rotation blinds it; a new grant is written before it
+  is issued. The next run finishes what the last one left.
+- **Interrupted issues.** One that landed is sealed on the next run. One
+  that left nothing on chain is kept as `issuing` while its transaction could
+  still land, an hour plus a margin by midnight-js's expiry, then marked
+  `abandoned`.
+- **Unknown read grants.** A live read grant on chain that the roster holds
+  no key for is surfaced as requiring reconnection.
+- **Re-seals** go only to the key the record's `read_pk_hash` names.
+- **Rotation secrets** are written before the rotation is submitted, and
+  none is ever dropped.
+- **Revocations.** A revocation records the rotation it owes before it is
+  submitted, so the rotation happens once, however many grants it revoked.
+  A revocation that never landed is retried, and its grant is never
+  re-sealed in the meantime.
+- **Change coins** are recorded before the spend that creates them. Each
+  session open backfills any recorded change the chain created but no inbox
+  entry describes.
+- **The use counter** is re-read from the `devices` set after every gated
+  call, whether or not the call landed.
+- **The agent** keys its running spend by grant incarnation (the grant id
+  with `issued_at`), so a re-issued grant starts from zero. It records a
+  spend as pending before submitting it. Its
+  running spend is checked against the record's `spent_commit` on every
+  session and before every spend, and a pending spend is counted once that
+  commitment shows it landed.
+
+Measured on this localnet, with one held coin:
+- Issuing a read grant takes three transactions: rotation 48 s (two
+  transactions), then issue 24 s.
+- Each grant spend takes about 30 s.
+
+The runs check each outcome on chain:
+- **Payment.** The merchant's coin is found by its commitment in the
+  transaction's events. The change is found by the agent's next walk.
+- **Over the cap.** A payment that would exceed the cap fails the circuit's
+  own assert before any proof exists.
+- **Admission expiry.** A spend proved while the grant is live and held
+  173 s is included if submitted before `expires_at`. Submitted after it,
+  the node refuses it from the mempool, with custom error 104: `guaranteed
+  execution would fail: mismatch between expected (<[01]: b1>) and actual
+  (<[-]: b1>) read`. The proof recorded the block-time comparison as true;
+  at admission it reads false. The record's nonce and the coin are untouched.
+
+### The grant mailbox
+
+The owner's response to a grant request travels on chain, sealed to the
+agent's read key (`../src/grants/mailbox.ts`, `src/mailbox.ts`):
+- **What it is.** Two `append_inbox` entries carry the scope's salt and
+  object, its `rp_id_hash`, and the account secret.
+- **Finding it.** The agent computes its grant id, walks the inbox with its
+  read key, and checks the message against the record's commitments and
+  `enc_key`.
+- **Re-seals.** After a rotation they arrive the same way, so the agent
+  picks up the new secret by reading the chain again.
+- **Fallback.** The owner also writes the same sealed message as a response
+  file, and `cli/owner.ts issue` prints it as a link for a QR code. Nothing
+  in it is in clear, and the agent verifies it exactly as a mailbox message.
+  `--mailbox-only` ignores it.
+- **Grant requests** travel as a link: 276 characters with a 16-byte
+  `client_id`, up to about 600 with the longest the form admits
+  (`midnight-mandate:grant-request?r=…`), which `scripts/agentRequest.ts`
+  prints and `cli/owner.ts issue` takes.
+
+On chain:
+- **Learned from chain alone.** An agent ignoring every file learned a new
+  grant from the mailbox and paid under it.
+- **Re-seals arrive.** An older grant's re-seal arrived through the mailbox.
+- **Other readers.** The owner's coin walk skipped every mailbox entry.
+- **Cost.** Each message is two appends, about 48 s together here.
+
+### On chain, beyond the first grant
+
+Every one of these was run against the node:
+- **Both owner-device arms.** A k1-born account activates, withdraws and
+  backfills with `_with_k256` circuits, then issues a grant with
+  `issue_grant_with_k256`.
+- **Both grantee arms.** A secp256k1 grantee under envelope 0 pays with
+  `withdraw_shielded_with_grant_k256`. Envelope-1 grantees are read-only, by
+  the draft's section 3.2.
+- **Paying a contract.** The owner's `withdraw_shielded_to_contract_with_jubjub`
+  and an agent's `withdraw_shielded_to_contract_with_grant_jubjub` each land
+  in one transaction with the payee's `deposit_shielded` claim
+  (`src/compose.ts`), and the payee's own walk finds the coin.
+- **In flight.** A spend proved before a deposit, or before a revocation, is
+  refused from the mempool on the read that changed: `round`, or the
+  record's `active`.
+- **Revocation.** `revoke_grant` and `revoke_all_grants`, each followed by
+  the rotation. Afterwards the revoked agent's view still opens, to a secret
+  that is no longer `enc_key`, so the agent refuses to act on it ("reconnect
+  to the owner"). After revoke-all, its record is gone as well.
+
+### Findings
+
+The findings written up for their teams are in `../docs/findings/`.
+
+- **An unshielded deposit is refused by the fee computation.**
+  `deposit_unshielded` fails with custom error 231,
+  `FeeCalculationError::OutsideTimeToDismiss`. Under the on-chain ledger
+  parameters (read from the indexer's `block.ledgerParameters`), validation
+  plus guaranteed cost comes out 21 µs over the time-to-dismiss bound.
+  `scripts/diagnoseDeposit.ts` reproduces it. The shielded path runs instead.
+- **The change coin is predictable, as the draft says.** A grantee seals the
+  change entry, which the challenge covers, before the proof exists. The
+  draft's section 6.5 gives the change nonce as Compact's stdlib evolution of
+  the spent nonce under `midnight:kernel:nonce_evolve/2`. It matched every
+  change the chain created here (`chain/src/coins.ts`, `changeCoinOf`).
+- **Paying a pinned shielded recipient needs its encryption key.** The grant
+  pins the merchant by coin public key (`recipient_kind` 2). midnight-js still
+  refuses to build the output without the recipient's encryption public key:
+  it encrypts the output so the recipient's wallet finds the coin. So the
+  grantee needs the merchant's full shielded address, off chain. Neither the
+  grant nor the request carries it.

package/dist/cli/owner.d.ts

@@ -0,0 +1,3 @@
+import type { Session } from '../src/session.ts';
+export type Out = (text: string) => void;
+export declare const runOwner: (argv: readonly string[], open: () => Promise<Session>, out?: Out) => Promise<number>;