Ir para o conteúdo

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: BLOCKCHAIN is the only supported ledger mode. Legacy memory and hybrid launcher values normalize to blockchain; they do not bypass Fabric. See LedgerMode.

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. FabricGatewayLedgerMirror has been the monitor's production path since the migration to the Gateway SDK (BL-015). The previous implementation, FabricCliLedgerMirror (invokes the peer binary via ProcessBuilder), remains in the code and is still instantiated directly by 4 of the 5 research experiment sessions (EcgFederatedSession, HarFederatedSession, MimicV31FederatedSession, MnistFederatedSession) — only ErgonomicRiskFederatedSession uses the process's shared Gateway-SDK bridge via FabricExperimentBridgeContext.current(). See details and environment variables for each bridge in docs/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:

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

Result: a 39-character string (sha256: + 32 hex), recorded on the ledger in place of the real clientId.

# Salt mandatory in production
export LGPD_PSEUDONYM_SALT="$(openssl rand -hex 32)"

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 clientId never enters the ledger — use ClientPseudonymService.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.
  • FabricCliConfig resolves the peer binary in this order: $FABRIC_HOME/bin/peer → $FABRIC_PEER_BIN → "peer" on the PATH.

Next steps

  • BL-015: completed — FabricGatewayLedgerMirror uses the Fabric Gateway SDK for Java over gRPC/TLS.