Back to Details

canton-network-repos

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Canton Network Open-Source Repositories

Canton Network 开源仓库

This skill provides comprehensive knowledge about the Canton Network open-source ecosystem, repository relationships, and build processes.
本技能提供关于Canton Network开源生态系统、仓库依赖关系及构建流程的全面知识。

Activation

适用场景

Use this skill when:
  • Working with Canton Network, DAML, or Splice repositories
  • Investigating version compatibility issues
  • Understanding enterprise vs community differences
  • Debugging LF version or package ID mismatches
  • Building Canton participants or Splice applications
在以下场景中使用本技能：
  • 处理Canton Network、DAML或Splice仓库相关工作
  • 排查版本兼容性问题
  • 理解企业版与社区版的差异
  • 调试LF版本或包ID不匹配问题
  • 构建Canton节点或Splice应用

Repository Hierarchy

仓库层级结构

┌─────────────────────────────────────────────────────────────────┐
│                    Splice Version (e.g., 0.5.4)                 │
│         github.com/digital-asset/decentralized-canton-sync     │
│   Applications: Validator, SV, Wallet, Scan, Amulet (CC)       │
└─────────────────────────┬───────────────────────────────────────┘
                          │ depends on
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Canton Version (e.g., 3.4.9)                  │
│               github.com/digital-asset/canton                   │
│     Runtime: Participant, Sequencer, Mediator, Admin API       │
└─────────────────────────┬───────────────────────────────────────┘
                          │ depends on
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    DAML SDK (e.g., 3.4.9)                       │
│                github.com/digital-asset/daml                    │
│    Compiler: damlc, LF Engine, Ledger API, stdlib, protobuf    │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│                    Splice Version (e.g., 0.5.4)                 │
│         github.com/digital-asset/decentralized-canton-sync     │
│   Applications: Validator, SV, Wallet, Scan, Amulet (CC)       │
└─────────────────────────┬───────────────────────────────────────┘
                          │ depends on
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Canton Version (e.g., 3.4.9)                  │
│               github.com/digital-asset/canton                   │
│     Runtime: Participant, Sequencer, Mediator, Admin API       │
└─────────────────────────┬───────────────────────────────────────┘
                          │ depends on
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    DAML SDK (e.g., 3.4.9)                       │
│                github.com/digital-asset/daml                    │
│    Compiler: damlc, LF Engine, Ledger API, stdlib, protobuf    │
└─────────────────────────────────────────────────────────────────┘

Repository Details

仓库详情

1. DAML SDK (
github.com/digital-asset/daml
)

1. DAML SDK (
github.com/digital-asset/daml
)

Purpose: Smart contract language, compiler, and runtime libraries.
Key Directories:
daml/
├── sdk/
│   ├── compiler/damlc/          # Haskell compiler source
│   │   └── lib/DA/Cli/Options.hs  # --target version validation
│   ├── daml-lf/
│   │   ├── language/            # LF version definitions (Scala)
│   │   ├── engine/              # LF execution engine
│   │   └── archive/             # DALF protobuf format
│   └── canton/                  # Canton runtime (submodule)
├── ledger-api/                  # gRPC API definitions
└── VERSION                      # SDK version string
LF Version Definitions (
LanguageVersion.scala
at v3.4.9):
scala
// V2 versions defined
val List(v2_1, v2_2, v2_dev) = AllV2  // Line 51 - v2_2 IS defined

// Version ranges
case Major.V2 => VersionRange(v2_1, v2_2)  // Line 171 - StableVersions includes v2_2
def AllVersions = VersionRange(v2_1, v2_dev)

