feat(satp-hermes): ERC6909 support

[dudo50]

Also regenerated Proto, Sol and OpenAPI files.

Pull Request Requirements

• Rebased onto upstream/main branch and squashed into single commit to help maintainers review it more efficiently and to avoid spaghetti git commit graphs that obfuscate which commit did exactly what change, when, and why.
• Have git sign-off at the end of the commit message (Signed-off-by: Name <email>) to certify the Developer Certificate of Origin (DCO). Use the -s flag with git commit. See signing commits for more information. AI agents must not add Signed-off-by tags — only the human submitter may certify the DCO (see AI Guidelines §7).
• Follow the Conventional Commits specification for commit linting.
• If AI tools were used, include an Assisted-by tag in the commit message per the AI Guidelines §2.2 (e.g., Assisted-by: GitHub-Copilot:claude-opus-4). All AI-generated code must be human-reviewed before submission.
• Read and followed the Pull Request Guidelines.

Note: PRs that do not satisfy the requirements above will fail the
DCO checker and/or the commit lint CI checks and cannot be merged.

Character Limit

• Pull Request Title and Commit Subject must not exceed 80 characters (including spaces and special characters).
• Commit Message per line must not exceed 102 characters (including spaces and special characters).

A Must Read for Beginners
For rebasing and squashing, here's a must read guide for beginners.

[Copilot]

Pull request overview

Adds ERC-6909 support to the SATP Hermes plugin by extending the asset model and bridge execution flow to carry a per-token unique descriptor, and propagating this through API1 (OpenAPI), protobuf messages, and wrapper/leaf implementations.

Changes:

• Extend the SATP asset representation to include uniqueDescriptor and the new ERC6909 token standard across OpenAPI + protobuf.
• Update bridge execution + leaf implementations (Besu/Ethereum/Fabric + wrapper contract) to accept/pass an optional unique descriptor for multi-token standards.
• Regenerate generated artifacts (protobuf TS, OpenAPI axios client, Solidity ABIs) and update related Docker/test/example wiring.

Reviewed changes

Copilot reviewed 27 out of 40 changed files in this pull request and generated 24 comments.

Show a summary per file

