@calimero-network/mero-js 24.1.3 → 24.3.0

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
+export type { RelayClientConfig, RelayExecutor, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
 export { createMemoryNonceSource, createLocalStorageNonceSource, createRecoveringNonceSource, authorNonceLookup, WarrantNonceExhaustedError, } from './nonce-source.js';
 export type { NonceSource, WarrantNonceLookup, RecoveringNonceSourceOptions, } from './nonce-source.js';

package/dist/relay/relay-client.d.ts

@@ -18,10 +18,11 @@
  * # The three preconditions, and why they are checked in this order
  *
  * `describe()` answers the first two in one call, before anything is signed:
- * the relay's executor account (which the warrant must name) and whether it
- * holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third — that the
- * author's account is a member — only the group knows, and it surfaces as a
- * refusal.
+ * the relay's executor account and signing key and the release the context's
+ * group names (which the warrant must name), and whether it holds
+ * `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
+ * that the author's account is a member, only the group knows, and it surfaces
+ * as a refusal.
  *
  * Checking before signing is not politeness. A warrant consumes a nonce from a
  * monotonic per-device sequence, and one minted against the wrong executor is
@@ -42,9 +43,8 @@ export interface RelayClientConfig {
     /**
      * The account the relay writes as, hex — a warrant's `executor`.
      *
-     * An account rather than a key, so one of the relay's processes rotating its
-     * signing key does not void warrants already issued to it. Left unset, the
-     * first `execute` learns it from {@link RelayClient.describe}.
+     * Only checked against what the relay answers: a warrant also names the
+     * relay's signing key and the release, which only discovery reports, so every write asks.
      */
     executorAccount?: string;
     /** The author's account, hex — whose consent the warrant carries. */
@@ -84,9 +84,9 @@ export interface RelayClientConfig {
     /**
      * Seconds a minted warrant stays valid. Defaults to 300.
      *
-     * Checked by the relay against its own clock and deliberately never by peers,
-     * so this bounds how long *this* request may sit in flight — not how long the
-     * network will accept the delta.
+     * Checked by the relay against its own clock, and by peers against the
+     * delta's own signed stamp, never their clocks: this bounds how long *this*
+     * request may sit in flight before the relay runs it.
      */
     ttlSeconds?: number;
     /** Injected for tests and non-browser runtimes. Defaults to global `fetch`. */
@@ -101,19 +101,29 @@ export interface RelayClientConfig {
      */
     rateLimitRetries?: number;
 }
-/** What a relay says about its ability to run intents in one context. */
-export interface RelayDescription {
+/** The relay a warrant names: its account, and the one key of it that may spend the warrant. */
+export interface RelayExecutor {
     /** The account a warrant must name as `executor`, hex. */
     executorAccount: string;
+    /** The signing key a warrant must name as `executor_key`, hex. */
+    executorKey: string;
+}
+/** What a relay says about its ability to run intents in one context. */
+export interface RelayDescription extends RelayExecutor {
     /** Whether the relay holds `CAN_AUTHOR_ON_BEHALF` on the owning group. */
     canAuthorOnBehalf: boolean;
     /** The group whose admin grants that capability, hex. */
     groupId: string;
+    /**
+     * The blob id of the release the group names, hex: what a warrant must pin
+     * as `release_bytecode_id`. Discovery answers 404 while the group names none.
+     */
+    releaseBytecodeId: string;
+    /** That release's semver, signed as the warrant's `release_version`. */
+    releaseVersion: string;
 }
 /** What a relay says about its ability to create contexts in one group. */
-export interface CreationDescription {
-    /** The account a creation warrant must name as `executor`, hex. */
-    executorAccount: string;
+export interface CreationDescription extends RelayExecutor {
     /** The group, hex. */
     groupId: string;
     /**
@@ -156,9 +166,7 @@ export interface CreatedContext {
     memberPublicKey: string;
 }
 /** What a relay says about publishing governance ops for members of one group. */
-export interface GovernanceDescription {
-    /** The account a governance warrant must name as `executor`, hex. */
-    executorAccount: string;
+export interface GovernanceDescription extends RelayExecutor {
     /** The group asked about, hex. */
     groupId: string;
     /**
@@ -192,11 +200,10 @@ export interface FoundNamespaceInput {
      */
     salt?: string;
     /**
-     * The relay's account, hex: the warrant's `executor`. The namespace does not
-     * exist yet, so there is nothing to ask `describeGovernance` about. Falls back
-     * to the client's configured or already-learned `executorAccount`.
+     * The relay's account and node key (pinned, or from `resolveRelayNodeKey`). Never
+     * a discovery answer: that key is unauthenticated, and no namespace exists yet.
      */
-    executorAccount?: string;
+    executor: RelayExecutor;
     /**
      * The namespace root's default capability mask (`MemberCapabilities` bits),
      * set right after founding. A namespace is founded with core's minimal
@@ -292,7 +299,6 @@ export declare class IntentRefusedError extends Error {
 }
 export declare class RelayClient {
     private readonly baseUrl;
-    private executorAccount;
     private readonly config;
     private readonly fetchImpl;
     private readonly timeoutMs;
@@ -389,7 +395,7 @@ export declare class RelayClient {
     createContext(input: CreateContextInput): Promise<CreatedContext>;
     /**
      * Ask the relay whether it may publish governance ops for members of
-     * `groupId`, and which account a warrant must name.
+     * `groupId`, and which account and key a warrant must name.
      */
     describeGovernance(groupId: string): Promise<GovernanceDescription>;
     /**
@@ -427,9 +433,7 @@ export declare class RelayClient {
      *
      * The executor cannot be learned from the relay first: the namespace does not
      * exist, so `describeGovernance` has nothing to answer about. It comes from
-     * `input.executorAccount`, the configured one, or one an earlier call learned
-     * (`describe`, `createContext`, `govern`), and without any of them this
-     * throws before taking a nonce.
+     * `input.executor` only, and without it this throws before taking a nonce.
      * The nonce is spent in the new namespace's ledger.
      *
      * With `defaultCapabilities`, the founder then sets the namespace's default
@@ -440,11 +444,11 @@ export declare class RelayClient {
      * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
      * that names an existing namespace is a `409`, an `HTTPError`.
      */
-    foundNamespace(input?: FoundNamespaceInput): Promise<FoundedNamespace>;
+    foundNamespace(input: FoundNamespaceInput): Promise<FoundedNamespace>;
     private postGovernance;
     /**
-     * The executor a warrant must name: the one the relay answered with, which a
-     * configured account must agree with. Remembered for later calls.
+     * The relay's answer, checked against a configured account.
+     * Decoded here so a relay naming no key is refused before a nonce is taken.
      */
     private checkedExecutor;
     /**

package/dist/relay/relay-client.js

@@ -18,16 +18,17 @@
  * # The three preconditions, and why they are checked in this order
  *
  * `describe()` answers the first two in one call, before anything is signed:
- * the relay's executor account (which the warrant must name) and whether it
- * holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third — that the
- * author's account is a member — only the group knows, and it surfaces as a
- * refusal.
+ * the relay's executor account and signing key and the release the context's
+ * group names (which the warrant must name), and whether it holds
+ * `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
+ * that the author's account is a member, only the group knows, and it surfaces
+ * as a refusal.
  *
  * Checking before signing is not politeness. A warrant consumes a nonce from a
  * monotonic per-device sequence, and one minted against the wrong executor is
  * unspendable: the number is gone and the write never happened.
  */
-import { signWarrant } from '../warrant/warrant.js';
+import { releaseVersionBytes, signWarrant } from '../warrant/warrant.js';
 import { resolveSigner } from '../signer/signer.js';
 import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
@@ -85,7 +86,6 @@ export class RelayClient {
     constructor(config) {
         this.config = config;
         this.baseUrl = config.relayUrl.replace(/\/+$/, '');
-        this.executorAccount = config.executorAccount;
         const injected = config.fetch;
         this.fetchImpl = injected
             ? (input, init) => injected(input, init)
@@ -138,9 +138,6 @@ export class RelayClient {
      */
     async describe(contextId) {
         const body = await this.json('GET', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`);
-        // Learned, not merely returned: a client that called `describe` should not
-        // then have to pass the account back in to `execute`.
-        this.executorAccount = body.data.executorAccount;
         return body.data;
     }
     /**
@@ -151,7 +148,13 @@ export class RelayClient {
      * apply. Nothing accumulates and nothing is reusable.
      */
     async execute(contextId, method, argsJson = {}) {
-        const executor = this.executorAccount ?? (await this.describe(contextId)).executorAccount;
+        // Asked on every write: the release moves with each upgrade of the group, and a
+        // warrant pinning the one before is refused. All of it is checked before the nonce.
+        const described = await this.describe(contextId);
+        const executor = this.checkedExecutor(described);
+        const releaseBytecodeId = hex(fromHex(described.releaseBytecodeId ?? '', "the relay's releaseBytecodeId", 32));
+        const releaseVersion = described.releaseVersion ?? '';
+        releaseVersionBytes(releaseVersion);
         // Resolved before the nonce, so a misconfigured key burns none.
         const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
@@ -159,7 +162,10 @@ export class RelayClient {
         const warrant = await signWarrant({
             context: contextId,
             authorAccount: this.config.authorAccount,
-            executor,
+            executor: executor.executorAccount,
+            executorKey: executor.executorKey,
+            releaseBytecodeId,
+            releaseVersion,
             method,
             argsJson,
             nonce,
@@ -224,7 +230,7 @@ export class RelayClient {
                 `${described.groupId}; it needs CAN_CREATE_CONTEXT or admin ` +
                 '(checked before signing — no nonce was spent)', false, 403);
         }
-        const executor = this.checkedExecutor(described.executorAccount);
+        const executor = this.checkedExecutor(described);
         const initArgs = input.initArgs ?? {};
         // Resolved before the nonce, so a misconfigured key burns none.
         const signer = await this.authorSigner();
@@ -234,7 +240,8 @@ export class RelayClient {
             group: input.groupId,
             seed: input.seed,
             authorAccount: this.config.authorAccount,
-            executor,
+            executor: executor.executorAccount,
+            executorKey: executor.executorKey,
             applicationId: input.applicationId,
             serviceName: input.serviceName,
             name: input.name,
@@ -252,7 +259,7 @@ export class RelayClient {
     }
     /**
      * Ask the relay whether it may publish governance ops for members of
-     * `groupId`, and which account a warrant must name.
+     * `groupId`, and which account and key a warrant must name.
      */
     async describeGovernance(groupId) {
         const body = await this.json('GET', `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`);
@@ -281,7 +288,7 @@ export class RelayClient {
                 `${described.groupId}; an admin must admit it as a relay or grant it CAN_AUTHOR_ON_BEHALF ` +
                 '(checked before signing, no nonce was spent)', false, 403);
         }
-        const executor = this.checkedExecutor(described.executorAccount);
+        const executor = this.checkedExecutor(described);
         // Resolved before the nonce, so a misconfigured key burns none.
         const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
@@ -290,7 +297,8 @@ export class RelayClient {
             scope: input.groupId,
             op: input.op,
             authorAccount: this.config.authorAccount,
-            executor,
+            executor: executor.executorAccount,
+            executorKey: executor.executorKey,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
             signer,
@@ -316,9 +324,7 @@ export class RelayClient {
      *
      * The executor cannot be learned from the relay first: the namespace does not
      * exist, so `describeGovernance` has nothing to answer about. It comes from
-     * `input.executorAccount`, the configured one, or one an earlier call learned
-     * (`describe`, `createContext`, `govern`), and without any of them this
-     * throws before taking a nonce.
+     * `input.executor` only, and without it this throws before taking a nonce.
      * The nonce is spent in the new namespace's ledger.
      *
      * With `defaultCapabilities`, the founder then sets the namespace's default
@@ -329,14 +335,12 @@ export class RelayClient {
      * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
      * that names an existing namespace is a `409`, an `HTTPError`.
      */
-    async foundNamespace(input = {}) {
-        const executor = input.executorAccount
-            ? this.checkedExecutor(input.executorAccount)
-            : this.executorAccount;
-        if (!executor) {
-            throw new Error("foundNamespace needs the relay's account: pass executorAccount or configure it " +
+    async foundNamespace(input) {
+        if (!input?.executor) {
+            throw new Error("foundNamespace needs the relay's account and signing key: pass executor " +
                 '(checked before signing, no nonce was spent)');
         }
+        const executor = this.checkedExecutor(input.executor);
         const salt = input.salt
             ? hex(fromHex(input.salt, 'salt', 32))
             : hex(crypto.getRandomValues(new Uint8Array(32)));
@@ -360,7 +364,8 @@ export class RelayClient {
             scope: namespaceId,
             op,
             authorAccount: this.config.authorAccount,
-            executor,
+            executor: executor.executorAccount,
+            executorKey: executor.executorKey,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
             signer,
@@ -408,17 +413,20 @@ export class RelayClient {
         return body.data;
     }
     /**
-     * The executor a warrant must name: the one the relay answered with, which a
-     * configured account must agree with. Remembered for later calls.
+     * The relay's answer, checked against a configured account.
+     * Decoded here so a relay naming no key is refused before a nonce is taken.
      */
     checkedExecutor(answered) {
+        const executor = {
+            executorAccount: hex(fromHex(answered.executorAccount ?? '', "the relay's executorAccount", 32)),
+            executorKey: hex(fromHex(answered.executorKey ?? '', "the relay's executorKey", 32)),
+        };
         const configured = this.config.executorAccount;
-        if (configured && configured.toLowerCase() !== answered.toLowerCase()) {
+        if (configured && configured.toLowerCase() !== executor.executorAccount) {
             throw new Error(`configured executorAccount ${configured} is not the relay's account ` +
-                `${answered}; a warrant naming it would be unspendable`);
+                `${executor.executorAccount}; a warrant naming it would be unspendable`);
         }
-        this.executorAccount = answered;
-        return answered;
+        return executor;
     }
     /**
      * One request, waiting out a rate limit rather than failing the caller.

package/dist/warrant/creation-warrant.d.ts

@@ -36,8 +36,10 @@ export interface CreationWarrantInput {
     seed?: string;
     /** The author's account, hex — whose consent this is, and who runs `init`. */
     authorAccount: string;
-    /** The relay authorised to act, hex. An account, not a key. */
+    /** The relay's account, hex: the subject its authorship grant is held by. */
     executor: string;
+    /** The one signing key of `executor` that may carry it out, hex: discovery's `executorKey`. */
+    executorKey: string;
     /** The application the context is created with, hex (32 bytes). */
     applicationId: string;
     /**
@@ -103,6 +105,7 @@ export interface CreationWarrantFields {
     /** The author device key: the signer's public key. */
     deviceKey: string;
     executor: string;
+    executorKey: string;
     applicationId: string;
     /** `null` when absent — distinct from `""`. */
     serviceName: string | null;
@@ -129,6 +132,7 @@ export interface CreationPreimageParts {
     authorAccount: Uint8Array;
     deviceKey: Uint8Array;
     executor: Uint8Array;
+    executorKey: Uint8Array;
     applicationId: Uint8Array;
     serviceName: Uint8Array | null;
     name: Uint8Array | null;

package/dist/warrant/creation-warrant.js

@@ -51,6 +51,7 @@ export async function creationWarrantPreimage(p) {
         p.authorAccount,
         p.deviceKey,
         p.executor,
+        p.executorKey,
         p.applicationId,
         new Uint8Array([p.serviceName === null ? 0 : 1]),
         p.serviceName ?? new Uint8Array(0),
@@ -78,6 +79,7 @@ export async function signCreationWarrant(input) {
         : fromHex(input.seed, 'seed', 32);
     const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
     const executor = fromHex(input.executor, 'executor', 32);
+    const executorKey = fromHex(input.executorKey, 'executorKey', 32);
     const applicationId = fromHex(input.applicationId, 'applicationId', 32);
     const serviceName = label(input.serviceName, 'serviceName');
     const name = label(input.name, 'name');
@@ -92,6 +94,7 @@ export async function signCreationWarrant(input) {
         authorAccount,
         deviceKey,
         executor,
+        executorKey,
         applicationId,
         serviceName,
         name,
@@ -102,7 +105,7 @@ export async function signCreationWarrant(input) {
         notAfter: input.notAfter,
     });
     const signature = checkedSignature(await signer.sign(preimage));
-    const warrant = hex(concat(group, seed, authorAccount, deviceKey, executor, applicationId, borshOption(serviceName), borshOption(name), initHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
+    const warrant = hex(concat(group, seed, authorAccount, deviceKey, executor, executorKey, applicationId, borshOption(serviceName), borshOption(name), initHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
     return { warrant, seed: hex(seed) };
 }
 /**
@@ -157,6 +160,7 @@ export function parseCreationWarrant(warrant) {
         authorAccount: hex(take(32, 'authorAccount')),
         deviceKey: hex(take(32, 'deviceKey')),
         executor: hex(take(32, 'executor')),
+        executorKey: hex(take(32, 'executorKey')),
         applicationId: hex(take(32, 'applicationId')),
         serviceName: option('serviceName'),
         name: option('name'),

package/dist/warrant/governance-warrant.d.ts

@@ -39,8 +39,10 @@ export interface GovernanceWarrantInput {
     op: GovernanceOp;
     /** The author's account, hex: whose authority the op is applied under. */
     authorAccount: string;
-    /** The relay authorised to publish it, hex. An account, not a key. */
+    /** The relay's account, hex: the subject its authorship grant is held by. */
     executor: string;
+    /** The one signing key of `executor` that may publish it, hex: discovery's `executorKey`. */
+    executorKey: string;
     /**
      * Monotonic per author **device**, spent in a per-group ledger. The same
      * nonce source `RelayClient` uses for every other warrant is correct.
@@ -76,6 +78,7 @@ export interface GovernanceWarrantFields {
     /** The author device key: the signer's public key. */
     deviceKey: string;
     executor: string;
+    executorKey: string;
     opHash: string;
     accountHeads: string[];
     governanceFloor: string[];
@@ -95,6 +98,7 @@ export interface GovernancePreimageParts {
     authorAccount: Uint8Array;
     deviceKey: Uint8Array;
     executor: Uint8Array;
+    executorKey: Uint8Array;
     opHash: Uint8Array;
     accountHeads: Uint8Array[];
     governanceFloor: Uint8Array[];

package/dist/warrant/governance-warrant.js

@@ -53,6 +53,7 @@ export async function governanceWarrantPreimage(p) {
         p.authorAccount,
         p.deviceKey,
         p.executor,
+        p.executorKey,
         p.opHash,
         u64le(p.accountHeads.length),
         ...p.accountHeads,
@@ -70,6 +71,7 @@ export async function signGovernanceWarrant(input) {
     const scope = fromHex(input.scope, 'scope', 32);
     const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
     const executor = fromHex(input.executor, 'executor', 32);
+    const executorKey = fromHex(input.executorKey, 'executorKey', 32);
     const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
     const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
     const kind = kindByte(input.op.kind);
@@ -82,6 +84,7 @@ export async function signGovernanceWarrant(input) {
         authorAccount,
         deviceKey,
         executor,
+        executorKey,
         opHash,
         accountHeads,
         governanceFloor,
@@ -89,7 +92,7 @@ export async function signGovernanceWarrant(input) {
         notAfter: input.notAfter,
     });
     const signature = checkedSignature(await signer.sign(preimage));
-    return hex(concat(scope, new Uint8Array([kind]), authorAccount, deviceKey, executor, opHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
+    return hex(concat(scope, new Uint8Array([kind]), authorAccount, deviceKey, executor, executorKey, opHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
 }
 /**
  * Decode a hex governance warrant back into its fields.
@@ -139,6 +142,7 @@ export function parseGovernanceWarrant(warrant) {
         authorAccount: hex(take(32, 'authorAccount')),
         deviceKey: hex(take(32, 'deviceKey')),
         executor: hex(take(32, 'executor')),
+        executorKey: hex(take(32, 'executorKey')),
         opHash: hex(take(32, 'opHash')),
         accountHeads: heads('accountHeads'),
         governanceFloor: heads('governanceFloor'),

package/dist/warrant/warrant.d.ts

@@ -42,24 +42,27 @@ export interface WarrantInput {
     context: string;
     /** The author's account, hex — whose consent this is. */
     authorAccount: string;
-    /** The relay authorised to act, hex. An account, not a key. */
+    /** The relay's account, hex: the subject its authorship grant is held by. */
     executor: string;
     /**
-     * The application build this warrant is signed against, hex (32 bytes).
-     *
-     * Pins the code rather than a version string, so a relay cannot wait for an
-     * upgrade that widens what `method` does and then spend a warrant signed
-     * against the narrower one. Read it from the context
-     * (`GET /admin-api/contexts/{id}` → `applicationId`); a value guessed here
-     * pins the wrong build, which is worse than not pinning.
+     * The one signing key of `executor` that may spend this warrant, hex: the
+     * relay's `executorKey` from discovery. Any other key of the account is refused.
+     */
+    executorKey: string;
+    /**
+     * The blob id of the release the context's group names, hex (32 bytes): the
+     * relay's `releaseBytecodeId` from discovery.
      *
-     * Defaults to 32 zero bytes, matching `merod account sign-warrant`'s
-     * `--app-version` default. Nothing verifies the field yet — core#3933 landed
-     * the field set ahead of its enforcement so a signer is written once against
-     * the final bytes — but a warrant minted with the default will be refused once
-     * pinning lands, so pass the real value for anything meant to outlive it.
+     * Pins the code, so a relay cannot wait for an upgrade that widens what
+     * `method` does and then spend a warrant signed against the narrower one. The
+     * relay refuses a warrant pinning any release other than the one it runs.
+     */
+    releaseBytecodeId: string;
+    /**
+     * That release's semver, discovery's `releaseVersion`: signed, never compared,
+     * at most 256 bytes of UTF-8. Defaults to empty, as `merod account warrant` does.
      */
-    appVersion?: string;
+    releaseVersion?: string;
     /**
      * The method the relay may run.
      *
@@ -144,6 +147,8 @@ export declare function signWarrant(input: WarrantInput): Promise<string>;
  * relay, far from the signer at fault. Internal.
  */
 export declare function checkedSignature(signature: Uint8Array): Uint8Array;
+/** A release version as UTF-8, refused past what a node accepts. Shared with `RelayClient`; internal. */
+export declare function releaseVersionBytes(version: string): Uint8Array;
 export declare function citedHeads(heads: string[] | undefined, label: string): Uint8Array[];
 /** A warrant's fields, as hex, decoded from the wire encoding. */
 export interface WarrantFields {
@@ -152,7 +157,10 @@ export interface WarrantFields {
     /** The author device key `signWarrant` derived from the secret. */
     deviceKey: string;
     executor: string;
-    appVersion: string;
+    executorKey: string;
+    releaseBytecodeId: string;
+    /** UTF-8, as hex like `method`. */
+    releaseVersion: string;
     method: string;
     intentHash: string;
     accountHeads: string[];
@@ -167,11 +175,11 @@ export interface WarrantFields {
  * Decode a hex warrant back into its fields.
  *
  * Exists because v2's offsets are no longer constants: `method` is a string and
- * the head lists are vectors, so everything after `appVersion` moves with the
- * method's length. Anything reading a warrant by fixed offset — a test, a client
- * inspecting one it was handed — silently reads the wrong field instead of
- * failing, which is how the three call sites that did so passed while comparing
- * the method's length prefix to a nonce.
+ * the head lists are vectors, so everything after `releaseBytecodeId` moves with
+ * the release version's and the method's lengths. Anything reading a warrant by
+ * fixed offset - a test, a client inspecting one it was handed - silently reads
+ * the wrong field instead of failing, which is how the three call sites that did
+ * so passed while comparing the method's length prefix to a nonce.
  *
  * One copy of the layout, beside the encoder that produces it, so the two cannot
  * drift. Internal: not exported from the package root, because a client that

package/dist/warrant/warrant.js

@@ -36,8 +36,8 @@ const INTENT_DOMAIN = new TextEncoder().encode('calimero.warrant.intent.v1');
  * any Ed25519 work, so minting past it produces a warrant nothing will spend.
  */
 const MAX_CITED_HEADS = 64;
-/** 32 zero bytes — the `appVersion` default. See {@link WarrantInput.appVersion}. */
-const UNPINNED_APP = '00'.repeat(32);
+/** core's `MAX_WARRANT_RELEASE_VERSION_LEN`, in UTF-8 bytes; a node refuses a longer one before any signature work. */
+const MAX_RELEASE_VERSION_LEN = 256;
 /**
  * The commitment a warrant carries in place of the intent itself.
  *
@@ -59,7 +59,9 @@ export async function signWarrant(input) {
     const context = fromHex(input.context, 'context', 32);
     const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
     const executor = fromHex(input.executor, 'executor', 32);
-    const appVersion = fromHex(input.appVersion ?? UNPINNED_APP, 'appVersion', 32);
+    const executorKey = fromHex(input.executorKey, 'executorKey', 32);
+    const releaseBytecodeId = fromHex(input.releaseBytecodeId, 'releaseBytecodeId', 32);
+    const releaseVersion = releaseVersionBytes(input.releaseVersion ?? '');
     const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
     const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
     const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
@@ -78,7 +80,9 @@ export async function signWarrant(input) {
         authorAccount,
         publicKey,
         executor,
-        appVersion,
+        executorKey,
+        releaseBytecodeId,
+        releaseVersion,
         method,
         commitment,
         u64le(accountHeads.length),
@@ -91,7 +95,7 @@ export async function signWarrant(input) {
     const signature = checkedSignature(await signer.sign(preimage));
     // Borsh: a `String` is a u32 length then its UTF-8 bytes; a `Vec<[u8; 32]>` is
     // a u32 count then the elements. u32 HERE; u64 in the preimage above.
-    return hex(concat(context, authorAccount, publicKey, executor, appVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
+    return hex(concat(context, authorAccount, publicKey, executor, executorKey, releaseBytecodeId, u32le(releaseVersion.length), releaseVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
 }
 /**
  * Decode a cited-head list, refusing one longer than a node will accept.
@@ -111,6 +115,17 @@ export function checkedSignature(signature) {
     }
     return signature;
 }
+/** A release version as UTF-8, refused past what a node accepts. Shared with `RelayClient`; internal. */
+export function releaseVersionBytes(version) {
+    const bytes = new TextEncoder().encode(version);
+    checkReleaseVersionLength(bytes.length);
+    return bytes;
+}
+function checkReleaseVersionLength(len) {
+    if (len > MAX_RELEASE_VERSION_LEN) {
+        throw new Error(`releaseVersion is ${len} bytes, over the ${MAX_RELEASE_VERSION_LEN} a node accepts`);
+    }
+}
 export function citedHeads(heads, label) {
     const list = heads ?? [];
     if (list.length > MAX_CITED_HEADS) {
@@ -122,11 +137,11 @@ export function citedHeads(heads, label) {
  * Decode a hex warrant back into its fields.
  *
  * Exists because v2's offsets are no longer constants: `method` is a string and
- * the head lists are vectors, so everything after `appVersion` moves with the
- * method's length. Anything reading a warrant by fixed offset — a test, a client
- * inspecting one it was handed — silently reads the wrong field instead of
- * failing, which is how the three call sites that did so passed while comparing
- * the method's length prefix to a nonce.
+ * the head lists are vectors, so everything after `releaseBytecodeId` moves with
+ * the release version's and the method's lengths. Anything reading a warrant by
+ * fixed offset - a test, a client inspecting one it was handed - silently reads
+ * the wrong field instead of failing, which is how the three call sites that did
+ * so passed while comparing the method's length prefix to a nonce.
  *
  * One copy of the layout, beside the encoder that produces it, so the two cannot
  * drift. Internal: not exported from the package root, because a client that
@@ -146,7 +161,12 @@ export function parseWarrant(warrant) {
     const authorAccount = take(32);
     const deviceKey = take(32);
     const executor = take(32);
-    const appVersion = take(32);
+    const executorKey = take(32);
+    const releaseBytecodeId = take(32);
+    const releaseVersionLen = u32At(o);
+    o += 4;
+    checkReleaseVersionLength(releaseVersionLen);
+    const releaseVersion = take(releaseVersionLen);
     const methodLen = u32At(o);
     o += 4;
     const method = take(methodLen);
@@ -168,7 +188,9 @@ export function parseWarrant(warrant) {
         authorAccount,
         deviceKey,
         executor,
-        appVersion,
+        executorKey,
+        releaseBytecodeId,
+        releaseVersion,
         method,
         intentHash: intentHashField,
         accountHeads,