// Features at v2_2:
val flatArchive = v2_2
val kindInterning = flatArchive
val exprInterning = flatArchive
val explicitPkgImports = v2_2
val unsafeFromInterfaceRemoved = v2_2
Note: v2_2 IS in SDK v3.4.9 source. Older snapshots may not include it.
damlc Target Validation (
Options.hs
):
haskell
lfVersionOpt :: Parser LF.Version
-- Validates against LF.supportedOutputVersions
-- Error: "Unknown Daml-LF version: X" if not in list
用途：智能合约语言、编译器及运行时库。
核心目录：
daml/
├── sdk/
│   ├── compiler/damlc/          # Haskell compiler source
│   │   └── lib/DA/Cli/Options.hs  # --target version validation
│   ├── daml-lf/
│   │   ├── language/            # LF version definitions (Scala)
│   │   ├── engine/              # LF execution engine
│   │   └── archive/             # DALF protobuf format
│   └── canton/                  # Canton runtime (submodule)
├── ledger-api/                  # gRPC API definitions
└── VERSION                      # SDK version string
LF版本定义（v3.4.9版本下的
LanguageVersion.scala
）：
scala
// V2 versions defined
val List(v2_1, v2_2, v2_dev) = AllV2  // Line 51 - v2_2 IS defined

// Version ranges
case Major.V2 => VersionRange(v2_1, v2_2)  // Line 171 - StableVersions includes v2_2
def AllVersions = VersionRange(v2_1, v2_dev)

// Features at v2_2:
val flatArchive = v2_2
val kindInterning = flatArchive
val exprInterning = flatArchive
val explicitPkgImports = v2_2
val unsafeFromInterfaceRemoved = v2_2
注意：v2_2在SDK v3.4.9源码中已定义。旧版快照可能未包含该版本。
damlc目标版本验证（
Options.hs
）：
haskell
lfVersionOpt :: Parser LF.Version
-- Validates against LF.supportedOutputVersions
-- Error: "Unknown Daml-LF version: X" if not in list

2. Canton (
github.com/digital-asset/canton
)

2. Canton (
github.com/digital-asset/canton
)

Purpose: Distributed ledger runtime implementing the Canton Protocol.
Key Directories:
canton/
├── community/                   # Open-source Canton
│   ├── app/                     # CantonCommunityApp entry point
│   ├── participant/             # Participant node implementation
│   ├── domain/                  # Embedded domain (sequencer/mediator)
│   └── common/src/main/daml/    # Built-in DAML packages
│       └── AdminWorkflows/      # Ping, party replication DARs
├── daml/                        # DAML SDK submodule
├── daml_dependencies.json       # LF library versions
├── VERSION                      # Canton version
└── version.sbt                  # SBT version config
Built-in DARs (embedded in JAR):
  • canton-builtin-admin-workflow-ping.dar
  • canton-builtin-admin-workflow-party-replication-alpha.dar
  • CantonExamples.dar
Enterprise vs Community:
FeatureEnterpriseCommunity
Main classCantonEnterpriseAppCantonCommunityApp
Transaction processingParallelSequential
PruningAvailableLimited
DatabasePostgreSQL, OraclePostgreSQL only
HA DomainSupportedEmbedded only
用途：实现Canton协议的分布式账本运行时。
核心目录：
canton/
├── community/                   # Open-source Canton
│   ├── app/                     # CantonCommunityApp entry point
│   ├── participant/             # Participant node implementation
│   ├── domain/                  # Embedded domain (sequencer/mediator)
│   └── common/src/main/daml/    # Built-in DAML packages
│       └── AdminWorkflows/      # Ping, party replication DARs
├── daml/                        # DAML SDK submodule
├── daml_dependencies.json       # LF library versions
├── VERSION                      # Canton version
└── version.sbt                  # SBT version config
内置DAR包（嵌入在JAR中）：
  • canton-builtin-admin-workflow-ping.dar
  • canton-builtin-admin-workflow-party-replication-alpha.dar
  • CantonExamples.dar
企业版 vs 社区版：
特性企业版社区版
主类CantonEnterpriseAppCantonCommunityApp
事务处理并行串行
数据清理支持完整功能功能受限
数据库PostgreSQL、Oracle仅支持PostgreSQL
高可用域支持仅支持嵌入式

3. Splice (
github.com/digital-asset/decentralized-canton-sync
)

3. Splice (
github.com/digital-asset/decentralized-canton-sync
)

