Ir para o conteúdo

04 — Integration with the System

This document describes how the blockchain layer connects to the other components of the HDT-AF project: the ledger operating modes, the two bridge implementations to Fabric (FabricGatewayLedgerMirror via the Gateway SDK and FabricCliLedgerMirror via the legacy CLI), the bridge-sharing mechanism across sessions (FabricExperimentBridgeContext), the configuration environment variables, and the chaincode deployment procedure.


Ledger modes

The federated-rest-api module (package br.ufma.lsdi.admin) supports only the BLOCKCHAIN ledger mode. Fabric is required, and failures block the operation:

Mode FEDERATED_LEDGER_MODE env Behavior
BLOCKCHAIN blockchain (default), fabric; legacy launcher aliases are normalized to blockchain Fabric is mandatory. A connection or transaction failure blocks the operation.
// LedgerMode.java
public boolean usesBlockchain()     { return true; }
public boolean failOnFabricError()  { return true; }

Legacy values accepted by launch scripts are normalized to blockchain; the LedgerMode enum itself has no memory-only or failure-tolerant mode. Do not use aliases to work around missing Fabric credentials.


Two bridge implementations to Fabric

The code contains two classes implementing LedgerPort (and the sibling interface FabricExperimentBridge, used by the in-memory chaincode FederatedExperimentChaincode). They are not interchangeable by accident — they represent an ongoing migration:

Implementation Transport Current role
FabricGatewayLedgerMirror Fabric Gateway SDK Java (org.hyperledger.fabric:fabric-gateway:1.11.0) over gRPC/TLS, authenticated with the application's MSP identity Production. This is what AdminApplicationBootstrap builds in createMonitoringService(LedgerMode) and createMonitoringServiceWithMqtt(...) — the path used by AdminWebApp.main.
FabricCliLedgerMirror peer chaincode invoke binary via ProcessBuilder/subprocess Legacy. Predecessor of the Gateway SDK. It still exists in the code and is still the bridge directly instantiated by 4 of the 5 research experiment sessions (see the next section) — not by architectural decision, but because those sessions were never migrated to use the process's shared bridge.

Both implement the same LGPD pseudonymization and the same "idempotent failure" handling (not rethrowing an exception when Fabric already reflects the transaction), but each reads its own configuration from the environment (FabricGatewayConfig vs. FabricCliConfig) and each has its own list of strings recognized as idempotent — see details in the subsections below.

FabricExperimentBridgeContext — shared process bridge (BL-117)

FederatedExperimentChaincode (the in-memory chaincode) has no constructor parameter for receiving a per-session bridge — experiment sessions created dynamically by ExperimentSessionFactory ended up operating in isolation, each purely in memory, never reaching the real Fabric network even with the monitor running in hybrid/blockchain mode. The fix (BL-117) was a static process-wide holder:

// br.ufma.lsdi.chaincode.experiment.FabricExperimentBridgeContext
public static void set(FabricExperimentBridge bridge);   // AdminApplicationBootstrap calls this after building the real bridge
public static FabricExperimentBridge current();          // sessions use this when assembling their own chaincode

AdminApplicationBootstrap.createMonitoringService(...) builds a single FabricGatewayLedgerMirror per process and calls FabricExperimentBridgeContext.set(fabricMirror) right after. Any session that wants to participate in the same audited ledger (the same channel, the same MSP identity, the same already-established gRPC connection) must build its chaincode like this:

new FederatedExperimentChaincode(FabricExperimentBridgeContext.requireCurrent())

Actual state per session (code audit, 2026-07-26):

Session (research/experiments/) How it obtains the Fabric bridge
ErgonomicRiskFederatedSession FabricExperimentBridgeContext.current() — correct, shares the process's real FabricGatewayLedgerMirror
EcgFederatedSession FabricExperimentBridgeContext.requireCurrent() — requires the process's shared Fabric Gateway bridge; no in-memory FederatedExperimentChaincode fallback
HarFederatedSession same — requires the shared Fabric Gateway bridge
MimicV31FederatedSession same — its own FabricCliLedgerMirror
MnistFederatedSession same — its own FabricCliLedgerMirror

