@distrohelena/canton-typescript-sdk 0.1.51 → 0.1.53

package/dist/cjs/daml-interface/emission/project-emitter.js

@@ -30,6 +30,7 @@ class ProjectEmitter {
     /** Emits the complete in-memory DAML interface project from analyzed templates. */
     emitProject(analysis, moduleImportStyle = daml_module_import_style_js_1.DamlModuleImportStyles.esm) {
         this.namedTypeEmitter.prepareProjectOrThrow(analysis.templates, analysis.typeDefinitions, analysis.packageMetadata);
+        this.templateBindingEmitter.providePackageMetadata(analysis.packageMetadata);
         const templateBindingFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateBindingFile(template));
         const namedTypeFiles = this.namedTypeEmitter.emitPreparedNamedTypeFiles(analysis.typeDefinitions, templateBindingFiles, moduleImportStyle);
         const templateFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateFile(template, namedTypeFiles, moduleImportStyle));

package/dist/cjs/daml-interface/emission/registry-emitter.js

@@ -22,7 +22,7 @@ class RegistryEmitter {
                 "export class GeneratedRegistry {",
                 "    public static fromCreatedEvent(event: DamlCreatedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeCreated(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...createdCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the created event\");",
@@ -31,7 +31,7 @@ class RegistryEmitter {
                 "",
                 "    public static fromExercisedEvent(event: DamlExercisedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...exercisedCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the exercised event\");",
@@ -43,7 +43,21 @@ class RegistryEmitter {
         });
     }
     emitCases(project, methodName) {
-        return project.templateFiles.map((file) => `            case "${file.binding.templateIdLiteral}":\n                return ${file.binding.className}.${methodName}(event);`);
+        // Dispatch is by module:entity — package ids are version-specific under smart contract upgrades,
+        // so any version of a template routes to its binding; the binding's own identity guard then
+        // verifies the package name when the event carries one.
+        const seen = new Map();
+        return project.templateFiles.map((file) => {
+            const parts = file.binding.templateIdLiteral.split(":");
+            const dispatchKey = `${parts[1]}:${parts[2]}`;
+            const existing = seen.get(dispatchKey);
+            if (existing !== undefined && existing !== file.binding.templateIdLiteral) {
+                throw new Error(`Generated registry cannot dispatch '${dispatchKey}': templates '${existing}' and `
+                    + `'${file.binding.templateIdLiteral}' collide on module:entity across packages.`);
+            }
+            seen.set(dispatchKey, file.binding.templateIdLiteral);
+            return `            case "${dispatchKey}":\n                return ${file.binding.className}.${methodName}(event);`;
+        });
     }
 }
 exports.RegistryEmitter = RegistryEmitter;

package/dist/cjs/daml-interface/emission/template-binding-emitter.js

