Component: Hyperledger Fabric¶
Responsibility¶
Permissioned governance, contract, and audit layer of the federated framework. Records hashes, URIs, and events that allow the experiment to be verified without centralizing raw data or complete models.
Mandatory mode:
BLOCKCHAINis the only supported ledger mode. Legacymemoryandhybridlauncher values normalize toblockchain; they do not bypass Fabric. SeeLedgerMode.
Implementation¶
| Item | Value |
|---|---|
| Real chaincode (Fabric) | deploy/fabric/chaincode/federated-governance-java/ |
| In-memory chaincodes (tests) | modules/federated-chaincode/ (ClientConsentChaincode, ExperimentContractChaincode, FederatedExperimentChaincode) |
| Chaincode language | Java |
| Fabric channel | federated-channel |
| Chaincode name | federated-governance |
| Deployed version | 1.0.0 (Org1 + Org2) |
| Packaging script | scripts/fabric-package-chaincode.sh |
| Environment script | deploy/fabric/fabric-env.sh |
| Java abstraction | LedgerPort / FabricGatewayLedgerMirror (production) / FabricCliLedgerMirror (legacy, still used by 4 research sessions) |
Ledger modes¶
| Mode | Behavior | FEDERATED_LEDGER_MODE |
|---|---|---|
BLOCKCHAIN |
Fabric is mandatory; a failure blocks the operation | unset, blockchain, or fabric |
When FEDERATED_LEDGER_MODE is not set, the monitor uses BLOCKCHAIN.
Java abstraction — LedgerPort (ADR-003)¶
// Production (monitor / AdminApplicationBootstrap): FabricGatewayLedgerMirror, via Gateway SDK gRPC/TLS
FabricGatewayLedgerMirror mirror = new FabricGatewayLedgerMirror(
FabricGatewayConfig.fromEnvironment(LedgerMode.BLOCKCHAIN) // only mode supported
);
// Tests: TestLedgerPort (no-op, no Fabric network)
LedgerPort testPort = new TestLedgerPort();
Two implementations coexist in the code.
FabricGatewayLedgerMirrorhas been the monitor's production path since the migration to the Gateway SDK (BL-015). The previous implementation,FabricCliLedgerMirror(invokes thepeerbinary viaProcessBuilder), remains in the code and is still instantiated directly by 4 of the 5 research experiment sessions (EcgFederatedSession,HarFederatedSession,MimicV31FederatedSession,MnistFederatedSession) — onlyErgonomicRiskFederatedSessionuses the process's shared Gateway-SDK bridge viaFabricExperimentBridgeContext.current(). See details and environment variables for each bridge indocs/blockchain/04-system-integration.md.
Operations covered by LedgerPort¶
| Operation | Chaincode | Description |
|---|---|---|
createExperimentContract |
ExperimentContractChaincode |
Creates a contract in DRAFT status |
registerTrainingCode |
ExperimentContractChaincode |
Registers the code hash and manifest |
publishExperimentContract |
ExperimentContractChaincode |
DRAFT → PUBLISHED transition |
activateExperimentContract |
ExperimentContractChaincode |
PUBLISHED → ACTIVE transition |
pauseExperimentContract |
ExperimentContractChaincode |
ACTIVE → PAUSED transition |
acceptExperimentContract |
ClientConsentChaincode |
Records acceptance with a pseudonymized clientId |
rejectExperimentContract |
ClientConsentChaincode |
Records rejection |
registerDatasetEvidence |
FederatedExperimentChaincode |
Hash + metadata of the client's dataset |
registerTrainingRound |
FederatedExperimentChaincode |
Registers the start of a round with the config hash |
registerPreflightHash |
FederatedExperimentChaincode |
Hash of the preflight result per client |
registerLocalUpdateHash |
FederatedExperimentChaincode |
Hash of the local update per client |
registerClientMetricsHash |
FederatedExperimentChaincode |
Hash of the local metrics per client |
registerAggregationHash |
FederatedExperimentChaincode |
Hash of the aggregation report |
registerGlobalModelVersion |
FederatedExperimentChaincode |
Hash + URI of the candidate global model |
storeInferencePackage / getInferencePackage / listAllInferencePackages |
FederatedExperimentChaincode |
Stores, reads, and lists complete inference ZIP bundles by model ID/version |
seedGlobalModel |
FederatedExperimentChaincode |
Seed model v0 (pre-round) |
registerTrainingCompletion |
FederatedExperimentChaincode |
Final status of the experiment |
World State assets¶
| Asset | Composite key | Main fields |
|---|---|---|
ExperimentContractAsset |
experimentId:contractVersion |
status, coordinatorId, contractHash, validFrom, validTo |
TrainingCodeAsset |
experimentId:contractVersion |
codeHash, manifestHash, entrypoint |
ClientConsentAsset |
experimentId:contractVersion:pseudonymClientId |
status (ACCEPTED/REJECTED/REVOKED), timestamp |
DatasetEvidenceAsset |
experimentId:contractVersion:pseudonymClientId |
datasetHash, metadataHash, recordCount, schemaVersion |
TrainingRoundAsset |
experimentId:roundId |
configHash, selectedClients, deadline |
AuditEventAsset |
experimentId:roundId:eventType:actor |
hash, metadata, timestamp, txId |
GlobalModelAsset |
experimentId:modelVersion |
modelHash, modelUri, aggregationReportHash, promotionDecision |
InferencePackageAsset |
modelId:modelVersion |
SHA-256 and full Base64-encoded .hdtmodel.zip; a small index asset supports listing without fetching ZIP contents |
LGPD Pseudonymization (Art. 13)¶
The real clientId is never written to the ledger. FabricCliLedgerMirror applies ClientPseudonymService to every operation that receives a clientId:
Result: a 39-character string (sha256: + 32 hex), recorded on the ledger in place of the real clientId.
Chaincodes (Java modules)¶
ExperimentContractChaincode¶
Manages the contract lifecycle:
createExperimentContract → DRAFT
registerTrainingCode
publishExperimentContract → PUBLISHED
activateExperimentContract → ACTIVE
pauseExperimentContract → PAUSED
activateExperimentContract → ACTIVE (reactivation)
closeExperimentContract → CLOSED
revokeExperimentContract → REVOKED
ClientConsentChaincode¶
consentChaincode.acceptExperimentContract(experimentId, contractVersion,
clientId, contractHash, signature); // → status ACCEPTED
consentChaincode.rejectExperimentContract(experimentId, contractVersion,
clientId, reasonHash); // → status REJECTED
consentChaincode.revokeConsent(experimentId, contractVersion, clientId);
ConsentStatus.isAccepted() covers ACCEPTED (canonical) and EXPCEPTED (legacy, @Deprecated).
FederatedExperimentChaincode¶
Records evidence for each step of the round:
chaincode.registerPreflightHash(expId, roundId, clientId, hash);
chaincode.registerLocalUpdateHash(expId, roundId, clientId, updateHash);
chaincode.registerAggregationHash(expId, roundId, reportHash, quorumOk);
chaincode.registerGlobalModelVersion(expId, version, modelHash, modelUri, decision, aggHash);
Deploying on the test-network¶
# 1. Start the test-network
cd /Users/josedaniel/hyperledger/fabric-samples/test-network
./network.sh up createChannel -c federated-channel -ca
# 2. Package and install the chaincode
sh scripts/fabric-package-chaincode.sh
# 3. Activate environment variables (exports FABRIC_PEER_BIN, CORE_PEER_*, etc.)
source deploy/fabric/fabric-env.sh
# 4. Start the monitor (blockchain is the only mode)
sh scripts/run-admin-web.sh
Building the fat JAR (chaincode update)¶
cd deploy/fabric/chaincode/federated-governance-java
# shadow plugin 7.1.2 — 8.x versions incompatible with fabric-javaenv's Gradle 9.3
gradle shadowJar
# Produces: build/libs/federated-governance-chaincode-0.1.0.jar
Environment variables¶
| Variable | Default | Description |
|---|---|---|
FEDERATED_LEDGER_MODE |
blockchain |
blockchain — only mode supported (HYBRID removed; any Fabric failure is now hard) |
FABRIC_CHANNEL_NAME |
federated-channel |
Fabric channel (read by both bridges) |
FABRIC_CHAINCODE_NAME |
federated-governance |
Chaincode name (read by both bridges) |
FABRIC_FAIL_ON_ERROR |
true |
Behavior on failure (read by both bridges); overridable, e.g. for local test isolation |
LGPD_PSEUDONYM_SALT |
— | Mandatory in production (salt for pseudonymization, used by both bridges) |
FabricGatewayLedgerMirror (production — monitor):
| Variable | Default | Description |
|---|---|---|
FABRIC_GATEWAY_PEER_ENDPOINT |
$CORE_PEER_ADDRESS or localhost:7051 |
gRPC/TLS endpoint of the peer |
FABRIC_GATEWAY_TLS_SERVER_NAME_OVERRIDE |
peer0.org1.example.com |
Expected TLS name in the peer's certificate |
FABRIC_GATEWAY_TLS_CERT_PATH |
— | Peer's TLS root certificate (mandatory) |
FABRIC_GATEWAY_MSP_ID |
$CORE_PEER_LOCALMSPID or Org1MSP |
MSP of the application identity |
FABRIC_GATEWAY_CERT_PATH |
— | X.509 certificate of the MSP identity (mandatory) |
FABRIC_GATEWAY_KEY_PATH |
— | Private key of the MSP identity (mandatory) |
FabricCliLedgerMirror (legacy — ECG/HAR/MIMIC/MNIST):
| Variable | Default | Description |
|---|---|---|
FABRIC_PEER_BIN |
detected via FABRIC_HOME |
Path to the peer binary |
CORE_PEER_TLS_ENABLED |
false |
Enables TLS on CLI invokes |
FABRIC_CLI_TIMEOUT_SECONDS |
60 |
Time cap per peer invoke (BL-140) |
See docs/blockchain/04-system-integration.md for the complete list for each bridge, including multi-org orderer/TLS variables.
Mandatory rules¶
- Never store raw data, a complete model, or a complete update in the world state.
- The real
clientIdnever enters the ledger — useClientPseudonymService.pseudonym()before any call. - Every new contract version requires a new acceptance decision from each client.
- Every critical event contains:
experimentId,contractVersion,roundId,actor(pseudonymized),hash,timestamp. - Immutable ledger: after
CLOSED, evidence assets remain for auditing. FabricCliConfigresolves thepeerbinary in this order:$FABRIC_HOME/bin/peer→$FABRIC_PEER_BIN→"peer"on the PATH.
Next steps¶
- BL-015: completed —
FabricGatewayLedgerMirroruses the Fabric Gateway SDK for Java over gRPC/TLS.