zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/permitMessages.ts

@@ -0,0 +1,572 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitMessages.ts — `zklicensing/permits/messages`
+ *
+ * The single definition of everything signed or hashed for zkPermits: the
+ * permit leaf, subject derivation, packed fees and policy, the authority
+ * key-set commitment, and the message each signer signs. The PermitRegistry
+ * circuit imports this module, so an off-chain signature (authority console,
+ * operator page, agent) always hashes to exactly what the circuit verifies.
+ * Test vectors: permitMessages.vectors.json.
+ *
+ * Every function works both off-chain and inside a circuit (o1js types
+ * only). Messages are short Field arrays; wallets sign them with
+ * `signFields` (Auro, WalletConnect `mina_signFields`), and o1js
+ * `Signature.verify` accepts those signatures in-circuit.
+ *
+ * Wallet field signatures are NOT bound to a network by the signer, so
+ * every message carries the network, the registry address and a
+ * per-message nonce itself (see `authorityMessage`).
+ */
+
+import { Bool, Field, Poseidon, PrivateKey, Provable, PublicKey, Signature, Struct, UInt32, UInt64 } from 'o1js';
+
+// ------------------------------------------------------------
+// Domain separation
+// ------------------------------------------------------------
+
+/** Deterministic Field from a short ASCII label (≤ 31 bytes). */
+function labelField(label: string): Field {
+  if (label.length > 31) throw new Error(`label too long: ${label}`);
+  let v = 0n;
+  for (const ch of label) {
+    const c = ch.charCodeAt(0);
+    if (c > 0x7f) throw new Error('ASCII labels only');
+    v = (v << 8n) | BigInt(c);
+  }
+  return Field(v);
+}
+
+/** One tag per message type. Never reuse or renumber. */
+export const PERMIT_TAGS: Readonly<Record<
+  'INIT' | 'GRANT' | 'ACCEPT' | 'SUSPEND' | 'REINSTATE' | 'REVOKE' | 'SURRENDER' | 'SET_FEES' | 'ROTATE' | 'LEAF' | 'SUBJECT' | 'KEYS'
+  | 'APPLICATION' | 'APPLY' | 'APPROVE' | 'REJECT' | 'WITHDRAW' | 'RETIRE' | 'PLATFORM_RETIRE' | 'PLATFORM_CANCEL'
+  | 'PAYOUT' | 'PAYOUT_CANCEL' | 'REKEY',
+  Field
+>> = {
+  INIT:       labelField('zkPermits/v1/init'),
+  GRANT:      labelField('zkPermits/v1/grant'),
+  ACCEPT:     labelField('zkPermits/v1/accept'),
+  SUSPEND:    labelField('zkPermits/v1/suspend'),
+  REINSTATE:  labelField('zkPermits/v1/reinstate'),
+  REVOKE:     labelField('zkPermits/v1/revoke'),
+  SURRENDER:  labelField('zkPermits/v1/surrender'),
+  SET_FEES:   labelField('zkPermits/v1/setFees'),
+  ROTATE:     labelField('zkPermits/v1/rotate'),
+  LEAF:       labelField('zkPermits/v1/leaf'),
+  SUBJECT:    labelField('zkPermits/v1/subject'),
+  KEYS:       labelField('zkPermits/v1/keys'),
+  // Application escrow (PERMITS_PLAN.md §4.2).
+  APPLICATION: labelField('zkPermits/v1/application'),
+  APPLY:       labelField('zkPermits/v1/apply'),
+  APPROVE:     labelField('zkPermits/v1/approve'),
+  REJECT:      labelField('zkPermits/v1/reject'),
+  WITHDRAW:    labelField('zkPermits/v1/withdraw'),
+  // Generations: the authority retires a registry before redeploying it.
+  RETIRE:      labelField('zkPermits/v1/retire'),
+  // ... or the platform does (one signature by the platform key).
+  PLATFORM_RETIRE: labelField('zkPermits/v1/platformRetire'),
+  // Before retiring, the platform may cancel an open application (full refund).
+  PLATFORM_CANCEL: labelField('zkPermits/v1/platformCancel'),
+  // Key changes: a new payout address (threshold, after a delay), a permit moving to a new holder key.
+  PAYOUT:        labelField('zkPermits/v1/payout'),
+  PAYOUT_CANCEL: labelField('zkPermits/v1/payoutCancel'),
+  REKEY:         labelField('zkPermits/v1/rekey'),
+};
+
+/** Network in signed messages. 0 is never valid. */
+export const PERMIT_NETWORK: Readonly<{ devnet: Field; mainnet: Field }> = { devnet: Field(1), mainnet: Field(2) };
+export type PermitNetwork = keyof typeof PERMIT_NETWORK;
+
+export function networkField(network: PermitNetwork): Field {
+  const f = PERMIT_NETWORK[network];
+  if (!f) throw new Error(`unknown network ${network}`);
+  return f;
+}
+
+// ------------------------------------------------------------
+// Permit leaf
+// ------------------------------------------------------------
+
+/** MOVED: the permit moved to a new holder key (rekeyPermit), under a new subject; this leaf is closed. */
+export const PERMIT_STATUS = { ACTIVE: 0, SUSPENDED: 1, REVOKED: 2, MOVED: 3 } as const;
+export const PERMIT_STATUS_ACTIVE = UInt32.from(0);
+export const PERMIT_STATUS_SUSPENDED = UInt32.from(1);
+export const PERMIT_STATUS_REVOKED = UInt32.from(2);
+export const PERMIT_STATUS_MOVED = UInt32.from(3);
+
+/** Expiry value meaning "does not expire" (only if the policy allows it). */
+export const NO_EXPIRY_SLOT = UInt32.MAXINT();
+
+// `const X: any = Struct(...)` — same pattern as licenseLeaf.ts: the inferred
+// Struct class type references o1js internals outside this package's rootDir.
+export const PermitLeaf: any = Struct({
+  subject:    Field,
+  holderKey:  PublicKey,
+  scope:      Field,
+  validFrom:  UInt32,
+  expirySlot: UInt32,
+  status:     UInt32,
+  seq:        UInt32,
+  docHash:    Field,
+});
+export type PermitLeaf = any;
+
+/** Hash stored in the permits MerkleMap. An empty map slot is Field(0). */
+export function permitLeafHash(leaf: PermitLeaf): Field {
+  return Poseidon.hash([PERMIT_TAGS.LEAF, ...PermitLeaf.toFields(leaf)]);
+}
+
+/** Tree key of an operator: hides the key behind a salt. */
+export function permitSubject(holderKey: PublicKey, salt: Field): Field {
+  return Poseidon.hash([PERMIT_TAGS.SUBJECT, ...holderKey.toFields(), salt]);
+}
+
+/** Leaf value for a subject that has never held a permit. */
+export function emptyPermitLeaf(subject: Field): PermitLeaf {
+  return new PermitLeaf({
+    subject,
+    holderKey: PublicKey.empty(),
+    scope: Field(0),
+    validFrom: UInt32.zero,
+    expirySlot: UInt32.zero,
+    status: PERMIT_STATUS_ACTIVE,
+    seq: UInt32.zero,
+    docHash: Field(0),
+  });
+}
+
+// ------------------------------------------------------------
+// Packed fees and policy
+// ------------------------------------------------------------
+
+const TWO_64 = 1n << 64n;
+
+export type PermitFees = { grantFee: UInt64; renewalFee: UInt64; minFee: UInt64 };
+
+/** grantFee | renewalFee << 64 | minFee << 128 (nanomina). */
+export function packFees(f: PermitFees): Field {
+  return f.grantFee.value
+    .add(f.renewalFee.value.mul(Field(TWO_64)))
+    .add(f.minFee.value.mul(Field(TWO_64 * TWO_64)));
+}
+
+/** Inverse of packFees; range-checks every part (safe in-circuit). */
+export function unpackFees(packed: Field): PermitFees {
+  const bits = packed.toBits(192);
+  return {
+    grantFee:   UInt64.Unsafe.fromField(Field.fromBits(bits.slice(0, 64))),
+    renewalFee: UInt64.Unsafe.fromField(Field.fromBits(bits.slice(64, 128))),
+    minFee:     UInt64.Unsafe.fromField(Field.fromBits(bits.slice(128, 192))),
+  };
+}
+
+/** Default minimum permit fee: 10 MINA. Configurable per registry at initialize. */
+export const DEFAULT_MIN_PERMIT_FEE = UInt64.from(10_000_000_000n);
+
+/** Platform share of a fee: 2%, rounded down (rounding favours the authority). */
+export const PERMIT_PLATFORM_FEE_BASIS = UInt64.from(50);
+export function platformShare(fee: UInt64): UInt64 {
+  return fee.div(PERMIT_PLATFORM_FEE_BASIS);
+}
+
+export type PermitPolicy = {
+  gracePeriod: UInt32;       // slots after expiry still reported as valid
+  maxTerm: UInt32;           // max expirySlot - validFrom; 0 = unlimited
+  singleKeySuspend: Bool;    // any one authority key may suspend
+  holderSigRequired: Bool;   // grant needs the holder's countersignature
+};
+
+/** gracePeriod | maxTerm << 32 | singleKeySuspend << 64 | holderSigRequired << 65 */
+export function packPolicy(p: PermitPolicy): Field {
+  return p.gracePeriod.value
+    .add(p.maxTerm.value.mul(Field(1n << 32n)))
+    .add(p.singleKeySuspend.toField().mul(Field(1n << 64n)))
+    .add(p.holderSigRequired.toField().mul(Field(1n << 65n)));
+}
+
+export function unpackPolicy(packed: Field): PermitPolicy {
+  const bits = packed.toBits(66);
+  return {
+    gracePeriod:       UInt32.Unsafe.fromField(Field.fromBits(bits.slice(0, 32))),
+    maxTerm:           UInt32.Unsafe.fromField(Field.fromBits(bits.slice(32, 64))),
+    singleKeySuspend:  bits[64],
+    holderSigRequired: bits[65],
+  };
+}
+
+// ------------------------------------------------------------
+// Application terms
+// ------------------------------------------------------------
+
+export type ApplicationTerms = {
+  processingFee: UInt64;     // kept on rejection or withdrawal (nanomina)
+  minProcessingFee: UInt64;  // platform minimum, fixed for the generation
+  decisionWindow: UInt32;    // slots from filing to the decision deadline
+};
+
+/** processingFee | minProcessingFee << 64 | decisionWindow << 128 */
+export function packApplicationTerms(t: ApplicationTerms): Field {
+  return t.processingFee.value
+    .add(t.minProcessingFee.value.mul(Field(TWO_64)))
+    .add(t.decisionWindow.value.mul(Field(TWO_64 * TWO_64)));
+}
+
+export function unpackApplicationTerms(packed: Field): ApplicationTerms {
+  const bits = packed.toBits(160);
+  return {
+    processingFee:    UInt64.Unsafe.fromField(Field.fromBits(bits.slice(0, 64))),
+    minProcessingFee: UInt64.Unsafe.fromField(Field.fromBits(bits.slice(64, 128))),
+    decisionWindow:   UInt32.Unsafe.fromField(Field.fromBits(bits.slice(128, 160))),
+  };
+}
+
+/** Default minimum processing fee: 1 MINA. Configurable per registry at initialize. */
+export const DEFAULT_MIN_PROCESSING_FEE = UInt64.from(1_000_000_000n);
+/** Default decision window: 14 days of 90 s slots (as licensing's refund window). */
+export const DEFAULT_DECISION_WINDOW = UInt32.from(13_440);
+/** Longest decision window an authority may set: one year. */
+export const MAX_DECISION_WINDOW = UInt32.from(350_640);
+
+/**
+ * An application with its fee in escrow. Stored as `applicationHash` in the
+ * registry's escrow MerkleMap under `subject`; emitted in full when filed.
+ * `baseSeq` is the permit leaf's `seq` it applies to (0 = new permit);
+ * `fee` is the whole amount escrowed, `processingFee` the part kept on
+ * rejection or withdrawal; both are locked at filing. `filing` is the
+ * registry's filing number (its filingCount when filed), so two filings
+ * never share a hash and a signature settling one can't settle another.
+ */
+export const Application: any = Struct({
+  subject:       Field,
+  holderKey:     PublicKey,
+  payer:         PublicKey,
+  baseSeq:       UInt32,
+  scope:         Field,
+  validFrom:     UInt32,
+  expirySlot:    UInt32,
+  docHash:       Field,
+  fee:           UInt64,
+  processingFee: UInt64,
+  deadline:      UInt32,
+  filing:        UInt32,
+});
+export type Application = any;
+
+export function applicationHash(app: Application): Field {
+  return Poseidon.hash([PERMIT_TAGS.APPLICATION, ...Application.toFields(app)]);
+}
+
+/**
+ * What the holder agrees to when applying: everything in the application
+ * except the payer (the transaction sender), the deadline (set by the
+ * contract from the filing slot) and the filing number (the registry's next).
+ */
+export function applicationTermsHash(app: Application): Field {
+  return Poseidon.hash([
+    PERMIT_TAGS.APPLICATION, app.subject, ...app.holderKey.toFields(), app.baseSeq.value, app.scope,
+    app.validFrom.value, app.expirySlot.value, app.docHash, app.fee.value, app.processingFee.value,
+  ]);
+}
+
+/** The permit leaf an approved application becomes. */
+export function leafFromApplication(app: Application): PermitLeaf {
+  return new PermitLeaf({
+    subject: app.subject,
+    holderKey: app.holderKey,
+    scope: app.scope,
+    validFrom: app.validFrom,
+    expirySlot: app.expirySlot,
+    status: PERMIT_STATUS_ACTIVE,
+    seq: app.baseSeq.add(1),
+    docHash: app.docHash,
+  });
+}
+
+/** Outcome codes in `applicationSettled` events. */
+export const APPLICATION_OUTCOME = { APPROVED: 1, REJECTED: 2, WITHDRAWN: 3, RECLAIMED: 4, CANCELLED: 5 } as const;
+
+// ------------------------------------------------------------
+// Authority key set
+// ------------------------------------------------------------
+
+export const MAX_AUTHORITY_KEYS = 3;
+
+// Fixed-length key set. `count` keys are in use (slots 0..count-1); unused
+// slots hold PublicKey.empty() and never count toward a threshold, whatever
+// signature is supplied for them.
+export const AuthorityKeys: any = Struct({
+  keys: Provable.Array(PublicKey, MAX_AUTHORITY_KEYS),
+  count: UInt32,
+  threshold: UInt32,
+});
+export type AuthorityKeys = any;
+
+export function authorityKeys(keys: PublicKey[], threshold: number): AuthorityKeys {
+  if (keys.length < 1 || keys.length > MAX_AUTHORITY_KEYS) throw new Error(`1..${MAX_AUTHORITY_KEYS} authority keys`);
+  if (!Number.isInteger(threshold) || threshold < 1 || threshold > keys.length) throw new Error('threshold must be 1..number of keys');
+  const b58 = keys.map(k => k.toBase58());
+  if (new Set(b58).size !== b58.length) throw new Error('authority keys must be distinct');
+  const padded = [...keys];
+  while (padded.length < MAX_AUTHORITY_KEYS) padded.push(PublicKey.empty());
+  return new AuthorityKeys({ keys: padded, count: UInt32.from(keys.length), threshold: UInt32.from(threshold) });
+}
+
+// One optional signature per key slot. `present[i]` false → slot i ignored.
+export const AuthoritySigs: any = Struct({
+  sigs: Provable.Array(Signature, MAX_AUTHORITY_KEYS),
+  present: Provable.Array(Bool, MAX_AUTHORITY_KEYS),
+});
+export type AuthoritySigs = any;
+
+// Placeholder for absent slots: a well-formed signature over an unrelated
+// one-field message. Absent slots are never counted anyway.
+let placeholder: Signature | null = null;
+function placeholderSignature(): Signature {
+  placeholder ??= Signature.create(PrivateKey.fromBigInt(1n), [Field(0)]);
+  return placeholder;
+}
+
+/** Builds the signature bundle from `{ slotIndex: signature }` (base58 or Signature). */
+export function authoritySigs(bySlot: Record<number, Signature | string>): AuthoritySigs {
+  const sigs: Signature[] = [];
+  const present: Bool[] = [];
+  for (let i = 0; i < MAX_AUTHORITY_KEYS; i++) {
+    const s = bySlot[i];
+    if (s === undefined) { sigs.push(placeholderSignature()); present.push(Bool(false)); continue; }
+    sigs.push(typeof s === 'string' ? Signature.fromBase58(s) : s);
+    present.push(Bool(true));
+  }
+  return new AuthoritySigs({ sigs, present });
+}
+
+/**
+ * Number of valid signatures over `message` from distinct, in-use key
+ * slots. Works in-circuit. Absent or unused slots count zero; a present
+ * signature that doesn't verify also counts zero.
+ */
+export function countAuthoritySignatures(keys: AuthorityKeys, sigs: AuthoritySigs, message: Field[]): UInt32 {
+  let n = UInt32.zero;
+  for (let i = 0; i < MAX_AUTHORITY_KEYS; i++) {
+    const inUse = UInt32.from(i).lessThan(keys.count);
+    // An unused slot's key is PublicKey.empty(); verify against a real key
+    // instead so the check stays well-formed. The result is masked by inUse.
+    const key = Provable.if(inUse, PublicKey, keys.keys[i], keys.keys[0]);
+    const ok = sigs.sigs[i].verify(key, message);
+    const counted = inUse.and(sigs.present[i]).and(ok);
+    n = n.add(Provable.if(counted, UInt32.from(1), UInt32.zero));
+  }
+  return n;
+}
+
+/**
+ * In-circuit validity of a key set: 1 ≤ count ≤ MAX, 1 ≤ threshold ≤ count,
+ * in-use keys pairwise distinct, unused slots empty.
+ */
+export function assertValidAuthorityKeys(keys: AuthorityKeys): void {
+  keys.count.assertGreaterThanOrEqual(UInt32.from(1));
+  keys.count.assertLessThanOrEqual(UInt32.from(MAX_AUTHORITY_KEYS));
+  keys.threshold.assertGreaterThanOrEqual(UInt32.from(1));
+  keys.threshold.assertLessThanOrEqual(keys.count);
+  for (let i = 0; i < MAX_AUTHORITY_KEYS; i++) {
+    const inUse = UInt32.from(i).lessThan(keys.count);
+    // Unused slots must be empty so the commitment is canonical.
+    inUse.or(keys.keys[i].equals(PublicKey.empty())).assertTrue();
+    // In-use keys are real keys, and distinct from every other in-use key.
+    inUse.not().or(keys.keys[i].equals(PublicKey.empty()).not()).assertTrue();
+    for (let j = i + 1; j < MAX_AUTHORITY_KEYS; j++) {
+      const bothInUse = UInt32.from(j).lessThan(keys.count);
+      bothInUse.not().or(keys.keys[i].equals(keys.keys[j]).not()).assertTrue();
+    }
+  }
+}
+
+/** Commitment stored on-chain as `authorityKeysHash`. */
+export function authorityKeysHash(k: AuthorityKeys): Field {
+  return Poseidon.hash([PERMIT_TAGS.KEYS, ...AuthorityKeys.toFields(k)]);
+}
+
+// ------------------------------------------------------------
+// Messages
+// ------------------------------------------------------------
+
+/**
+ * Message an authority key signs:
+ *   [tag, network, registry.x, registry.isOdd, epoch, nonce, payloadHash]
+ * `nonce` is the leaf's `seq` for per-permit actions and the registry's
+ * `actionNonce` for registry-wide ones (setFees, rotate, init = 0).
+ */
+export function authorityMessage(
+  tag: Field, network: Field, registry: PublicKey, epoch: UInt32, nonce: UInt32, payload: Field[],
+): Field[] {
+  return [tag, network, ...registry.toFields(), epoch.value, nonce.value, Poseidon.hash(payload)];
+}
+
+export function initMessage(a: {
+  network: Field; registry: PublicKey; keysHash: Field; policyPacked: Field; feesPacked: Field;
+  appTermsPacked: Field; metadataHash: Field; payout: PublicKey; forkActivationSlot: UInt32;
+  predecessor: PublicKey; initialPermitsRoot: Field;
+}): Field[] {
+  // On a redeploy, the registry this one continues and the frozen permits
+  // tree it starts with (the chain checks both); PublicKey.empty() and the
+  // empty root for a first generation.
+  return authorityMessage(PERMIT_TAGS.INIT, a.network, a.registry, UInt32.zero, UInt32.zero,
+    [a.keysHash, a.policyPacked, a.feesPacked, a.appTermsPacked, a.metadataHash, ...a.payout.toFields(), a.forkActivationSlot.value, ...a.predecessor.toFields(), a.initialPermitsRoot]);
+}
+
+/** Authority approval of a leaf change (issue, renew, scope change). Nonce = oldLeaf.seq. */
+export function grantMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; oldLeaf: PermitLeaf; newLeaf: PermitLeaf;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.GRANT, a.network, a.registry, a.epoch, a.oldLeaf.seq,
+    [permitLeafHash(a.oldLeaf), permitLeafHash(a.newLeaf)]);
+}
+
+/** The operator's acceptance of a grant, including the fee it pays. */
+export function acceptMessage(a: { network: Field; registry: PublicKey; newLeaf: PermitLeaf; fee: UInt64 }): Field[] {
+  return [PERMIT_TAGS.ACCEPT, a.network, ...a.registry.toFields(), permitLeafHash(a.newLeaf), a.fee.value];
+}
+
+export type StatusAction = 'suspend' | 'reinstate' | 'revoke';
+const STATUS_TAG: Record<StatusAction, Field> = {
+  suspend: PERMIT_TAGS.SUSPEND, reinstate: PERMIT_TAGS.REINSTATE, revoke: PERMIT_TAGS.REVOKE,
+};
+
+/** Authority status change of a permit. Nonce = leaf.seq. */
+export function statusMessage(action: StatusAction, a: {
+  network: Field; registry: PublicKey; epoch: UInt32; leaf: PermitLeaf; reasonCode: Field;
+}): Field[] {
+  return authorityMessage(STATUS_TAG[action], a.network, a.registry, a.epoch, a.leaf.seq,
+    [permitLeafHash(a.leaf), a.reasonCode]);
+}
+
+/** The holder giving up their permit. */
+export function surrenderMessage(a: { network: Field; registry: PublicKey; leaf: PermitLeaf }): Field[] {
+  return [PERMIT_TAGS.SURRENDER, a.network, ...a.registry.toFields(), permitLeafHash(a.leaf), a.leaf.seq.value];
+}
+
+/** New fees and application terms (processing fee, decision window). */
+export function setFeesMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32; newFeesPacked: Field; newAppTermsPacked: Field;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.SET_FEES, a.network, a.registry, a.epoch, a.actionNonce,
+    [a.newFeesPacked, a.newAppTermsPacked]);
+}
+
+/**
+ * The authority retires the registry, freezing its permits at `permitsRoot`
+ * (the root the redeployed registry's ancestorsRoot commits to). Bound to the
+ * epoch and action nonce like the other registry-wide actions.
+ */
+export function retireMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32; permitsRoot: Field;
+  /** The one registry that may start from these permits (stored on chain). */
+  successor: PublicKey;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.RETIRE, a.network, a.registry, a.epoch, a.actionNonce, [a.permitsRoot, ...a.successor.toFields()]);
+}
+
+/**
+ * The platform's retirement of a registry (`retireByPlatform`): what the
+ * platform key signs, the fields of retireMessage under its own tag (so
+ * neither signature can stand in for the other) plus `force`: retire with
+ * application fees still in escrow, which then stay on the retired registry.
+ */
+export function platformRetireMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32; permitsRoot: Field; successor: PublicKey; force: Bool;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.PLATFORM_RETIRE, a.network, a.registry, a.epoch, a.actionNonce, [a.permitsRoot, ...a.successor.toFields(), a.force.toField()]);
+}
+
+/**
+ * authorityKeysHash of a retired registry: no key set hashes to it, so no
+ * authority action can run again, and filing and surrender check
+ * it. (0 means not yet initialized.)
+ */
+export const RETIRED_KEYS_HASH: Field = Field(1);
+
+export function rotateMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32; newKeysHash: Field;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.ROTATE, a.network, a.registry, a.epoch, a.actionNonce, [a.newKeysHash]);
+}
+
+// ------------------------------------------------------------
+// Application escrow messages
+// ------------------------------------------------------------
+
+/** The holder's application: the terms and the fee they put in escrow. */
+export function applyMessage(a: { network: Field; registry: PublicKey; application: Application }): Field[] {
+  return [PERMIT_TAGS.APPLY, a.network, ...a.registry.toFields(), applicationTermsHash(a.application)];
+}
+
+/** Authority approval of an application exactly as filed. Nonce = baseSeq. */
+export function approveMessage(a: { network: Field; registry: PublicKey; epoch: UInt32; application: Application }): Field[] {
+  return authorityMessage(PERMIT_TAGS.APPROVE, a.network, a.registry, a.epoch, a.application.baseSeq,
+    [applicationHash(a.application)]);
+}
+
+/** Authority rejection of an application. Nonce = baseSeq. */
+export function rejectMessage(a: {
+  network: Field; registry: PublicKey; epoch: UInt32; application: Application; reasonCode: Field;
+}): Field[] {
+  return authorityMessage(PERMIT_TAGS.REJECT, a.network, a.registry, a.epoch, a.application.baseSeq,
+    [applicationHash(a.application), a.reasonCode]);
+}
+
+/**
+ * The platform cancelling the open applications of a registry before it
+ * retires it (`cancelApplication`, e.g. ahead of a hard fork): every
+ * application filed before filing number `cutoff` (the registry's filing
+ * count when signed) may be cancelled, its whole fee back to its payer. One
+ * signature covers them all; anyone may send the cancellations. Later
+ * filings it never covers.
+ */
+export function cancelMessage(a: { network: Field; registry: PublicKey; cutoff: UInt32 }): Field[] {
+  return [PERMIT_TAGS.PLATFORM_CANCEL, a.network, ...a.registry.toFields(), a.cutoff.value];
+}
+
+/**
+ * A new payout address for the registry (threshold, registry-wide nonce):
+ * it takes effect PAYOUT_DELAY_SLOTS_N after it is proposed, unless the keys
+ * cancel it (payoutCancelMessage) meanwhile.
+ */
+export function payoutMessage(a: { network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32; payout: PublicKey }): Field[] {
+  return authorityMessage(PERMIT_TAGS.PAYOUT, a.network, a.registry, a.epoch, a.actionNonce, a.payout.toFields());
+}
+
+export function payoutCancelMessage(a: { network: Field; registry: PublicKey; epoch: UInt32; actionNonce: UInt32 }): Field[] {
+  return authorityMessage(PERMIT_TAGS.PAYOUT_CANCEL, a.network, a.registry, a.epoch, a.actionNonce, []);
+}
+
+/**
+ * A permit moving to a new holder key (rekeyPermit), with the same terms,
+ * under the new subject permitSubject(newHolderKey, newSalt): signed by the
+ * current holder key and the new one, over the permit as it is now. The old
+ * leaf is closed (MOVED), so the signatures can't be used twice.
+ */
+export function rekeyMessage(a: { network: Field; registry: PublicKey; leaf: PermitLeaf; newSubject: Field; newHolderKey: PublicKey }): Field[] {
+  return [PERMIT_TAGS.REKEY, a.network, ...a.registry.toFields(), permitLeafHash(a.leaf), a.newSubject, ...a.newHolderKey.toFields()];
+}
+
+/** The holder withdrawing their application before a decision. */
+export function withdrawMessage(a: { network: Field; registry: PublicKey; application: Application }): Field[] {
+  return [PERMIT_TAGS.WITHDRAW, a.network, ...a.registry.toFields(), applicationHash(a.application)];
+}
+
+/** What both wallets sign (signMessage) to move an authority account to a new wallet. */
+export function authorityMoveText(from: string, to: string): string {
+  return [
+    'zkPermits: move my authority account to a new wallet',
+    `from: ${from}`,
+    `to: ${to}`,
+    'Both wallets sign this. The account and its registries move to the new wallet; registry keys change by a rotation.',
+  ].join('\n');
+}
+
+/** Decimal strings for a wallet's `signFields({ message })`. */
+export function toSignableFields(message: Field[]): string[] {
+  return message.map(f => f.toString());
+}