HAR and ECG now use the shared Gateway SDK bridge and fail closed if it has not been configured. MIMIC and MNIST still construct their own legacy CLI bridges. Separate remaining gap: HAR/ECG still instantiate process-local ExperimentContractChaincode and ClientConsentChaincode objects for contract/consent workflow state; routing those operations through Fabric-backed adapters remains pending under BL-299. The in-memory simulator objects must not be mistaken for the durable Fabric ledger.


Fabric network (test-network)

The federated-governance chaincode is deployed and in production on the local test-network. The exact version/sequence evolves as upgrades are committed (see querycommitted below and chunk-007-blockchain.md for the latest operational status); the table below shows the reference definition of the first deployment:

Parameter Value
Channel federated-channel
Chaincode federated-governance version 1.0.0 sequence 1 (initial definition)
Approving orgs Org1MSP + Org2MSP
Org1 peer localhost:7051
Org2 peer localhost:9051
Orderer localhost:7050 (orderer.example.com)
Fabric binaries /Users/josedaniel/hyperledger/fabric-samples/bin/
Test-network /Users/josedaniel/hyperledger/fabric-samples/test-network/

To check the chaincode status:

FABRIC_CFG_PATH=/Users/josedaniel/hyperledger/fabric-samples/config \
  peer lifecycle chaincode querycommitted \
  --channelID federated-channel --name federated-governance \
  --tls --cafile <orderer-ca>

Environment configuration script

The deploy/fabric/fabric-env.sh file centralizes variables for the local Fabric network. Source it before running a component when using that local network:

source deploy/fabric/fabric-env.sh
sh scripts/run-admin-web.sh

The script configures:

export FABRIC_PEER_BIN="..."          # path to the peer binary
export FABRIC_CFG_PATH="..."          # peer configuration directory
export FABRIC_CHANNEL_NAME="federated-channel"
export FABRIC_CHAINCODE_NAME="federated-governance"
export FEDERATED_LEDGER_MODE=blockchain

# TLS — Org1 identity
export CORE_PEER_TLS_ENABLED=true
export CORE_PEER_LOCALMSPID=Org1MSP
export CORE_PEER_ADDRESS=localhost:7051
export CORE_PEER_MSPCONFIGPATH="...org1.../Admin@org1.../msp"
export CORE_PEER_TLS_ROOTCERT_FILE="...org1.../tlsca/tlsca.org1.example.com-cert.pem"
export ORDERER_CA="...orderer.../tlsca.example.com-cert.pem"

# Multi-org endorsement (Org1 and Org2)
export FABRIC_ORDERER_ADDRESS=localhost:7050
export FABRIC_ORDERER_HOSTNAME_OVERRIDE=orderer.example.com
export FABRIC_PEER_ADDRESSES="localhost:7051,localhost:9051"
export FABRIC_PEER_TLS_CERTS="<tlsca-org1>,<tlsca-org2>"

clientId pseudonymization (LGPD Art. 13)

Neither of the two bridge implementations (FabricGatewayLedgerMirror nor FabricCliLedgerMirror) writes the real clientId to the ledger. Before any on-chain invocation that receives a participant identifier, both apply the same ClientPseudonymService class:

pseudonym = "sha256:" + sha256(clientId + ":" + experimentId + ":" + LGPD_PSEUDONYM_SALT)[0..31]

The salt is configured via the LGPD_PSEUDONYM_SALT environment variable. The reverse mapping (pseudonym → clientId) exists only in memory in the process that created the ClientPseudonymService instance and is never transmitted to the ledger. Since each bridge creates its own instance of the service, the reverse mapping of the monitor process (FabricGatewayLedgerMirror) and that of a research session with its own FabricCliLedgerMirror (see the previous section) are not shared between them — each process only resolves the pseudonyms it generated itself.

In production, LGPD_PSEUDONYM_SALT is mandatory:

export LGPD_PSEUDONYM_SALT="$(openssl rand -hex 32)"

If not defined, the system falls back to a default development salt (ClientPseudonymService.isDevSalt() detects this case) and issues a warning. See the LGPD RAG reference and the client/Fabric component documents for details.


FabricGatewayLedgerMirror (production bridge)

Class in br.ufma.lsdi.admin, implements LedgerPort and FabricExperimentBridge. Mirrors operations to Fabric through the Fabric Gateway SDK Java (org.hyperledger.fabric:fabric-gateway:1.11.0), submitting transactions over gRPC/TLS via GrpcFabricGatewayClient — without depending on the peer binary or ProcessBuilder.

