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