Ir para o conteúdo

03 — World State Assets

The Hyperledger Fabric world state stores seven asset types for the HDT-AF project. All are implemented as Java record types with a toJson() method that serializes the fields using the Json utility (no external dependencies).

Each asset includes the asset_type, transaction_id, and timestamp fields, which identify the Fabric transaction that created it.


1. ExperimentContractAsset

Chaincode: ExperimentContractSmartContract Composite key: (experiment_contract, experimentId, contractVersion) Class: br.ufma.lsdi.fabric.contracts.assets.ExperimentContractAsset

Represents the federated experiment contract. It is created with status DRAFT and evolves according to the state machine described in 02-chaincodes.md.

JSON field Type Description
asset_type string Always "ExperimentContract"
experiment_id string Unique experiment identifier
contract_version string Semantic version of the contract (e.g., "1.0")
contract_hash string SHA-256 hash of the off-chain contract document (sha256:...)
contract_uri string URI of the contract document in the Artifact Experiment Service
coordinator_id string Identifier of the responsible researcher/coordinator
status string Current status: DRAFT, PUBLISHED, ACTIVE, PAUSED, CLOSED, REVOKED
valid_from string Start of the contract's validity (ISO-8601 or epoch)
valid_to string End of validity (may be empty for contracts with no expiration date)
created_tx_id string ID of the Fabric transaction that created the asset
created_at string Creation timestamp (epoch seconds)
updated_tx_id string ID of the last transaction that updated the status
updated_at string Timestamp of the last update
status_reason_hash string Hash of the reason for pausing or revocation (filled in by pauseExperimentContract and revokeExperimentContract)
final_report_hash string Hash of the final closure report (filled in by closeExperimentContract)

The full contract stays off-chain at contract_uri. When the researcher defines a central test dataset, this document must contain an evaluation_dataset section with dataset_id, owner_id, uri, hash, metric_name, distribution_policy, evaluate_client_models, and evaluate_global_model. The required value of distribution_policy is researcher_only_never_to_clients; the test dataset is never stored in the world state nor distributed to clients.

JSON example:

{
  "asset_type": "ExperimentContract",
  "experiment_id": "exp-har-smartphones-001",
  "contract_version": "1.0",
  "contract_hash": "sha256:a3f1c2d4e5b6...",
  "contract_uri": "artifacts://contracts/exp-har-smartphones-001/1.0.json",
  "coordinator_id": "researcher-lsdi-ufma",
  "status": "ACTIVE",
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_to": "",
  "created_tx_id": "txid-abc123",
  "created_at": "1748304000",
  "updated_tx_id": "txid-def456",
  "updated_at": "1748390400",
  "status_reason_hash": "",
  "final_report_hash": ""
}


2. TrainingCodeAsset

Chaincode: ExperimentContractSmartContract Composite key: (training_code, experimentId, contractVersion, codeHash) Class: br.ufma.lsdi.fabric.contracts.assets.TrainingCodeAsset

Represents the training code authorized for a specific contract version. A contract version accepts exactly one registered code.

JSON field Type Description
asset_type string Always "TrainingCode"
experiment_id string Experiment identifier
contract_version string Contract version the code belongs to
code_hash string SHA-256 hash of the training JAR (sha256:...)
code_uri string URI of the JAR in the Artifact Experiment Service
signature string Researcher's digital signature over the JAR
manifest_hash string SHA-256 hash of the JSON manifest describing the code (sha256:...)
entrypoint string Full name of the class implementing TrainingLocalModel (e.g., br.ufma.lsdi.training.DtFederatedJob)
registered_tx_id string ID of the registration transaction
registered_at string Registration timestamp

Why register the code on the blockchain: The hash and signature guarantee that the code executed on each client is exactly the one authorized by the researcher. Any modification or replacement of the JAR would be detected during the client's local validation before training.


3. ClientConsentAsset

Chaincode: ClientConsentSmartContract Composite key: (consent, experimentId, contractVersion, clientId) Class: br.ufma.lsdi.fabric.contracts.assets.ClientConsentAsset

Represents a client's decision regarding a specific contract version. A single client may have multiple records over time (acceptance → revocation), but each operation overwrites the asset at the composite key (the Fabric ledger keeps the full history of key versions).