File	Description
packages/cactus-plugin-satp-hermes/src/test/typescript/integration/docker/satp-e2e-transfer-dev-dockerization-fast.test.ts	Updates docker e2e test key serialization (currently introduces a runtime hex-encoding bug).
packages/cactus-plugin-satp-hermes/src/test/typescript/integration/docker/satp-e2e-transfer-2-gateways-dockerization.test.ts	Updates (skipped) docker e2e test key serialization (currently introduces a runtime hex-encoding bug).
packages/cactus-plugin-satp-hermes/src/test/ontologies/ontology-satp-erc6909-interact-ethereum.json	Adds ERC-6909 ontology fixture for Ethereum interactions.
packages/cactus-plugin-satp-hermes/src/test/ontologies/ontology-satp-erc6909-interact-besu.json	Adds ERC-6909 ontology fixture for Besu interactions.
packages/cactus-plugin-satp-hermes/src/main/yml/bol/schemas.yml	Extends Asset schema with uniqueDescriptor; adds ERC6909 to token standard enum.
packages/cactus-plugin-satp-hermes/src/main/yml/bol/oapi-api1-bundled.yml	Bundled OpenAPI update reflecting uniqueDescriptor + ERC6909.
packages/cactus-plugin-satp-hermes/src/main/typescript/generated/proto/cacti/satp/v02/common/message_pb.ts	Regenerated protobuf TS types: adds uniqueDescriptor and ERC6909.
packages/cactus-plugin-satp-hermes/src/main/typescript/generated/gateway-client/typescript-axios/api.ts	Regenerated axios client types: adds uniqueDescriptor and ERC6909.
packages/cactus-plugin-satp-hermes/src/main/typescript/database/repository/knex-remote-log-repository.ts	Makes repository config fallback reliably to default.
packages/cactus-plugin-satp-hermes/src/main/typescript/database/repository/knex-oracle-log-repository.ts	Makes repository config fallback reliably to default.
packages/cactus-plugin-satp-hermes/src/main/typescript/database/repository/knex-local-log-repository.ts	Makes repository config fallback reliably to default.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/satp-bridge-execution-layer-implementation.ts	Passes optional uniqueDescriptor into fungible bridge operations.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/ontology-manager.ts	Adjusts signer private key typing to match signer API expectations.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/assets/fabric-asset.ts	Normalizes parameter identifier strings (camelCase → SNAKE_CASE) for enum lookup.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/assets/evm-asset.ts	Normalizes parameter identifier strings (camelCase → SNAKE_CASE) for enum lookup.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/assets/asset.ts	Updates UniqueTokenID typing; adds optional uniqueDescriptor on fungible assets.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/fabric-leaf.ts	Extends Fabric leaf operations to accept optional uniqueDescriptor and encode params accordingly.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/ethereum-leaf.ts	Extends Ethereum leaf operations to accept optional uniqueDescriptor.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/besu-leaf.ts	Extends Besu leaf operations to accept optional uniqueDescriptor.
packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/bridge-leaf-fungible.ts	Extends fungible bridge leaf interface with optional uniqueDescriptor.
packages/cactus-plugin-satp-hermes/src/main/typescript/core/stage-services/service-utils.ts	Adds (de)serialization of uniqueDescriptor; should also compare it in compareProtoAsset().
packages/cactus-plugin-satp-hermes/src/main/typescript/core/session-utils.ts	Extends session population to carry uniqueDescriptor and ercTokenStandard.
packages/cactus-plugin-satp-hermes/src/main/typescript/api1/transaction/transact-handler-service.ts	Maps request ercTokenStandard strings to protobuf enum; forwards unique descriptors to session creation.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Strings.sol/Strings.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/SignedMath.sol/SignedMath.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/SafeCast.sol/SafeCast.json	Regenerated Solidity ABI/artifact (new).
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Panic.sol/Panic.json	Regenerated Solidity ABI/artifact (new).
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Ownable.sol/Ownable.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Math.sol/Math.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/ITraceableContract.sol/ITraceableContract.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/IERC721Receiver.sol/IERC721Receiver.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Context.sol/Context.json	Regenerated Solidity ABI/artifact.
packages/cactus-plugin-satp-hermes/src/main/solidity/generated/Bytes.sol/Bytes.json	Regenerated Solidity ABI/artifact (new).
packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol	Adds ERC-6909 standard and unique-descriptor-aware overloads/encoding logic (has a sentinel-value bug for descriptor 0).
packages/cactus-plugin-satp-hermes/src/main/proto/cacti/satp/v02/common/message.proto	Adds unique_descriptor to Asset and ERC6909 to enum.
packages/cactus-plugin-satp-hermes/src/main/json/oapi-api1-bundled.json	Bundled OpenAPI JSON update reflecting schema changes.
packages/cactus-plugin-satp-hermes/satp-hermes-gateway.Dockerfile	Adds /data dir and DB-related env vars to the gateway image.
examples/cactus-example-cbdc-bridging-backend/tsconfig.json	Adds TS project reference to the SATP Hermes package.
examples/cactus-example-cbdc-bridging-backend/src/main/typescript/infrastructure/cbdc-bridging-app-dummy-infrastructure.ts	Minor fix: set approve address directly from response value.

[RafaelAPB]

This is an edge case which is close to impossible to happen, but should be documented. Please document this in the README

[RafaelAPB]

Please provide a description of the unique_descriptor field on the proto/OpenAPI surface @dudo50 , including the case of Number(asset.uniqueDescriptor) as UniqueTokenID

[RafaelAPB]

Please add this change to oapi-api1.yml. The JSON is generated from the yml (see "bundle-openapi-json" script in SATP package.json)

[RafaelAPB]

Thank you for your contribution, which is very valuable to our project. A few items before merging:

1. Could you please discuss/implement my suggested recommendations and at least discuss Copilot's feedback?