Purpose: Decentralized synchronizer governance, Amulet (Canton Coin), and network applications.
Key Directories:
decentralized-canton-sync/
├── project/
│   ├── CantonDependencies.scala  # Version config, LF versions
│   └── DamlPlugin.scala          # DAR build logic
├── daml/
│   ├── splice-amulet/            # Canton Coin token contracts
│   ├── splice-wallet/            # Wallet contracts
│   ├── splice-dso-governance/    # DSO governance
│   └── */daml.yaml               # Package configs with --target
├── apps/
│   ├── sv/                       # Super Validator app
│   ├── validator/                # Validator app
│   ├── wallet/                   # Wallet backend
│   └── scan/                     # Payment scan service
├── cluster/images/               # Docker image builds
│   └── canton-community/         # Community participant image
└── daml-compiler-sources.json    # Compiler version reference
Critical Configuration (
CantonDependencies.scala
):
scala
object CantonDependencies {
  val version: String = "3.4.9"
  val daml_language_versions = Seq("2.1")  // ← LF target version
  val daml_libraries_version = version
  val daml_compiler_version = sys.env("DAML_COMPILER_VERSION")
}
Package Target (
daml/splice-amulet/daml.yaml
):
yaml
sdk-version: 3.3.0-snapshot.20250502.13767.0.v2fc6c7e2
build-options:
  - --target=2.1  # Explicit LF 2.1 target
用途：去中心化同步器治理、Amulet（Canton Coin）及网络应用。
核心目录：
decentralized-canton-sync/
├── project/
│   ├── CantonDependencies.scala  # Version config, LF versions
│   └── DamlPlugin.scala          # DAR build logic
├── daml/
│   ├── splice-amulet/            # Canton Coin token contracts
│   ├── splice-wallet/            # Wallet contracts
│   ├── splice-dso-governance/    # DSO governance
│   └── */daml.yaml               # Package configs with --target
├── apps/
│   ├── sv/                       # Super Validator app
│   ├── validator/                # Validator app
│   ├── wallet/                   # Wallet backend
│   └── scan/                     # Payment scan service
├── cluster/images/               # Docker image builds
│   └── canton-community/         # Community participant image
└── daml-compiler-sources.json    # Compiler version reference
关键配置（
CantonDependencies.scala
）：
scala
object CantonDependencies {
  val version: String = "3.4.9"
  val daml_language_versions = Seq("2.1")  // ← LF target version
  val daml_libraries_version = version
  val daml_compiler_version = sys.env("DAML_COMPILER_VERSION")
}
包目标版本（
daml/splice-amulet/daml.yaml
）：
yaml
sdk-version: 3.3.0-snapshot.20250502.13767.0.v2fc6c7e2
build-options:
  - --target=2.1  # Explicit LF 2.1 target

Version Mapping

版本映射表

SpliceCantonDAML SDKProtocolLF (Default)LF (With SDK 3.4.9)
0.5.43.4.93.4.9PV342.1*2.2 (verified)
0.5.33.4.83.4.8PV342.1*2.2
0.4.x3.3.x3.3.xPV332.12.1
*Open-source Splice 0.5.4 ships with SDK snapshot 
3.3.0-snapshot.20250502
which predates LF 2.2.
Root Cause (Verified): The public Splice release uses an SDK snapshot from May 2, 2025, but LF 2.2 was added to the SDK on October 3, 2025. Updating to SDK 3.4.9 enables LF 2.2 builds.
Key insight: LF 2.2 is fully available in open-source SDK v3.4.9. The Splice project simply needs to be updated to use the newer SDK.
SpliceCantonDAML SDK协议LF（默认）LF（使用SDK 3.4.9）
0.5.43.4.93.4.9PV342.1*2.2（已验证）
0.5.33.4.83.4.8PV342.1*2.2
0.4.x3.3.x3.3.xPV332.12.1
*开源Splice 0.5.4使用的SDK快照版本为
3.3.0-snapshot.20250502
，该版本早于LF 2.2的发布时间。
根本原因（已验证）：公开的Splice版本使用的SDK快照发布于2025年5月2日，而LF 2.2是在2025年10月3日才加入SDK的。升级到SDK 3.4.9即可支持LF 2.2构建。
核心结论：LF 2.2在开源SDK v3.4.9中已完全可用。Splice项目只需升级至新版本SDK即可。