Construction and prerequisite diagnostics

In the constructor, FabricGatewayConfig.operationalBlocker() deterministically validates whether the required local material exists and is readable (peer endpoint, MSP ID, peer TLS certificate, application MSP certificate, MSP private key) before attempting any gRPC connection:

  • If something is missing: the mirror starts in a non-operational state (isOperational() == false), with operationalBlocker() returning the message for the operator. Every subsequent call fails fast (without attempting the network) and, if failOnError=true (BLOCKCHAIN mode), throws IllegalStateException.
  • If the material exists but the gRPC connection fails at construction time (GrpcFabricGatewayClient throws RuntimeException), the mirror also enters a blocked state, with the exception message.
  • Any submission failure after successful construction (network went down, peer went offline) also marks operational = false from that point on — the mirror does not attempt to recover on its own within the same process.

Idempotency

submit(...) recognizes as non-error (idempotent) any failure whose message — or the details of a GatewayException — contains "asset ja registrado" or "contrato ja existe" (case-insensitive). In these cases the mirror silently returns false, without logging an error or throwing an exception.

Contract rehydration (rehydratedContracts)

When the monitor is restarted with an experiment contract that already exists on Fabric (from a previous process), createExperimentContract(...) detects that the operation was idempotent (submit returned false) and marks the key experimentId:contractVersion in a local Set (rehydratedContracts). Subsequent calls to registerTrainingCode, publishExperimentContract, and activateExperimentContract for that same contract do not resend the transaction — they simply return, avoiding reapplying code registration/publication/activation to a contract that is already ACTIVE on the ledger (which would fail the chaincode's state machine).

Environment variables (FabricGatewayConfig.fromEnvironment)

Variable Default Description
FABRIC_GATEWAY_PEER_ENDPOINT $CORE_PEER_ADDRESS or localhost:7051 Peer's gRPC/TLS endpoint
FABRIC_GATEWAY_TLS_SERVER_NAME_OVERRIDE peer0.org1.example.com Expected TLS name in the peer's certificate
FABRIC_GATEWAY_TLS_CERT_PATH $CORE_PEER_TLS_ROOTCERT_FILE or empty Peer's TLS root certificate (required)
FABRIC_GATEWAY_MSP_ID $CORE_PEER_LOCALMSPID or Org1MSP Application identity's MSP
FABRIC_GATEWAY_CERT_PATH empty X.509 certificate of the MSP identity (required)
FABRIC_GATEWAY_KEY_PATH empty MSP identity private key (required)
FABRIC_CHANNEL_NAME federated-channel Fabric channel
FABRIC_CHAINCODE_NAME federated-governance Name of the chaincode on the channel
FABRIC_FAIL_ON_ERROR true Fabric failures block the operation

The three file paths (FABRIC_GATEWAY_TLS_CERT_PATH, FABRIC_GATEWAY_CERT_PATH, FABRIC_GATEWAY_KEY_PATH) are required for Gateway operation. Missing or unreadable material blocks the operation; a network failure also blocks it.


FabricCliLedgerMirror (legacy bridge)

Predecessor class of the Gateway SDK. Implements the same LedgerPort/FabricExperimentBridge pair, but invokes the peer chaincode invoke binary via ProcessBuilder, building the JSON argument payload in the format {"Args":["functionName","arg1","arg2",...]}. No longer the monitor's production path (that is FabricGatewayLedgerMirror, previous section) — it remains in the code because EcgFederatedSession, HarFederatedSession, MimicV31FederatedSession, and MnistFederatedSession still instantiate it directly (see "Two bridge implementations to Fabric" above).

When TLS is enabled (CORE_PEER_TLS_ENABLED=true), the generated command automatically includes:

peer chaincode invoke \
  -C federated-channel -n federated-governance \
  -c '{"Args":["..."]}' \
  -o localhost:7050 \
  --ordererTLSHostnameOverride orderer.example.com \
  --tls --cafile <orderer-ca> \
  --peerAddresses localhost:7051 --tlsRootCertFiles <tlsca-org1> \
  --peerAddresses localhost:9051 --tlsRootCertFiles <tlsca-org2>

Mapped operations

Java method Chaincode invoked Fabric function
createExperimentContract(contract) ExperimentContractChaincode createExperimentContract
registerTrainingCode(contract) ExperimentContractChaincode registerTrainingCode
publishExperimentContract(id, version) ExperimentContractChaincode publishExperimentContract
activateExperimentContract(id, version) ExperimentContractChaincode activateExperimentContract
pauseExperimentContract(id, version, reason) ExperimentContractChaincode pauseExperimentContract
acceptExperimentContract(id, version, clientId, hash, sig) ClientConsentChaincode ClientConsentChaincode:acceptExperimentContract
rejectExperimentContract(id, version, clientId, reasonHash) ClientConsentChaincode ClientConsentChaincode:rejectExperimentContract
registerDatasetEvidence(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerDatasetEvidence
registerTrainingRound(id, roundId, configHash) FederatedExperimentChaincode FederatedExperimentChaincode:registerTrainingRound
registerPreflightHash(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerPreflightHash
registerLocalUpdateHash(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerLocalUpdateHash
registerClientMetricsHash(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerClientMetricsHash
registerAggregationHash(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerAggregationHash
registerGlobalModelVersion(...) FederatedExperimentChaincode FederatedExperimentChaincode:registerGlobalModelVersion
seedGlobalModel(...) FederatedExperimentChaincode FederatedExperimentChaincode:seedGlobalModel

Idempotent error handling

Fabric failures whose output contains ALREADY_EXISTS, TRAINING_CODE_ALREADY_REGISTERED, INVALID_CONTRACT_TRANSITION, or CONTRACT_IMMUTABLE are handled by the bridge's idempotency rules and are not rethrown. This applies when a transaction has already been committed, including by a previous process run; other Fabric failures block the operation.

Invoke timeout (BL-140)

Each peer chaincode invoke runs with a time cap — by default 60 seconds, configurable via FABRIC_CLI_TIMEOUT_SECONDS. Before this safeguard, a peer invoke against an unresponsive orderer/peer would hang the calling thread indefinitely; since the mirror is invoked from synchronized methods of AdminMonitoringService, this would freeze the entire web monitor. A timeout is treated as a failure (idempotent or not, depending on the partial output captured) — never as a silent success.


FabricCliConfig

Configuration of the peer binary read from the environment at runtime:

public record FabricCliConfig(
    Path peerBinary,
    String channelName,
    String chaincodeName,
    boolean failOnError,
    // TLS / orderer (null = TLS disabled)
    String ordererAddress,
    String ordererHostnameOverride,
    String ordererCaFile,
    List<String> peerAddresses,
    List<String> peerTlsCertFiles
)
Environment variable Default Description
FABRIC_PEER_BIN $FABRIC_HOME/bin/peer or peer Full path to the peer binary
FABRIC_CHANNEL_NAME federated-channel Channel where the chaincodes are installed
FABRIC_CHAINCODE_NAME federated-governance Name of the chaincode on the channel
FABRIC_FAIL_ON_ERROR true Behavior on transaction failure
CORE_PEER_TLS_ENABLED false Enables TLS flags in the peer chaincode invoke command
FABRIC_ORDERER_ADDRESS localhost:7050 Orderer address (when TLS is active)
FABRIC_ORDERER_HOSTNAME_OVERRIDE orderer.example.com Orderer TLS hostname override
ORDERER_CA — Path to the orderer's CA certificate
FABRIC_PEER_ADDRESSES CORE_PEER_ADDRESS Comma-separated list of endorsing peers
FABRIC_PEER_TLS_CERTS CORE_PEER_TLS_ROOTCERT_FILE Comma-separated list of the peers' TLS certs
CORE_PEER_ADDRESS localhost:7051 Fallback: single local peer when FABRIC_PEER_ADDRESSES is not defined

The peerAvailable() method checks whether the file exists and is executable before attempting to invoke any transaction. The tlsEnabled() method returns true when ordererAddress is defined (i.e., CORE_PEER_TLS_ENABLED=true in the environment).


Transaction flow with required Fabric

The flow is the same for both bridges (only the transport in step 2 changes). The local chaincode objects provide application workflow state; they do not replace the required Fabric write:

Admin API / Experiment
    │
    │ 1. Local operation (e.g.: create contract)
    ▼
In-memory simulator (ExperimentContractChaincode)
    │ Success → continues
    │
    │ 2. Writes to Fabric (synchronous; failure blocks the operation)
    ▼
FabricGatewayLedgerMirror.submit(...)          FabricCliLedgerMirror.invoke(...)
  (gRPC/TLS via Gateway SDK — monitor;            ("peer chaincode invoke ..." via subprocess —
   and the ergonomic session via                  ECG/HAR/MIMIC/MNIST, each with its own
   FabricExperimentBridgeContext.current())        instance)
    │                                                │
    ├── Peer reachable and transaction OK → Fabric ledger updated
    ├── Idempotent transaction (contract/asset already exists) → handled by bridge idempotency rules
    └── Peer unavailable, timeout, or error → operation fails

Full transaction flow in an experiment

The diagram below shows the chronological order of Fabric transactions throughout a complete experiment, including per-client dataset evidence registration (registerDatasetEvidence) right after consent is accepted:

Diagrama PlantUML 1

Ver código-fonte PlantUML
    @startuml "Full Transaction Flow in an Experiment"
    !theme plain
    skinparam shadowing false
    skinparam sequenceMessageAlign center
    skinparam maxMessageSize 160

    title Full Transaction Flow in an Experiment — Hyperledger Fabric

    actor Researcher
    participant "Client 1" as Client1
    participant "Client 2" as Client2
    participant "Client 3" as Client3
    participant Orchestrator
    participant Aggregator
    participant "Blockchain (Fabric)" as FAB

    group #LightBlue Contract lifecycle
        Researcher -> FAB : createExperimentContract(...)
        FAB --> Researcher : ExperimentContractAsset (DRAFT)
        Researcher -> FAB : registerTrainingCode(...)
        FAB --> Researcher : TrainingCodeAsset
        Researcher -> FAB : publishExperimentContract(...)
        FAB --> Researcher : ExperimentContractAsset (PUBLISHED)
        Researcher -> FAB : activateExperimentContract(...)
        FAB --> Researcher : ExperimentContractAsset (ACTIVE)
    end

    group #LightGreen Consent and dataset registration
        Client1 -> FAB : acceptExperimentContract(...)
        FAB --> Client1 : ClientConsentAsset (ACCEPTED)
        Client1 -> FAB : registerDatasetEvidence(...)
        FAB --> Client1 : DatasetEvidenceAsset + AuditEvent

        Client2 -> FAB : acceptExperimentContract(...)
        FAB --> Client2 : ClientConsentAsset (ACCEPTED)
        Client2 -> FAB : registerDatasetEvidence(...)
        FAB --> Client2 : DatasetEvidenceAsset + AuditEvent

        Client3 -> FAB : rejectExperimentContract(...)
        FAB --> Client3 : ClientConsentAsset (REJECTED)
        note over Client3 : no dataset evidence is registered\n— consent was not accepted
    end

    group #LightYellow Round 1 — training and aggregation
        Orchestrator -> FAB : registerTrainingRound(round 1)
        FAB --> Orchestrator : AuditEvent (RegisterTrainingRound)

        Client1 -> FAB : registerPreflightHash(round 1)
        FAB --> Client1 : AuditEvent (RegisterPreflightHash)
        Client1 -> FAB : registerLocalUpdateHash(round 1)
        FAB --> Client1 : AuditEvent (RegisterLocalUpdateHash)

        Client2 -> FAB : registerPreflightHash(round 1)
        FAB --> Client2 : AuditEvent (RegisterPreflightHash)
        Client2 -> FAB : registerLocalUpdateHash(round 1)
        FAB --> Client2 : AuditEvent (RegisterLocalUpdateHash)

        Aggregator -> FAB : registerAggregationHash(round 1)
        FAB --> Aggregator : AuditEvent (RegisterAggregationHash)
        Aggregator -> FAB : registerGlobalModelVersion(v1)
        FAB --> Aggregator : GlobalModelAsset + AuditEvent
    end

    note over Orchestrator, FAB
      ... subsequent rounds repeat
      RegisterTrainingRound → updates → aggregation ...
    end note

    group #Plum Completion
        Orchestrator -> FAB : registerTrainingCompletion(...)
        FAB --> Orchestrator : AuditEvent (RegisterTrainingCompletion)
        Researcher -> FAB : closeExperimentContract(...)
        FAB --> Researcher : ExperimentContractAsset (CLOSED)
    end

    @enduml

Known limitations

  1. Simulators do not model MSP, channels, or endorsement. The in-memory simulators (ExperimentContractChaincode, ClientConsentChaincode, FederatedExperimentChaincode) implement the same business invariants as the real chaincodes, but do not model per-organization endorsement policies, channel isolation, Private Data Collections, or MSP certificate revocation. These aspects can only be tested with a real Fabric network (local in Docker containers or a staging environment).

  2. Legacy EXPCEPTED in old reads. The accepted consent status was historically written as EXPCEPTED (a typo for ACCEPTED) both in the simulators and in the real chaincodes. Every new write uses ACCEPTED exclusively (canonical value); reads (getClientConsentStatus, listAcceptedClients) continue to accept both values so as not to break records written before the fix. See LedgerConstants.CONSENT_ACCEPTED/CONSENT_EXPCEPTED and 02-chaincodes.md.

  3. Fabric bridge split across sessions (BL-178). As detailed in "Two bridge implementations to Fabric" above, only ErgonomicRiskFederatedSession participates in the process's shared FabricGatewayLedgerMirror via FabricExperimentBridgeContext. EcgFederatedSession, HarFederatedSession, MimicV31FederatedSession, and MnistFederatedSession continue to open their own FabricCliLedgerMirror (legacy CLI), with their own environment configuration. This means that, today, the evidence for these four experiments is written to the real ledger through a different path (and with a different configuration surface — FABRIC_PEER_BIN/CORE_PEER_* instead of FABRIC_GATEWAY_*) than the one used by the monitor itself. Not yet fixed; the decision on whether to migrate is left for a future review.


Chaincode deployment procedure (reference)

The chaincode is already deployed on the test-network. The procedure below is the reference for re-deployment in case of an update.

Prerequisites

  • Test-network started: ./network.sh up createChannel -c federated-channel -ca
  • Fabric binaries at /Users/josedaniel/hyperledger/fabric-samples/bin/
  • FABRIC_CFG_PATH=/Users/josedaniel/hyperledger/fabric-samples/config

1. Build the fat JAR

cd deploy/fabric/chaincode/federated-governance-java
# The shadow plugin 7.1.2 is required (8.x is incompatible with Gradle 9.3 in the fabric-javaenv container)
gradle shadowJar
# Produces: build/libs/federated-governance-chaincode-0.1.0.jar

2. Packaging

The package is generated from the pre-built fat JAR (not from source), to avoid building inside the Fabric Docker container:

# Staging dir with the JAR
STAGE=$(mktemp -d) && mkdir -p "$STAGE/src"
cp build/libs/federated-governance-chaincode-0.1.0.jar "$STAGE/src/chaincode.jar"

peer lifecycle chaincode package deploy/fabric/federated-governance-chaincode.tar.gz \
  --path "$STAGE" --lang java --label "federated-governance_1.0.0"

3. Install, approve, and commit

# Common variables
PKG=deploy/fabric/federated-governance-chaincode.tar.gz
CHANNEL=federated-channel
ORDERER_CA=<test-network>/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem

# Org1
export CORE_PEER_LOCALMSPID=Org1MSP
export CORE_PEER_ADDRESS=localhost:7051
# (set CORE_PEER_MSPCONFIGPATH and CORE_PEER_TLS_ROOTCERT_FILE for Org1)
peer lifecycle chaincode install $PKG
peer lifecycle chaincode approveformyorg -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com \
  --channelID $CHANNEL --name federated-governance --version 1.0.0 --package-id <id> --sequence 1 \
  --tls --cafile $ORDERER_CA

# Org2 (repeat install and approveformyorg with Org2 vars)

# Commit
peer lifecycle chaincode commit -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com \
  --channelID $CHANNEL --name federated-governance --version 1.0.0 --sequence 1 \
  --tls --cafile $ORDERER_CA \
  --peerAddresses localhost:7051 --tlsRootCertFiles <tlsca-org1> \
  --peerAddresses localhost:9051 --tlsRootCertFiles <tlsca-org2>

The scripts/fabric-package-chaincode.sh script covers only the packaging step. The install/approve/commit steps are manual or via network.sh deployCC.