chore(satp-hermes): document bridge configuration

Signed-off-by: Rafael Belchior <[email protected]>
Co-signed-by: Rafael Belchior <[email protected]>

Author: RafaelAPB

packages/cactus-plugin-satp-hermes/README.md

@@ -163,6 +163,57 @@ const gatewayConfig: {
 
 ### Bridge Configuration
 
+#### Reusing Deployed Wrapper Contracts
+
+When you already have bridge wrapper contracts on-chain, provide their identifiers in the leaf configuration so the deployment step skips redeployment. The CLI entrypoint loads the configuration, `validateCCConfig` verifies the schema, and the bridge manager attaches each leaf to the supplied contract details.
+
+##### Fabric Leaf Wrapper Example
+```typescript
+const fabricWrapperConfig = {
+  networkIdentification: {
+    id: "FabricLedgerTestNetwork",
+    ledgerType: "FABRIC_2",
+  },
+  channelName: "mychannel",
+  signingCredential: {/* Fabric signing credential */},
+  connectorOptions: {/* Fabric connector options */},
+  wrapperContractName: "satp-wrapper-fabric", // Existing chaincode package name
+  claimFormats: [1],
+};
+```
+
+##### Besu Leaf Wrapper Example
+```typescript
+const besuWrapperConfig = {
+  networkIdentification: {
+    id: "BesuLedgerTestNetwork",
+    ledgerType: "BESU_2X",
+  },
+  signingCredential: {/* Besu signing credential */},
+  connectorOptions: {/* Besu connector options */},
+  wrapperContractName: "BesuWrapper",
+  wrapperContractAddress: "0x1234...cdef",
+  claimFormats: [1],
+};
+```
+
+##### Ethereum Leaf Wrapper Example
+```typescript
+const ethereumWrapperConfig = {
+  networkIdentification: {
+    id: "EthereumLedgerTestNetwork",
+    ledgerType: "ETHEREUM",
+  },
+  signingCredential: {/* Ethereum signing credential */},
+  connectorOptions: {/* Ethereum connector options */},
+  wrapperContractName: "EthereumWrapper",
+  wrapperContractAddress: "0x9876...abcd",
+  claimFormats: [1],
+};
+```
+
+If both `wrapperContractName` and `wrapperContractAddress` are present (Fabric only requires the name), leaf deployment logs that contracts already exist and continues without redeploying them.
+
 #### Fabric Configuration Example:
 ```typescript
 const leafConfig = {
@@ -264,6 +315,49 @@ const leafConfig = {
   claimFormats: [1]                               // Claim format identifiers (application-specific)
 }
 ```
+
+### Gateway Example (One Leaf Using Existing Wrapper)
+```typescript
+const gatewayConfig = {
+  gid: {
+    id: "gatewayId",
+    name: "GatewayWithBesuConnection",
+    version: [{ Core: "v02", Architecture: "v02", Crash: "v02" }],
+    proofID: "mockProofID10",
+    address: "http://gateway1.satp-hermes",
+  },
+  logLevel: "TRACE",
+  counterPartyGateways: [],
+  localRepository: localDbKnexConfig,
+  remoteRepository: remoteDbKnexConfig,
+  environment: "development",
+  ontologyPath: "/opt/cacti/satp-hermes/ontologies",
+  enableCrashRecovery: true,
+  ccConfig: {
+    bridgeConfig: [
+      {
+        networkIdentification: {
+          id: "BesuLedgerTestNetwork",
+          ledgerType: "BESU_2X",
+        },
+        signingCredential: {
+          ethAccount: "0x736dC9B8258Ec5ab2419DDdffA9e1fa5C201D0b4",
+          secret: "0xc31e76f70d6416337d3a7b7a8711a43e30a14963b5ba622fa6c9dbb5b4555986",
+          type: "PRIVATE_KEY_HEX",
+        },
+        gas: 999999999999999,
+        connectorOptions: {
+          rpcApiHttpHost: "http://172.20.0.6:8545",
+          rpcApiWsHost: "ws://172.20.0.6:8546",
+        },
+        wrapperContractName: "BesuWrapper",
+        wrapperContractAddress: "0x09D16c22216BC873e53c8D93A38420f48A81dF1B",
+        claimFormats: [1],
+      },
+    ],
+  },
+};
+```
 #### Notes:
 - **Field values:** Replace placeholders (such as file paths, endpoint addresses, credentials, etc.) with values appropriate for your environment.
 - **Security**: Credentials and secret material (certificates, private keys, etc.) must be handled securely, never checked into version control, and managed via secure secrets management.

packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/besu-leaf.ts

@@ -357,8 +357,15 @@ export class BesuLeaf
       try {
         await Promise.all([this.deployWrapperContract()]);
       } catch (err) {
-        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-        span.recordException(err);
+        if (err instanceof WrapperContractAlreadyCreatedError) {
+          this.log.debug(
+            `${fnTag}, Wrapper contracts already exist, skipping deployment`,
+          );
+          span.setStatus({ code: SpanStatusCode.OK });
+        } else {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.recordException(err);
+        }
         throw err;
       } finally {
         span.end();

packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/ethereum-leaf.ts

@@ -341,8 +341,15 @@ export class EthereumLeaf
       try {
         await Promise.all([this.deployWrapperContract()]);
       } catch (err) {
-        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-        span.recordException(err);
+        if (err instanceof WrapperContractAlreadyCreatedError) {
+          this.log.debug(
+            `${fnTag}, Wrapper contracts already exist, skipping deployment`,
+          );
+          span.setStatus({ code: SpanStatusCode.OK });
+        } else {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.recordException(err);
+        }
         throw err;
       } finally {
         span.end();
@@ -368,8 +375,15 @@ export class EthereumLeaf
         }
         return this.wrapperDeployReceipt;
       } catch (err) {
-        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-        span.recordException(err);
+        if (err instanceof WrapperContractAlreadyCreatedError) {
+          this.log.debug(
+            `${fnTag}, Wrapper contracts already exist, skipping deployment`,
+          );
+          span.setStatus({ code: SpanStatusCode.OK });
+        } else {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.recordException(err);
+        }
         throw err;
       } finally {
         span.end();

packages/cactus-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/fabric-leaf.ts

@@ -397,8 +397,15 @@ export class FabricLeaf
           // this.deployNonFungibleWrapperContract(),
         ]);
       } catch (err) {
-        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-        span.recordException(err);
+        if (err instanceof WrapperContractAlreadyCreatedError) {
+          this.log.debug(
+            `${fnTag}, Wrapper contracts already exist, skipping deployment`,
+          );
+          span.setStatus({ code: SpanStatusCode.OK });
+        } else {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.recordException(err);
+        }
         throw err;
       } finally {
         span.end();

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

@@ -610,15 +610,19 @@ export class SATPBridgeExecutionLayerImpl implements SATPBridgeExecutionLayer {
    * @throws {Error} If the method is not implemented.
    */
   public async verifyAssetExistence(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     assetId: string,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     invocationType: unknown,
   ): Promise<boolean | undefined> {
     const fnTag = `${SATPBridgeExecutionLayerImpl.CLASS_NAME}#verifyAssetExistence()`;
     const { span, context: ctx } = this.monitorService.startSpan(fnTag);
     return context.with(ctx, () => {
       try {
+        this.log.debug(
+          `${fnTag}, Verifying asset existence for assetId: ${assetId}`,
+        );
+        this.log.debug(
+          `${fnTag}, invocationType: ${JSON.stringify(invocationType)}`,
+        );
         //todo: implement this
         throw new Error("Not implemented");
       } catch (err) {