LF Version Implications

LF版本影响

Package ID Derivation

包ID生成逻辑

Package IDs are cryptographic hashes derived from:
  1. Package source content
  2. LF version used (
    --target
    )
  3. SDK/stdlib versions
  4. Dependency package IDs
Changing LF version = Different package IDs = Incompatible packages
包ID是基于以下内容生成的加密哈希：
  1. 包源码内容
  2. 使用的LF版本（
    --target
    参数指定）
  3. SDK/标准库版本
  4. 依赖包ID
修改LF版本 = 生成不同的包ID = 包不兼容

Upgrade Validation

升级验证

Canton validates package upgrades:
  • Upgraded packages must use equal or newer LF version
  • LF 2.1 package cannot "upgrade" to LF 2.2 package (different IDs)
  • Mixing LF versions on same ledger causes validation failures
Canton会对包升级进行验证：
  • 升级后的包必须使用等于或更高版本的LF
  • LF 2.1包无法“升级”为LF 2.2包（包ID不同）
  • 同一账本中混合使用不同LF版本会导致验证失败

Building from Open-Source

从开源代码构建

Community Canton Participant

社区版Canton节点

bash
cd canton
sbt "community/app/assembly"
bash
cd canton
sbt "community/app/assembly"

Output: community/app/target/scala-2.13/canton-community.jar

Output: community/app/target/scala-2.13/canton-community.jar

undefined
undefined

Splice Applications

Splice应用

bash
cd decentralized-canton-sync
sbt compile  # Requires DAML_COMPILER_VERSION env var
bash
cd decentralized-canton-sync
sbt compile  # Requires DAML_COMPILER_VERSION env var

Building with LF 2.2 (Verified Working)

使用LF 2.2构建（已验证可行）

LF 2.2 is available in SDK v3.4.9. The following steps have been verified to work:
  1. Edit 
    project/CantonDependencies.scala
    :
    scala
    val daml_language_versions = Seq("2.2")
  2. Update 
    nix/daml-compiler-sources.json
    :
    json
    { "version": "3.4.9" }
  3. Update all 
    daml/*/daml.yaml
    files:
    yaml
    sdk-version: 3.4.9
build-options:
  - --target=2.2
  4. Remove invalid warning flags (not present in SDK 3.4.9):
    bash
    # Remove -Wno-ledger-time-is-alpha from all daml.yaml files
  5. Build packages:
    bash
    cd decentralized-canton-sync
nix-shell -p daml-sdk --run "daml build -p daml/splice-util"
nix-shell -p daml-sdk --run "daml build -p daml/splice-amulet"
Verified: splice-util and splice-amulet build successfully with LF 2.2 and SDK 3.4.9.
LF 2.2在SDK v3.4.9中可用。以下步骤已验证可行：
  1. 编辑
    project/CantonDependencies.scala
    ：
    scala
    val daml_language_versions = Seq("2.2")
  2. 更新
    nix/daml-compiler-sources.json
    ：
    json
    { "version": "3.4.9" }
  3. 更新所有
    daml/*/daml.yaml
    文件：
    yaml
    sdk-version: 3.4.9
build-options:
  - --target=2.2
  4. 移除无效的警告标志（SDK 3.4.9中不存在）：
    bash
    # Remove -Wno-ledger-time-is-alpha from all daml.yaml files
  5. 构建包：
    bash
    cd decentralized-canton-sync
nix-shell -p daml-sdk --run "daml build -p daml/splice-util"
nix-shell -p daml-sdk --run "daml build -p daml/splice-amulet"
已验证：splice-util和splice-amulet可通过LF 2.2和SDK 3.4.9成功构建。

Fully Open-Source LF 2.2 Build (Verified)

完全开源的LF 2.2构建（已验证）