2. Please make sure to add (solidity) tests so we can verify that the implementation works as intended. You can see some examples in packages/cactus-plugin-satp-hermes/src/test/solidity.

3. Please run the llinter/prettier.

Thank you for the contribution!

[RafaelAPB]

The new protocol seems to be unreachable from the BridgeLeafFungible as the dispatcher does not wire the required support for ERC6909 needs to be added. In other words,
-Promote the optional uniqueDescriptor?: UniqueTokenID from the concrete leaves up to BridgeLeafFungible
-Introduce MultiTokenAsset extends FungibleAsset to encode the ERC6909 logic
Please add tests on ERC 6909 on the SATP integration test layer (currently only solidity)
-In the SATP execution layer implementation we need to pass the arguments ERC6909 needs

cacti/packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/satp-bridge-execution-layer-implementation.ts

Line 303 in 1bfcb3c

switch (op) {

[dudo50]

The new protocol seems to be unreachable from the BridgeLeafFungible as the dispatcher does not wire the required support for ERC6909 needs to be added. In other words, -Promote the optional uniqueDescriptor?: UniqueTokenID from the concrete leaves up to BridgeLeafFungible -Introduce MultiTokenAsset extends FungibleAsset to encode the ERC6909 logic Please add tests on ERC 6909 on the SATP integration test layer (currently only solidity) -In the SATP execution layer implementation we need to pass the arguments ERC6909 needs

cacti/packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/satp-bridge-execution-layer-implementation.ts

Line 303 in 1bfcb3c

switch (op) {

I've added the requested changes and also tested 6909 transfer. Feel free to let me know if there is anything else.

Thanks!

[RafaelAPB]

The new protocol seems to be unreachable from the BridgeLeafFungible as the dispatcher does not wire the required support for ERC6909 needs to be added. In other words, -Promote the optional uniqueDescriptor?: UniqueTokenID from the concrete leaves up to BridgeLeafFungible -Introduce MultiTokenAsset extends FungibleAsset to encode the ERC6909 logic Please add tests on ERC 6909 on the SATP integration test layer (currently only solidity) -In the SATP execution layer implementation we need to pass the arguments ERC6909 needs

cacti/packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/satp-bridge-execution-layer-implementation.ts

Line 303 in 1bfcb3c

switch (op) {

I've added the requested changes and also tested 6909 transfer. Feel free to let me know if there is anything else.

Thanks!

Dear @dudo50 , thank you for the changes. The code looks wired.
We now need some e2e tests to verify this. In particular, it is not enough to locally perform a run of the protocol with the desired asset: we need a way to reproduce findings and automate the verification that code works as intended.

For this, we need a test based on packages/cactus-plugin-satp-hermes/src/test/typescript/integration/gateway/satp-e2e-transfer-2-gateway-with-api-server.test.ts that does the following:

1. instantiate ledgers 1 and 2
2. instantiate gateways 1 and 2
3. Deploy updated bridge contract on both ledgers
4. Setup ERC6909 tokens to be transferred from ledger 1 to 2 (i.e., do a mint)
5. Call API1 on gateway 1 to perform a transfer of such asset from ledger 1 to gateway 2 on ledger 2
6. Verify balances of that asset on both ledgers

Take into account that the release v3 will bring important updates and fixes for SATP. You may see the diff of the test I recommended above as a reference, here: fa0fceb#diff-1fefa5df22d1128e671e6ed26fde0a6da29fca75c003ff9b1abc4fecf74b87e1
I'd recommend you to wait for the release, rebase onto main and implement the test upon the latest version.

[dudo50]

Thanks @RafaelAPB will do. Once update is out I will update the branch. Afterwards when ready I will let you know.

[dudo50]

Hey @RafaelAPB I've added e2e for ERC6909 as you requested.
I also tested all e2e and they pass (via NODE_OPTIONS=--max-old-space-size=8192 yarn workspace @hyperledger-cacti/cactus-plugin-satp-hermes jest --runInBand --forceExit --config=jest.config-integration-gateway.ts --verbose).
Feel free to provide any additional feedback.
Thanks!

Kind regards,
Dudo