@@ -10,10 +10,15 @@ const relative_module_specifier_js_1 = require("./relative-module-specifier.js")
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 class TemplateBindingEmitter {
     nameResolver;
+    packageMetadata;
     constructor(nameResolver = new type_script_name_resolver_js_1.TypeScriptNameResolver()) {
         this.nameResolver = nameResolver;
         void this.nameResolver;
     }
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata) {
+        this.packageMetadata = metadata;
+    }
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates) {
         this.nameResolver.prepareTemplatesOrThrow(templates);
@@ -49,7 +54,8 @@ class TemplateBindingEmitter {
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
             className,
-            templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
+            templateIdLiteral: this.templateIdLiteral(template),
+            packageName: this.packageMetadata?.get(template.templateId.packageId)?.packageName,
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
             createdEventTypeName: this.nameResolver.getCreatedEventTypeName(template),
@@ -133,6 +139,7 @@ class TemplateBindingEmitter {
         return [
             `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
+            ...(binding.packageName === undefined ? [] : [`    public static readonly packageName = ${JSON.stringify(binding.packageName)};`]),
             `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
@@ -144,7 +151,7 @@ class TemplateBindingEmitter {
             "",
             `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        const fields = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${binding.createFieldsTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(normalized.payload, ${binding.className}.descriptor, GeneratedDamlTypeDescriptorRegistry, "create arguments"));`,
             `        return new ${binding.className}(`,
             "            normalized.contractId,",
@@ -154,7 +161,7 @@ class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
@@ -162,11 +169,7 @@ class TemplateBindingEmitter {
             "        }",
             "    }",
             "",
-            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
-            `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
@@ -193,12 +196,12 @@ class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
             `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId, event.metadata.packageName);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
             `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
@@ -207,14 +210,28 @@ class TemplateBindingEmitter {
             `        return new ${choice.exercisedEventTypeName}(event.contractId, argument, result, event.consuming, event.metadata);`,
             "    }",
             "",
-            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
-            `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames) {
+        const lines = [
+            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }, packageName?: string): void {",
+            `        if (identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            "        }",
+        ];
+        if (binding.packageName !== undefined) {
+            lines.push(`        if (packageName !== undefined && packageName !== ${JSON.stringify(binding.packageName)}) {`, `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected package '${binding.packageName}' but received '\${packageName}' for template '${binding.templateIdLiteral}'\`);`, "        }");
+        }
+        lines.push("    }");
+        return lines;
+    }
     emitTemplateDescriptor(binding) {
         return `{ kind: "record", fields: [${binding.createFields.map((field) => `{ damlLabel: ${JSON.stringify(field.name)}, propertyName: ${JSON.stringify(field.propertyName)}, type: ${this.emitDescriptor(field.type)} }`).join(", ")}] }`;
     }
@@ -515,8 +532,16 @@ class TemplateBindingEmitter {
         }
         return (hash >>> 0).toString(36).padStart(6, "0").slice(-6);
     }
-    packageId(binding) {
-        return binding.templateIdLiteral.split(":")[0];
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    templateIdLiteral(template) {
+        const packageName = this.packageMetadata?.get(template.templateId.packageId)?.packageName;
+        return packageName === undefined
+            ? this.nameResolver.getTemplateIdLiteral(template)
+            : `${packageName}:${template.templateId.moduleName}:${template.templateId.templateName}`;
     }
     moduleName(binding) {
         return binding.templateIdLiteral.split(":")[1];

package/dist/cjs/daml-interface/emission-model/generated-template-binding.js

@@ -21,6 +21,8 @@ class GeneratedTemplateBinding {
     namespaceAlias;
     className;
     templateIdLiteral;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    packageName;
     path;
     createFieldsTypeName;
     createdEventTypeName;
@@ -31,6 +33,7 @@ class GeneratedTemplateBinding {
         this.namespaceAlias = init.namespaceAlias ?? init.className;
         this.className = init.className;
         this.templateIdLiteral = init.templateIdLiteral;
+        this.packageName = init.packageName;
         this.path = init.path;
         this.createFieldsTypeName = init.createFieldsTypeName;
         this.createdEventTypeName = init.createdEventTypeName;

package/dist/cjs/daml-interface/runtime/daml-event-source-normalizer.js

@@ -147,6 +147,7 @@ function identityFrom(value, path) {
 function freezeCreatedMetadata(event, templateId) {
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "created event source"),
         offset: optionalString(event, ["offset", "createdEventOffset", "created_event_offset"], "offset", "created event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "created event source"),
         witnessParties: optionalStringArray(event, ["witnessParties", "witness_parties", "witnesses"], "witness parties", "created event source"),
@@ -160,6 +161,7 @@ function freezeExercisedMetadata(event, source, templateId) {
     const transaction = asObject(readProperty(event, ["transaction"]).value) ?? asObject(root?.transaction);
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "exercised event source"),
         offset: optionalString(event, ["offset"], "offset", "exercised event source")
             ?? optionalString(transaction ?? {}, ["offset"], "offset", "exercised event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "exercised event source"),
@@ -527,6 +529,17 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
 function removeUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
 }
+/** Protobuf-generated events default packageName to ""; treat the default as absent, not invalid. */
+function optionalPackageName(event, context) {
+    const { value } = readProperty(event, ["packageName", "package_name"]);
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw sourceError(context, "package name must be a string");
+    }
+    return value;
+}
 function sourceError(path, detail) {
     return new daml_materialization_error_js_1.DamlMaterializationError(path, detail);
 }

package/dist/daml-interface/emission/project-emitter.js

@@ -27,6 +27,7 @@ export class ProjectEmitter {
     /** Emits the complete in-memory DAML interface project from analyzed templates. */
     emitProject(analysis, moduleImportStyle = DamlModuleImportStyles.esm) {
         this.namedTypeEmitter.prepareProjectOrThrow(analysis.templates, analysis.typeDefinitions, analysis.packageMetadata);
+        this.templateBindingEmitter.providePackageMetadata(analysis.packageMetadata);
         const templateBindingFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateBindingFile(template));
         const namedTypeFiles = this.namedTypeEmitter.emitPreparedNamedTypeFiles(analysis.typeDefinitions, templateBindingFiles, moduleImportStyle);
         const templateFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateFile(template, namedTypeFiles, moduleImportStyle));

package/dist/daml-interface/emission/registry-emitter.js

@@ -19,7 +19,7 @@ export class RegistryEmitter {
                 "export class GeneratedRegistry {",
                 "    public static fromCreatedEvent(event: DamlCreatedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeCreated(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...createdCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the created event\");",
@@ -28,7 +28,7 @@ export class RegistryEmitter {
                 "",
                 "    public static fromExercisedEvent(event: DamlExercisedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...exercisedCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the exercised event\");",
@@ -40,6 +40,20 @@ export class RegistryEmitter {
         });
     }
     emitCases(project, methodName) {
-        return project.templateFiles.map((file) => `            case "${file.binding.templateIdLiteral}":\n                return ${file.binding.className}.${methodName}(event);`);
+        // Dispatch is by module:entity — package ids are version-specific under smart contract upgrades,
+        // so any version of a template routes to its binding; the binding's own identity guard then
+        // verifies the package name when the event carries one.
+        const seen = new Map();
+        return project.templateFiles.map((file) => {
+            const parts = file.binding.templateIdLiteral.split(":");
+            const dispatchKey = `${parts[1]}:${parts[2]}`;
+            const existing = seen.get(dispatchKey);
+            if (existing !== undefined && existing !== file.binding.templateIdLiteral) {
+                throw new Error(`Generated registry cannot dispatch '${dispatchKey}': templates '${existing}' and `
+                    + `'${file.binding.templateIdLiteral}' collide on module:entity across packages.`);
+            }
+            seen.set(dispatchKey, file.binding.templateIdLiteral);
+            return `            case "${dispatchKey}":\n                return ${file.binding.className}.${methodName}(event);`;
+        });
     }
 }

package/dist/daml-interface/emission/template-binding-emitter.d.ts

@@ -6,7 +6,12 @@ import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export declare class TemplateBindingEmitter {
     private readonly nameResolver;
+    private packageMetadata?;
     constructor(nameResolver?: TypeScriptNameResolver);
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata: ReadonlyMap<string, {
+        readonly packageName: string;
+    }>): void;
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates: readonly AnalyzedTemplate[]): void;
     /** Emits a generated TypeScript file for one analyzed DAML template. */
@@ -18,6 +23,12 @@ export declare class TemplateBindingEmitter {
     private emitImports;
     private emitTemplateClass;
     private emitChoiceEventClass;
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    private emitAssertTemplateIdentity;
     private emitTemplateDescriptor;
     private emitDescriptor;
     private getTypeName;
@@ -33,7 +44,12 @@ export declare class TemplateBindingEmitter {
     private getNamedReferenceKey;
     private toTypeName;
     private shortHash;
-    private packageId;
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    private templateIdLiteral;
     private moduleName;
     private entityName;
     private relativeFilePath;

package/dist/daml-interface/emission/template-binding-emitter.js

@@ -7,10 +7,15 @@ import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export class TemplateBindingEmitter {
     nameResolver;
+    packageMetadata;
     constructor(nameResolver = new TypeScriptNameResolver()) {
         this.nameResolver = nameResolver;
         void this.nameResolver;
     }
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata) {
+        this.packageMetadata = metadata;
+    }
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates) {
         this.nameResolver.prepareTemplatesOrThrow(templates);
@@ -46,7 +51,8 @@ export class TemplateBindingEmitter {
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
             className,
-            templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
+            templateIdLiteral: this.templateIdLiteral(template),
+            packageName: this.packageMetadata?.get(template.templateId.packageId)?.packageName,
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
             createdEventTypeName: this.nameResolver.getCreatedEventTypeName(template),
@@ -130,6 +136,7 @@ export class TemplateBindingEmitter {
         return [
             `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
+            ...(binding.packageName === undefined ? [] : [`    public static readonly packageName = ${JSON.stringify(binding.packageName)};`]),
             `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
@@ -141,7 +148,7 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        const fields = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${binding.createFieldsTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(normalized.payload, ${binding.className}.descriptor, GeneratedDamlTypeDescriptorRegistry, "create arguments"));`,
             `        return new ${binding.className}(`,
             "            normalized.contractId,",
@@ -151,7 +158,7 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
@@ -159,11 +166,7 @@ export class TemplateBindingEmitter {
             "        }",
             "    }",
             "",
-            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
-            `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
@@ -190,12 +193,12 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
             `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId, event.metadata.packageName);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
             `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
@@ -204,14 +207,28 @@ export class TemplateBindingEmitter {
             `        return new ${choice.exercisedEventTypeName}(event.contractId, argument, result, event.consuming, event.metadata);`,
             "    }",
             "",
-            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
-            `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames) {
+        const lines = [
+            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }, packageName?: string): void {",
+            `        if (identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            "        }",
+        ];
+        if (binding.packageName !== undefined) {
+            lines.push(`        if (packageName !== undefined && packageName !== ${JSON.stringify(binding.packageName)}) {`, `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected package '${binding.packageName}' but received '\${packageName}' for template '${binding.templateIdLiteral}'\`);`, "        }");
+        }
+        lines.push("    }");
+        return lines;
+    }
     emitTemplateDescriptor(binding) {
         return `{ kind: "record", fields: [${binding.createFields.map((field) => `{ damlLabel: ${JSON.stringify(field.name)}, propertyName: ${JSON.stringify(field.propertyName)}, type: ${this.emitDescriptor(field.type)} }`).join(", ")}] }`;
     }
@@ -512,8 +529,16 @@ export class TemplateBindingEmitter {
         }
         return (hash >>> 0).toString(36).padStart(6, "0").slice(-6);
     }
-    packageId(binding) {
-        return binding.templateIdLiteral.split(":")[0];
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    templateIdLiteral(template) {
+        const packageName = this.packageMetadata?.get(template.templateId.packageId)?.packageName;
+        return packageName === undefined
+            ? this.nameResolver.getTemplateIdLiteral(template)
+            : `${packageName}:${template.templateId.moduleName}:${template.templateId.templateName}`;
     }
     moduleName(binding) {
         return binding.templateIdLiteral.split(":")[1];

package/dist/daml-interface/emission-model/generated-template-binding.d.ts

@@ -19,6 +19,8 @@ export declare class GeneratedTemplateBinding {
     readonly namespaceAlias: string;
     readonly className: string;
     readonly templateIdLiteral: string;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    readonly packageName?: string;
     readonly path: string;
     readonly createFieldsTypeName: string;
     readonly createdEventTypeName: string;
@@ -29,6 +31,7 @@ export declare class GeneratedTemplateBinding {
         namespaceAlias?: string;
         className: string;
         templateIdLiteral: string;
+        packageName?: string;
         path: string;
         createFieldsTypeName: string;
         createdEventTypeName: string;

package/dist/daml-interface/emission-model/generated-template-binding.js

@@ -17,6 +17,8 @@ export class GeneratedTemplateBinding {
     namespaceAlias;
     className;
     templateIdLiteral;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    packageName;
     path;
     createFieldsTypeName;
     createdEventTypeName;
@@ -27,6 +29,7 @@ export class GeneratedTemplateBinding {
         this.namespaceAlias = init.namespaceAlias ?? init.className;
         this.className = init.className;
         this.templateIdLiteral = init.templateIdLiteral;
+        this.packageName = init.packageName;
         this.path = init.path;
         this.createFieldsTypeName = init.createFieldsTypeName;
         this.createdEventTypeName = init.createdEventTypeName;

package/dist/daml-interface/runtime/daml-event-source-normalizer.d.ts

@@ -8,6 +8,8 @@ export type DamlCreatedEventSource = CreatedEvent | GetContractResponse | Active
 export type DamlExercisedEventSource = ExercisedEvent | ExerciseResult | Event | DamlJsonEventRecord;
 export type DamlCreatedEventMetadata = {
     readonly templateId: DamlTypeIdentity;
+    /** The template's package NAME — the stable identity across smart-contract-upgrade versions. */
+    readonly packageName?: string;
     readonly offset?: string;
     readonly nodeId?: number;
     readonly witnessParties?: readonly string[];
@@ -18,6 +20,8 @@ export type DamlCreatedEventMetadata = {
 };
 export type DamlExercisedEventMetadata = {
     readonly templateId: DamlTypeIdentity;
+    /** The template's package NAME — the stable identity across smart-contract-upgrade versions. */
+    readonly packageName?: string;
     readonly offset?: string;
     readonly nodeId?: number;
     readonly actingParties?: readonly string[];

package/dist/daml-interface/runtime/daml-event-source-normalizer.js

@@ -143,6 +143,7 @@ function identityFrom(value, path) {
 function freezeCreatedMetadata(event, templateId) {
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "created event source"),
         offset: optionalString(event, ["offset", "createdEventOffset", "created_event_offset"], "offset", "created event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "created event source"),
         witnessParties: optionalStringArray(event, ["witnessParties", "witness_parties", "witnesses"], "witness parties", "created event source"),
@@ -156,6 +157,7 @@ function freezeExercisedMetadata(event, source, templateId) {
     const transaction = asObject(readProperty(event, ["transaction"]).value) ?? asObject(root?.transaction);
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "exercised event source"),
         offset: optionalString(event, ["offset"], "offset", "exercised event source")
             ?? optionalString(transaction ?? {}, ["offset"], "offset", "exercised event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "exercised event source"),
@@ -523,6 +525,17 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
 function removeUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
 }
+/** Protobuf-generated events default packageName to ""; treat the default as absent, not invalid. */
+function optionalPackageName(event, context) {
+    const { value } = readProperty(event, ["packageName", "package_name"]);
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw sourceError(context, "package name must be a string");
+    }
+    return value;
+}
 function sourceError(path, detail) {
     return new DamlMaterializationError(path, detail);
 }

package/node/start-local.sh

@@ -98,6 +98,19 @@ es256_runtime_dir() {
   printf '%s\n' "${START_LOCAL_ES256_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-es256}"
 }
 
+resolve_no_auth_enabled() {
+  local value="${LOCALNET_NO_AUTH:-0}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_NO_AUTH must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
+no_auth_runtime_dir() {
+  printf '%s\n' "${START_LOCAL_NO_AUTH_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-no-auth}"
+}
+
 resolve_tls_enabled() {
   local value="${LOCALNET_TLS:-0}"
   if [[ "$value" != "0" && "$value" != "1" ]]; then
@@ -447,6 +460,66 @@ EOF
   export LOCALNET_ES256_TOKEN_PATH="$token_path"
 }
 
+prepare_no_auth_runtime_files() {
+  if [[ "$(resolve_no_auth_enabled)" != "1" ]]; then
+    return 0
+  fi
+
+  local runtime_dir
+  runtime_dir="$(no_auth_runtime_dir)"
+  local compose_file="$runtime_dir/compose-no-auth.yaml"
+  local canton_config_file="$runtime_dir/canton-no-auth.conf"
+  mkdir -p "$runtime_dir"
+
+  cat > "$canton_config_file" <<EOF
+include file("/app/base-app.conf")
+
+$(if [[ "$(resolve_tls_enabled)" == "1" ]]; then printf 'include file("/app/localnet-tls.conf")\n'; fi)
+
+EOF
+  local participant profile
+  for participant in app-provider app-user sv; do
+    case "$participant" in
+      app-provider) profile="$APP_PROVIDER_PROFILE" ;;
+      app-user) profile="$APP_USER_PROFILE" ;;
+      sv) profile="$SV_PROFILE" ;;
+    esac
+    if [[ "$profile" != "off" ]]; then
+      cat >> "$canton_config_file" <<EOF
+canton.participants.${participant}.ledger-api.auth-services = []
+EOF
+    fi
+  done
+
+  cat > "$compose_file" <<EOF
+services:
+  canton:
+    volumes:
+      - "${LOCALNET_DIR}/conf/canton/app.conf:/app/base-app.conf:ro"
+      - "$canton_config_file:/app/app.conf:ro"
+  pqs-app-provider:
+    environment:
+      SCRIBE_SOURCE_LEDGER_AUTH: NoAuth
+  pqs-app-user:
+    environment:
+      SCRIBE_SOURCE_LEDGER_AUTH: NoAuth
+  pqs-sv:
+    environment:
+      SCRIBE_SOURCE_LEDGER_AUTH: NoAuth
+EOF
+  export LOCALNET_NO_AUTH_COMPOSE_FILE="$compose_file"
+}
+
+append_no_auth_args() {
+  local -n compose_args_ref="$1"
+  if [[ "$(resolve_no_auth_enabled)" == "1" ]]; then
+    local compose_file="$(no_auth_runtime_dir)/compose-no-auth.yaml"
+    if [[ -f "$compose_file" ]]; then
+      compose_args_ref+=( -f "$compose_file" )
+    fi
+  fi
+}
+
 append_es256_args() {
   local -n compose_args_ref="$1"
   if [[ "$(resolve_es256_enabled)" == "1" ]]; then
@@ -485,6 +558,23 @@ docker_compose() {
   "${DOCKER_COMPOSE_CMD[@]}" "$@"
 }
 
+resolve_extra_participant_auth() {
+  local index="$1"
+  local var="EXTRA_PARTICIPANT_${index}_AUTH"
+  local value="${!var:-}"
+  if [[ -z "$value" ]]; then
+    if [[ "$(resolve_no_auth_enabled)" == "1" ]]; then value="none"; else value="jwt"; fi
+  fi
+  case "$value" in
+    jwt|none) ;;
+    *)
+      echo "EXTRA_PARTICIPANT_${index}_AUTH must be 'jwt' or 'none'." >&2
+      return 1
+      ;;
+  esac
+  printf '%s\n' "$value"
+}
+
 resolve_extra_participants() {
   local value="${EXTRA_PARTICIPANTS:-0}"
   if [[ ! "$value" =~ ^[0-9]+$ ]]; then
@@ -684,6 +774,16 @@ EOF
     done
   fi
 
+  local no_auth_index
+  for ((no_auth_index = 1; no_auth_index <= count; no_auth_index++)); do
+    if [[ "$(resolve_extra_participant_auth "$no_auth_index")" == "none" ]]; then
+      cat >> "$canton_config_file" <<EOF
+canton.participants.extra-${no_auth_index}.ledger-api.auth-services = []
+
+EOF
+    fi
+  done
+
   if [[ "$(resolve_tls_enabled)" == "1" ]]; then
     local index
     for ((index = 1; index <= count; index++)); do
@@ -842,7 +942,7 @@ EOF
     environment:
       SCRIBE_SOURCE_LEDGER_HOST: canton
       SCRIBE_SOURCE_LEDGER_PORT: \${EXTRA_PARTICIPANT_${index}_LEDGER_API_PORT}
-      SCRIBE_SOURCE_LEDGER_AUTH: OAuth
+      SCRIBE_SOURCE_LEDGER_AUTH: $(if [[ "$(resolve_extra_participant_auth "$index")" == "none" ]]; then printf 'NoAuth'; else printf 'OAuth'; fi)
       SCRIBE_TARGET_POSTGRES_HOST: postgres-pqs-extra-${index}
       SCRIBE_TARGET_POSTGRES_PORT: 5432
       SCRIBE_TARGET_POSTGRES_DATABASE: \${EXTRA_PQS_${index}_POSTGRES_DB}
@@ -1218,8 +1318,9 @@ start_ledger_stack() {
   load_localnet_common_env "$localnet_dir/env/common.env"
   prepare_tls_runtime_files
   prepare_es256_runtime_files
+  prepare_no_auth_runtime_files
   local extra_participants
-  extra_participants="$(resolve_extra_participants)"
+  extra_participants="$(resolve_extra_participants)" 
   if (( extra_participants > 0 )) && [[ "$auth_mode" != "shared-secret" ]]; then
     echo "EXTRA_PARTICIPANTS with extra PQS currently supports AUTH_MODE=shared-secret only." >&2
     return 1
@@ -1252,6 +1353,7 @@ start_ledger_stack() {
   append_extra_participant_args "$extra_participants" "$auth_mode" compose_args
   append_tls_args compose_args
   append_es256_args compose_args
+  append_no_auth_args compose_args
   docker_compose "${compose_args[@]}" down -v --remove-orphans
   mapfile -t startup_services < <(prerequisite_services "$auth_mode")
   mapfile -t followup_services < <(dependent_services)
@@ -1289,17 +1391,22 @@ load_repo_root_env
 QUICKSTART_DIR="$(resolve_quickstart_dir)"
 cd "$QUICKSTART_DIR"
 
+if [[ "$(resolve_no_auth_enabled)" == "1" && "$(resolve_es256_enabled)" == "1" ]]; then
+  echo "LOCALNET_NO_AUTH=1 conflicts with LOCALNET_ES256_JWT=1: pick one auth mode." >&2
+  exit 1
+fi
+
 if [[ ! -f .env.local ]]; then
   echo ".env.local not found. Bootstrapping Quickstart with 'make setup'."
   make setup
 fi
 
-if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" ]] && make_target_exists start-local-ledger; then
+if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" && "$(resolve_no_auth_enabled)" != "1" ]] && make_target_exists start-local-ledger; then
   make start-local-ledger
 else
   auth_mode="$(read_env_value AUTH_MODE || true)"
   auth_mode="${auth_mode:-shared-secret}"
-  if [[ "$(resolve_es256_enabled)" == "1" || "$(resolve_tls_enabled)" == "1" ]]; then
+  if [[ "$(resolve_es256_enabled)" == "1" || "$(resolve_tls_enabled)" == "1" || "$(resolve_no_auth_enabled)" == "1" ]]; then
     echo "Generated localnet transport overlay enabled. Starting ledger-only compose stack directly."
   else
     echo "start-local-ledger target not found. Starting ledger-only compose stack directly."

package/node/stop-local.sh

@@ -92,6 +92,19 @@ es256_runtime_dir() {
   printf '%s\n' "${START_LOCAL_ES256_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-es256}"
 }
 
+resolve_no_auth_enabled() {
+  local value="${LOCALNET_NO_AUTH:-0}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_NO_AUTH must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
+no_auth_runtime_dir() {
+  printf '%s\n' "${START_LOCAL_NO_AUTH_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-no-auth}"
+}
+
 resolve_tls_enabled() {
   local value="${LOCALNET_TLS:-0}"
   if [[ "$value" != "0" && "$value" != "1" ]]; then
@@ -125,6 +138,16 @@ append_tls_args() {
   fi
 }
 
+append_no_auth_args() {
+  local -n compose_args_ref="$1"
+  if [[ "$(resolve_no_auth_enabled)" == "1" ]]; then
+    local compose_file="$(no_auth_runtime_dir)/compose-no-auth.yaml"
+    if [[ -f "$compose_file" ]]; then
+      compose_args_ref+=( -f "$compose_file" )
+    fi
+  fi
+}
+
 resolve_docker_compose_cmd() {
   if (( ${#DOCKER_COMPOSE_CMD[@]} > 0 )); then
     return 0
@@ -203,6 +226,7 @@ stop_ledger_stack() {
   append_existing_extra_participant_args compose_args
   append_tls_args compose_args
   append_es256_args compose_args
+  append_no_auth_args compose_args
   docker_compose "${compose_args[@]}" down -v --remove-orphans
 }
 
@@ -215,7 +239,7 @@ if [[ ! -f .env.local ]]; then
   exit 0
 fi
 
-if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" ]] && make_target_exists stop-local-ledger; then
+if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" && "$(resolve_no_auth_enabled)" != "1" ]] && make_target_exists stop-local-ledger; then
   make stop-local-ledger
 else
   auth_mode="$(read_env_value AUTH_MODE || true)"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.51",
+    "version": "0.1.53",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",
@@ -87,6 +87,7 @@
     },
     "scripts": {
         "build": "node ./scripts/clean-dist.mjs && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs",
+        "prepublishOnly": "npm run build && npm run test:unit",
         "generate:daml-interface": "node ./dist/daml-interface/cli/daml-interface-cli-main.js",
         "generate:grpc": "node ./scripts/generate-grpc-bindings.mjs",
         "examples:check": "npm run build && tsc -p tsconfig.examples.json --noEmit",