Both Splice and Canton can be built with LF 2.2 from entirely open-source code:
Splice和Canton均可完全基于开源代码使用LF 2.2构建：

Canton Built-in DARs

Canton内置DAR包

Update Canton's daml.yaml files:
bash
cd canton/community
更新Canton的daml.yaml文件：
bash
cd canton/community

Update all daml.yaml files to sdk-version: 3.4.9 and --target=2.2

Update all daml.yaml files to sdk-version: 3.4.9 and --target=2.2

perl -pi -e 's/sdk-version: 3.3.0-snapshot.[^\n]*/sdk-version: 3.4.9/g' **/daml.yaml perl -pi -e 's/--target=2.1/--target=2.2/g' **/daml.yaml

Rebuild Canton:
```bash
sbt "canton-community-app/assembly"
perl -pi -e 's/sdk-version: 3.3.0-snapshot.[^\n]*/sdk-version: 3.4.9/g' **/daml.yaml perl -pi -e 's/--target=2.1/--target=2.2/g' **/daml.yaml

重新构建Canton：
```bash
sbt "canton-community-app/assembly"

Verified Results (2025-12-24)

验证结果（2025-12-24）

Community-built DARs have identical package IDs to enterprise:
  • canton-builtin-admin-workflow-ping-3.4.9-fbeb863dab36da66d99...
This confirms full compatibility with enterprise deployments.
社区版构建的DAR包与企业版的包ID完全一致：
  • canton-builtin-admin-workflow-ping-3.4.9-fbeb863dab36da66d99...
这证实了社区版构建与企业版部署完全兼容。

Key Files Reference

核心文件参考

PurposeRepositoryFile
LF versions (Scala)daml
sdk/daml-lf/language/.../LanguageVersion.scala
damlc validationdaml
sdk/compiler/damlc/lib/DA/Cli/Options.hs
Canton versioncanton
VERSION
Canton DARscanton
community/common/src/main/daml/
Splice LF configsplice
project/CantonDependencies.scala
Package targetssplice
daml/*/daml.yaml
Docker buildssplice
cluster/images/*/Dockerfile
用途仓库文件
LF版本定义（Scala）daml
sdk/daml-lf/language/.../LanguageVersion.scala
damlc验证逻辑daml
sdk/compiler/damlc/lib/DA/Cli/Options.hs
Canton版本canton
VERSION
Canton DAR包canton
community/common/src/main/daml/
Splice LF配置splice
project/CantonDependencies.scala
包目标版本splice
daml/*/daml.yaml
Docker构建splice
cluster/images/*/Dockerfile

Troubleshooting

故障排查

"Unknown Daml-LF version: 2.2"

“Unknown Daml-LF version: 2.2”（未知Daml-LF版本：2.2）

  • Cause: damlc binary doesn't support 2.2 in 
    supportedOutputVersions
  • Check: 
    daml damlc --help
    for supported targets
  • Fix: Use SDK version that includes 2.2, or use 2.1
  • 原因：damlc二进制文件的
    supportedOutputVersions
    中不支持2.2版本
  • 检查：执行
    daml damlc --help
    查看支持的目标版本
  • 解决：使用包含2.2版本的SDK，或切换至2.1版本

Package ID Mismatch

包ID不匹配

  • Cause: Different LF versions between builds
  • Check: 
    unzip -p package.dar META-INF/MANIFEST.MF | grep Sdk-Version
  • Fix: Ensure consistent 
    --target
    across all builds
  • 原因：构建时使用了不同的LF版本
  • 检查：执行
    unzip -p package.dar META-INF/MANIFEST.MF | grep Sdk-Version
    查看SDK版本
  • 解决：确保所有构建使用一致的
    --target
    参数

Upgrade Validation Failed

升级验证失败

  • Cause: Trying to swap enterprise (LF 2.2) with community (LF 2.1) packages
  • Fix: Use DAR injection to maintain LF 2.2 compatibility
  • 原因：尝试将企业版（LF 2.2）包替换为社区版（LF 2.1）包
  • 解决：使用DAR注入方式保持LF 2.2兼容性

External References

外部参考