JSON field Type Description
asset_type string Always "ClientConsent"
experiment_id string Experiment identifier
contract_version string Contract version accepted or rejected
client_id string Unique federated client identifier
accepted_contract_hash string Hash of the contract at the moment of acceptance (empty on rejection/revocation)
signature string Client's signature over the acceptance (empty on rejection/revocation)
status string Status: EXPCEPTED, REJECTED, REVOKED
reason_hash string Hash of the reason for rejection or revocation (empty on acceptance)
transaction_id string Fabric transaction ID
timestamp string Timestamp of the operation

Acceptance integrity guarantee: The accepted_contract_hash field is compared against the contract_hash of the ExperimentContractAsset at the moment of acceptance. This prevents a client from accepting a version different from the one registered on-chain.


4. AuditEventAsset

Chaincode: FederatedExperimentSmartContract Composite key: (audit, experimentId, roundId, txId) Class: br.ufma.lsdi.fabric.contracts.assets.AuditEventAsset

Represents an auditable event from any phase of the experiment. Events are append-only: each call creates a new asset with a unique key (the Fabric transaction's txId guarantees uniqueness). The list of events for an experiment can be queried via listAuditEvents.

JSON field Type Description
asset_type string Always "AuditEvent"
event_type string Event type (see table below)
experiment_id string Experiment identifier
round_id string Round number (integer; "0" for events outside a specific round)
actor_id string Identifier of the actor that generated the event (clientId, "orchestrator", "aggregator")
evidence_hash string SHA-256 hash of the evidence associated with the event (sha256:...)
metadata_json string Additional metadata in JSON (e.g., quorum, final status)
transaction_id string Fabric transaction ID
timestamp string Transaction timestamp

Event types (event_type):

Value Emitted by Evidence
RegisterTrainingRound Orchestrator Hash of the round configuration
RegisterDatasetEvidence Client Hash of the partitioned local dataset
RegisterPreflightHash Client Hash of the preflight report
RegisterLocalUpdateHash Client Hash of the local update file
RegisterAggregationHash Aggregator Hash of the aggregation report
RegisterGlobalModelVersion Aggregator Hash of the candidate global model
RegisterTrainingCompletion Orchestrator Hash of the final report

5. DatasetEvidenceAsset

Chaincode: FederatedExperimentSmartContract Composite key: (dataset_evidence, experimentId, contractVersion, clientId) Class: br.ufma.lsdi.fabric.contracts.assets.DatasetEvidenceAsset

Records evidence of a client's local dataset for a specific experiment. It does not store raw data — only hashes and metadata that allow verifying the dataset's integrity and compatibility without revealing its content.

JSON field Type Description
asset_type string Always "DatasetEvidence"
experiment_id string Experiment identifier
contract_version string Associated contract version
client_id string Client identifier
dataset_hash string SHA-256 hash of the client's dataset.csv file (sha256:...)
metadata_hash string SHA-256 hash of the client's metadata.json file (sha256:...)
record_count string Number of records in the dataset (integer as string)
schema_version string Data schema version (e.g., "1.0")
data_path_hash string Hash of the local data directory path (sha256:...), without revealing the real path
registered_tx_id string ID of the registration transaction
registered_at string Registration timestamp

Idempotency: a second call with the same values is accepted without error. A second call with divergent values throws DATASET_EVIDENCE_ALREADY_EXISTS — protection against retroactive tampering.


6. GlobalModelAsset

Chaincode: FederatedExperimentSmartContract Composite key: (global_model, experimentId, modelVersion) Class: br.ufma.lsdi.fabric.contracts.assets.GlobalModelAsset

Represents a version of the global model produced by an aggregation round. Since the on-chain vs. off-chain policy change described in 01-overview.md, the model's own weight vector and the round's training information are stored on-chain, alongside the evidence fields (hash, URI, promotion decision) kept from the previous design.

JSON field Type Description
asset_type string Always "GlobalModel"
experiment_id string Experiment identifier
model_version string Model version number (integer as string; incremented each round)
model_hash string SHA-256 hash of the model vector (sha256:...) — still recomputable from model_vector_csv for integrity checks
model_uri string URI of the model's off-chain mirror in the Artifact Experiment Service (kept for the existing download/serving path; the ledger no longer depends on it for the model's own bytes)
promotion_decision string Promotion decision: PROMOTED, REJECTED, PENDING, or "candidate"/"seed"
aggregation_report_hash string Hash of the aggregation report that produced this model (sha256:...)
model_vector_csv string The model's weight vector itself, serialized as comma-separated values (empty string "" for the seed model, version 0, before any training)
hyperparameters_json string Round hyperparameters (RoundConfig.hyperparameters()) as a JSON object string; "{}" when unavailable at the call site (see the note below)
metrics_json string Training/evaluation metrics for the round (loss, evaluation metric, per-client evaluation) as a JSON object string; "{}" if none
aggregation_provenance_json string Aggregation provenance — participating clients' weights, quorum status, total training examples — as a JSON object string; "{}" if none
registered_tx_id string ID of the registration transaction
registered_at string Registration timestamp

Immutability: once registered, a model version cannot be overwritten with a different hash or URI (hyperparameters_json/metrics_json/aggregation_provenance_json are not part of the idempotency check, only model_hash/model_uri). An overwrite attempt with a different hash/URI throws GLOBAL_MODEL_ALREADY_EXISTS.

hyperparameters_json availability: AggregationReport carries the round's hyperparameters (hyperparameters, filled from RoundConfig by FedAvgAggregationService.aggregate(...) and AggregationResultPublisher.publish(...)), so every writer — aggregator, publisher, AdminMonitoringService and the Docker aggregation-result callback — records the real values (BL-264). It is "{}" only when the producer of the report never knew them.


7. ClientUpdateAsset

Chaincode: FederatedExperimentSmartContract Composite key: (client_update, experimentId, roundId, clientId) Class: br.ufma.lsdi.fabric.contracts.assets.ClientUpdateAsset

Represents a client's local model update for a round — introduced by the same policy change as GlobalModelAsset's new fields. Previously, a local update was only ever recorded as an AuditEventAsset carrying its hash; it now also gets this dedicated, queryable asset carrying the update's own weight vector and training information.

JSON field Type Description
asset_type string Always "ClientUpdate"
experiment_id string Experiment identifier
round_id string Round number (integer as string)
client_id string Client identifier (LGPD: pseudonymized by the caller before this transaction, same as every other per-client field on this chaincode)
update_hash string SHA-256 hash of the update vector (sha256:...)
update_vector_csv string The client's local update vector itself, serialized as comma-separated values
sample_count string Number of training samples used locally (integer as string)
positive_count string Number of positive-class samples (integer as string; 0 when not applicable)
update_norm string L2 norm of the update vector (decimal as string)
local_metric string Local evaluation metric value (decimal as string, e.g., accuracy)
local_metric_name string Name of the local metric (e.g., "accuracy")
registered_tx_id string ID of the registration transaction
registered_at string Registration timestamp

Immutability: once registered for a given (experimentId, roundId, clientId), a client update cannot be overwritten with a different update_hash. A divergent retry throws CLIENT_UPDATE_ALREADY_EXISTS; a retry with the identical hash is accepted as idempotent (no new asset write, but the accompanying RegisterLocalUpdateHash audit event is still appended).

Every registerLocalUpdateHash call still also appends a RegisterLocalUpdateHash AuditEventAsset, unchanged from the previous design — the dedicated asset above is additional, not a replacement of the audit trail.


Summary: asset map by chaincode

ExperimentContractSmartContract
├── ExperimentContractAsset   (experiment_contract, experimentId, contractVersion)
└── TrainingCodeAsset         (training_code, experimentId, contractVersion, codeHash)

ClientConsentSmartContract
└── ClientConsentAsset        (consent, experimentId, contractVersion, clientId)

FederatedExperimentSmartContract
├── AuditEventAsset           (audit, experimentId, roundId, txId)
├── DatasetEvidenceAsset      (dataset_evidence, experimentId, contractVersion, clientId)
├── GlobalModelAsset          (global_model, experimentId, modelVersion)
└── ClientUpdateAsset         (client_update, experimentId, roundId, clientId)

Hash policy

All fields representing cryptographic hashes must: 1. Have the sha256: prefix (validated by Validation.requireHash()). 2. Be computed by the issuer before calling the transaction. 3. Be recomputed by the receiver when downloading the off-chain artifact for verification.

The format is: sha256:<hex-lowercase-64-chars>.

Example: sha256:3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c