KiiWORKS / Documentation
Standards & Regulatory Compliance
SOURCE · docs/standards-compliance.md · synced from the engineering repo
Standards & Regulatory Compliance
KiiWORKS implements data models and validation logic aligned with international standards and EU regulations. This document details each standard and how KiiWORKS uses it.
EU Regulations
ESPR — Ecodesign for Sustainable Products Regulation (2024/1781)
The ESPR mandates Digital Product Passports for nearly all physical products sold in the EU. KiiWORKS implements:
- Product data model: Structured passport with product identity, materials, environmental impact, lifecycle stages
- Data carrier: QR codes with GS1 Digital Link URIs
- Machine-readable access: REST API for passport data retrieval
- Tamper evidence: Blockchain anchoring of passport state hashes
- Lifecycle tracking: EPCIS-based event recording from manufacturing through end-of-life
Relevant service: dpp, regulator
EU Battery Regulation (2023/1542)
Mandatory for EV batteries from February 2027. KiiWORKS provides:
- Battery-specific DPP fields: State of health, cycle count, capacity, chemistry
- Carbon footprint declaration: CO2 per kWh tracking
- Material composition: Bill of materials with recycled content percentages
- Due diligence: Supply chain traceability for cobalt, lithium, nickel
- Compliance checks (regulator service):
- Carbon footprint threshold verification
- Recycled content minimum verification
- State of health monitoring
- Material composition completeness
- Supply chain due diligence documentation
Relevant service: regulator (5 pre-built battery regulation checks)
ESPR Compliance Checks
The regulator service includes 4 pre-built ESPR checks:
- Data completeness — verifies all required DPP fields are populated
- Lifecycle coverage — confirms events span required lifecycle stages
- Tamper evidence — checks blockchain anchoring exists
- Data carrier — verifies QR/Digital Link availability
EBSI — European Blockchain Services Infrastructure
EBSI is the European Union’s sovereign blockchain — a permissioned Besu network operated by EU Member State node operators, designed for institutional cross-border use cases. KiiWORKS supports EBSI as a regulator-facing anchor target alongside Kaspa:
- What EBSI is: A multi-tenant permissioned Ethereum-family network (Hyperledger Besu) governed by EBP (European Blockchain Partnership) Member States. Gas-free by design — fees are paid via Member State quotas, not user wallets. Two environments: pre-production (
api-pilot.ebsi.eu, chain id 5611) and production. - How KiiWORKS interoperates: The
kiiworks-bridgecrate’s unifiedEvmChainAdapterspeaks EBSI’s JSON-RPC interface directly. The adapter enforces EBSI’s requirement that data anchors go through a deployedAnchorRegistrycontract (calldata-only mode is refused at construction). Operators deployAnchorRegistry.sol(bundled incrates/bridge/contracts/) to their assigned EBSI node and supply the address viaEVM_ANCHOR_CONTRACT. - Participation model: EBSI access requires either (a) running a Member State node under an existing EU Member State partnership, or (b) integrating through an EBSI-aligned conformant wallet / service provider. KiiWORKS does not provision EBSI accounts — operators arrange access independently and supply credentials via env vars.
- Use cases: Digital Product Passport regulator endpoints (Battery Reg, ESPR, CBAM), eFTI freight visibility for cross-border movements, and verifiable credential issuance under the EU Trust Framework (planned — EBSI v4 DID/VC integration, Q3 2027).
- Why it matters for KiiWORKS: EBSI provides EU-sovereign settlement that satisfies regulator expectations about jurisdiction, data residency, and operator accountability. Public chains (Ethereum L2s) provide broader interop and developer ergonomics but no sovereign EU footprint. KiiWORKS dual-anchors to Kaspa (high-throughput public, primary trust anchor) and EBSI (regulator-facing redundancy) for institutional pilots.
See guides/ebsi-evm-anchor.md for the operator deployment procedure and configuration reference.
Relevant crate: kiiworks-bridge (EvmChainAdapter with EvmNetwork::EbsiPreProduction / EvmNetwork::EbsiMainnet)
GS1 Standards
GTIN (Global Trade Item Number)
KiiWORKS validates GTINs per the GS1 General Specification:
- GTIN-8: 8-digit identifier for small items
- GTIN-12: 12-digit UPC-A (North America)
- GTIN-13: 13-digit EAN (international)
- GTIN-14: 14-digit for logistics units
Validation includes check digit calculation using the modulo-10 algorithm.
Crate: kiiworks-passport (validate_gtin())
GS1 Digital Link
QR codes generated by KiiWORKS use GS1 Digital Link URIs:
https://id.gs1.org/01/04012345000010/21/SERIAL-001
─────────────── ── ────────────── ── ──────────
resolver domain AI GTIN AI serialApplication Identifiers (AIs) from the kiiworks-standards crate:
| AI | Name | Example |
|---|---|---|
| 01 | GTIN | 04012345000010 |
| 10 | Batch/Lot | BATCH-2026-001 |
| 21 | Serial Number | SN-12345 |
| 17 | Expiry Date | 260301 |
| 3103 | Net Weight (g) | 005000 |
Crate: kiiworks-standards (Gs1ApplicationIdentifier, Gs1DigitalLinkUri)
EPCIS 2.0 (Electronic Product Code Information Services)
KiiWORKS maps EPCIS events to DPP lifecycle stages. The kiiworks-standards crate defines the full EPCIS 2.0 vocabulary:
Business Steps (20 defined)
| BizStep URN | Description | DPP Lifecycle Stage |
|---|---|---|
urn:epcglobal:cbv:bizstep:commissioning | Item created | Manufacturing |
urn:epcglobal:cbv:bizstep:shipping | Item shipped | Shipping |
urn:epcglobal:cbv:bizstep:receiving | Item received | Distribution |
urn:epcglobal:cbv:bizstep:inspecting | Quality check | Quality Control |
urn:epcglobal:cbv:bizstep:repairing | Repair event | Maintenance |
urn:epcglobal:cbv:bizstep:destroying | End of life | Recycling |
urn:epcglobal:cbv:bizstep:recycling | Recycling | Recycling |
| … | (13 more) | Auto-mapped |
Dispositions (11 defined)
active, inactive, damaged, recalled, in_transit, returned, disposed, sold, reserved, stolen, unknown
Business Transaction Types (7 defined)
purchase_order, despatch_advice, invoice, receiving_advice, return_merchandise, production_order, transfer_order
Crate: kiiworks-standards (EpcisBizStep, EpcisDisposition, EpcisBizTransaction)
W3C Standards
DID (Decentralized Identifiers) v1.0
KiiWORKS implements did:kaspa: — a DID method anchored on the Kaspa blockchain:
did:kaspa:testnet-12:a1b2c3d4e5f6789...DID Documents follow W3C DID Core:
@context:https://www.w3.org/ns/did/v1verificationMethod: SchnorrSecp256k1VerificationKey2024authentication: DID-based loginassertionMethod: Credential issuance
Crate: kiiworks-forge (DidKaspaMethod)
Verifiable Credentials (VC) v2.0
KiiWORKS issues and verifies W3C Verifiable Credentials:
{
"@context": ["https://www.w3.org/2018/credentials/v1"],
"type": ["VerifiableCredential", "ProductPassportCredential"],
"issuer": "did:kaspa:testnet-12:...",
"issuanceDate": "2026-03-20T10:00:00Z",
"credentialSubject": {
"id": "urn:gtin:04012345000010",
"productName": "Li-Ion Battery Module 48V",
"carbonFootprint": "35.2 kgCO2e/kWh"
},
"proof": {
"type": "SchnorrSecp256k1Signature2024",
"verificationMethod": "did:kaspa:testnet-12:...#key-1",
"proofValue": "..."
}
}Crate: kiiworks-forge (VcIssuer)
DID Method Types (from standards crate)
DidKaspa, DidKey, DidWeb, DidPeer, DidEthr, DidIon, DidSov, DidExample
VC Types
VerifiableCredential, VerifiablePresentation, ProductPassportCredential, SupplyChainCredential, ComplianceCredential, IdentityCredential
Proof Types
SchnorrSecp256k1Signature2024, Ed25519Signature2020, JsonWebSignature2020, EcdsaSecp256k1Signature2019
GLEIF vLEI / LEI / KERI
KiiWORKS implements the GLEIF (Global Legal Entity Identifier Foundation) verifiable identity stack — ISO 17442 LEIs, the W3C vLEI credential family, and a minimal KERI event log.
ISO 17442 — Legal Entity Identifier
- 20-character alphanumeric code with ISO 7064 mod-97 checksum.
kiiworks-standards::vlei::Leinewtype validates the code on construction; mistyped or tampered LEIs cannot be constructed.
vLEI credential family (GLEIF EGF)
| Type | Issued by | Issued to |
|---|---|---|
GleifRootCredential | GLEIF (self-issued) | GLEIF |
QualifiedVLeiIssuerCredential | GLEIF Root | Qualified vLEI Issuer |
LegalEntityVLeiCredential | QVI | Legal entity (by LEI) |
OfficialOrganizationalRoleCredential | Legal Entity | Officer holding an official role |
EngagementContextRoleCredential | Legal Entity | Person in a defined engagement context |
The verifier (kiiworks-vlei::VLeiVerifier) walks the chain back to a
GLEIF Root and rejects any presentation whose root is missing,
revoked, or of the wrong type.
KERI (Key Event Receipt Infrastructure)
- 44-character base64url AID prefixes.
- Append-only event log with inception, rotation, interaction, and delegated-inception/rotation events.
- Implementation is structural and minimal — sequencing, inception-first, and prior-digest invariants are enforced, but signer-signature verification, pre-rotation commitment, witness receipts, and out-of-order recovery are deferred.
Crates: kiiworks-standards (vlei module), kiiworks-vlei,
kiiworks-vlei-service.
Residual risk for production deployment
KiiVLeiIssuer’s deterministic key derivation is currently active even
in production mode (KIIWORKS_VLEI_PRODUCTION_MODE=true). The
production gate today only checks that the env var is set; it does not
yet swap the keystore. A FileBackedKeystore stub exists at the trait
level but is not wired into issuer signing. Real key custody — an
HSM-backed HardwareKeystore (PKCS#11, AWS KMS, GCP Cloud HSM, Azure
Managed HSM, or a YubiHSM2 cluster) with audit logging and rotation —
is a Foundation engineering task that MUST land before any production
identity issuance. Operators running this build with the production
flag set are still relying on derived keys and MUST treat issuance as
non-production until the keystore wiring lands. Tracked as a vLEI
hardening item in the post-Toccata roadmap.
Gaia-X Trust Framework
KiiWORKS implements Gaia-X trust framework types for European data space interoperability:
GaiaXParticipant: Legal entity in a data ecosystemGaiaXServiceOffering: Service description with termsGaiaXComplianceCredential: Compliance attestationGaiaXCredentialType: LegalPerson, ServiceOffering, DataResource, SoftwareResource, ComplianceCredential
The trust service (platform/trust) includes a GaiaXComplianceChecker that validates participant credentials against framework requirements.
Crate: kiiworks-standards (gaiax module), platform/trust
UNECE (United Nations Economic Commission for Europe)
Recommendation 20 — Unit Codes
29 unit codes defined for measurement standardisation:
| Code | Symbol | Unit |
|---|---|---|
| KGM | kg | Kilogram |
| GRM | g | Gram |
| MTR | m | Metre |
| LTR | l | Litre |
| CEL | °C | Celsius |
| WTT | W | Watt |
| WHR | Wh | Watt-hour |
| KWH | kWh | Kilowatt-hour |
| AMP | A | Ampere |
| VLT | V | Volt |
| … | … | (19 more) |
Country Codes (ISO 3166)
30 country codes with alpha-2, alpha-3, and numeric representations.
Currency Codes (ISO 4217)
16 currency codes: EUR, USD, GBP, JPY, CHF, CNY, KRW, INR, BRL, AUD, CAD, SEK, NOK, DKK, PLN, CZK.
Crate: kiiworks-standards (unece module)
Industry-Specific Standards
VDA (Verband der Automobilindustrie)
German automotive industry association standards:
- Part Categories (17): RawMaterial, MetalAlloy, Polymer, Ceramic, Composite, Electronic, Mechanical, Fastener, Seal, Bearing, Motor, Sensor, PCB, Cable, Housing, Connector, Software
- Material Classes (16): Steel, Aluminium, Copper, Titanium, Magnesium, Zinc, Nickel, Cobalt, Lithium, Graphite, Silicon, Polyethylene, Polypropylene, Nylon, Epoxy, CarbonFiber
Crate: kiiworks-standards (vda module)
DCSA (Digital Container Shipping Association)
Maritime shipping event types:
- Transport Events: Departed, Arrived, Loaded, Discharged
- Equipment Events: GateIn, GateOut, Stuffing, Stripping, PickUp, DropOff, Inspection
- Shipment Status: Booked, Confirmed, Departed, InTransit, Arrived, Delivered, Cancelled
Crate: kiiworks-standards (dcsa module)
Schema.org
14 Schema.org types mapped: Product, Organization, Place, Event, CreativeWork, Action, QuantitativeValue, PropertyValue, Offer, Review, Rating, Person, PostalAddress, GeoCoordinates.
Dublin Core
15 Dublin Core metadata elements: title, creator, subject, description, publisher, contributor, date, type, format, identifier, source, language, relation, coverage, rights.
FOAF (Friend of a Friend)
10 FOAF properties for agent descriptions: name, mbox, homepage, depiction, knows, member, interest, based_near, made, account.
W3C vCard
Typed contact-card primitives for personal and organizational contacts, aligned with the W3C vCard ontology (http://www.w3.org/2006/vcard/ns#):
VCard— top-level contact card with formatted name, structured name, organization, email, telephone, address, URL, photo, birthday, role, title, note, geo, timezone, categoriesVCardName— structured name (familyName, givenName, additionalName, honorificPrefix, honorificSuffix)VCardAddress— postal address (streetAddress, locality, region, postalCode, countryName, type)VCardTelephone— telephone entry (value, type) where type ∈ work | home | cell | faxVCardKind— Individual, Organization, Group, LocationVCardProperty— 27 property URIs for fine-grained JSON-LD generation
JSON-LD context exposed via vcard_context(). Used for institutional contact representation in Verifiable Credentials, Gaia-X participant self-descriptions, and supply-chain partner records.
Crate: kiiworks-standards (respective modules — foaf, vcard, schema_org, dublin_core)
ODRL (Open Digital Rights Language)
The rights-management service implements ODRL 2.2 for policy expression:
Actions (from standards crate)
Use, Transfer, Print, Display, Execute, Distribute, Modify, Read, Write, Stream, Reproduce, Aggregate, Annotate, Translate
Used to define data sharing agreements between supply chain participants.
Service: rights-management
Zero-Knowledge Compliance
The kiiworks-zkp crate enables proving compliance without revealing sensitive data:
Selective Disclosure
- Reveal specific DPP fields while hiding others
- Hash commitments prove hidden fields exist and are consistent
Range Proofs
- Prove a value is within a range without revealing it
- Example: “Carbon footprint is below 50 kgCO2e/kWh” without revealing exact value
Equality Proofs
- Prove two hidden values are equal
- Example: “Declared origin matches actual origin” without revealing the location
This is critical for supply chain confidentiality — a battery manufacturer can prove regulatory compliance to auditors without revealing proprietary composition data to competitors.
JSON-LD Schema Registry Contexts
KiiWORKS ships 15 canonical JSON-LD @context documents at crates/standards/contexts/ covering the Foundation’s domain vocabularies:
| Context file | Domain |
|---|---|
anchor.jsonld | On-chain anchor proof structure |
attestation.jsonld | Verifiable attestation envelope |
audit.jsonld | Audit log entries |
catalogue.jsonld | Federated catalogue entries (DCAT-aligned) |
common.jsonld | Shared vocabulary primitives |
dataspace.jsonld | Eclipse Dataspace Protocol message envelopes |
did.jsonld | DID document and DID method extensions |
document.jsonld | Document management metadata |
governance.jsonld | Foundation governance terms |
iot.jsonld | IoT sensor batch and reading vocabulary |
legal.jsonld | Legal-entity and jurisdiction primitives |
nft.jsonld | NFT and trust-tag attestation envelopes |
supply-chain.jsonld | Supply chain event and lineage vocabulary |
trust.jsonld | Trust framework (Gaia-X aligned) |
vc.jsonld | Verifiable Credential envelope conventions |
These are the canonical Foundation contexts. JSON-LD documents produced by KiiWORKS reference them via stable URLs.
Static-serve route — DONE. kiiworks-api mounts the contexts directory at /.well-known/contexts/{name}.jsonld with Content-Type: application/ld+json. The directory is resolved in this order: explicit path → KIIWORKS_CONTEXTS_DIR environment variable → workspace default crates/standards/contexts/. Directory listings are disabled; missing files return 404. See platform/api/src/contexts.rs and crates/standards/contexts/README.md for implementation details.
GET https://api.kiiworks.org/.well-known/contexts/anchor.jsonld
→ 200 OK, Content-Type: application/ld+jsonSource-of-record: copied from the v1 reference codebase at kiiworks/apps/schema-registry/schemas/ on 2026-05-05.
Trade Rails Standards
The trade-rails suite adds typed support for the following standards in crates/standards/:
EU Carbon Border Adjustment Mechanism (CBAM) — Regulation (EU) 2023/956
Module: crates/standards/src/cbam.rs + crates/standards/src/cbam/{defaults,loader}.rs. Covers:
- Six covered goods categories (cement, hydrogen, fertilisers, iron and steel, aluminium, electricity).
- Transitional (quarterly) and definitive (annual) reporting periods.
- Embedded-emissions reports (direct + indirect, with EU default-value markers).
- Verifier attestation envelope (Article 8) required for the definitive period.
- Certificates-required calculation (1 cert per tCO2e, rounded up).
- CBAM default-emission values table — typed per-CN8 lookup keyed to
Commission Implementing Regulation (EU) 2025/2621 Annex.
cbam_default_for(cn_code)— exact match.cbam_default_for_category(category)— category-level fallback.cbam_resolve_default(cn_code)— exact → category resolution chain.- Each entry carries
effective_from/superseded_bydates to track Commission revisions.
- Runtime loader —
JsonFileCbamDefaultsLoaderreads a JSON file (env:CBAM_DEFAULTS_FILE) so the full per-CN8 expansion ships as a Foundation data artefact without binary recompile. See docs/guides/cbam-defaults.md.
Relevant service: cbam. Routes: GET /api/cbam/defaults/{cn_code},
GET /api/cbam/defaults, POST /api/cbam/defaults.
UNCITRAL Model Law on Electronic Transferable Records (MLETR)
Module: crates/standards/src/mletr.rs. Implements the four functional requirements (information, singularity, integrity, exclusive control) needed for an electronic record to qualify as the functional equivalent of a paper transferable document. Used by kiiworks-trade-documents to mark eBLs and electronic warehouse receipts as transferable.
Relevant service: trade.
ICC UCP 600 / eUCP 2.1 / URDG 758 / URC 522
Module: crates/standards/src/ucp.rs. Typed references to UCP 600 articles, LC form and lifecycle states, eUCP 2.1 articles for electronic presentation, URDG 758 demand-guarantee form/state, URC 522 collection type and release condition.
Relevant service: trade.
EU Electronic Freight Transport Information (eFTI) — Regulation (EU) 2020/1056
Module: crates/standards/src/efti.rs. Competent-authority categories, data subsets (consignment, parties, equipment, routing, goods, dangerous goods, documents), transport modes, and access rules.
Relevant service: efti.
UN/CEFACT extended trade primitives
Module: crates/standards/src/unece_extended.rs. UN/EDIFACT TDED 1001 document-type codes for all standard trade documents, Incoterms 2020, payment terms, transport modes.
Relevant crates: trade-documents, customs.
IATA Cargo-XML / Cargo-IMP
Module: crates/standards/src/iata.rs. Message-type stubs (FWB, FFM, FHL, FSU, FBR, FBC, FCL, FCE, FPD) with a minimal envelope. Full XML mapping deferred.
UIC RailML / TAF-TSI
Module: crates/standards/src/uic.rs. Message-type stubs (CIM, PreAdvice, TrainComposition, WagonMovement, Arrival, EtaUpdate, DangerousGoodsDeclaration, CustomsHandover) with a minimal envelope.
Harmonized System (HS) — WCO HS 2022 nomenclature
Module: crates/customs/src/chapter.rs (99-chapter index) and crates/customs/src/hs_code.rs (newtype, 6-10 digit validation).
Relevant service: customs.
EU Customs Procedure Codes (Box 37 of the SAD)
Module: crates/customs/src/procedure.rs. 13 procedures including release for free circulation (40, 42), permanent export (10), inward/outward processing, temporary admission, customs warehousing, re-export.
Relevant service: customs.
Sanctions list authorities (no list data bundled)
Module: crates/sanctions/src/lib.rs. Typed SanctionsList enum for OFAC, EU Consolidated, UK OFSI, UN Security Council, BIS Entity List, EU Dual-Use. List data is sourced out-of-band by the Foundation.
KiiWORKS ships native parsers for the four major published lists:
| Authority | Format | Module | Source | Cadence | License |
|---|---|---|---|---|---|
| OFAC SDN | XML | crates/sanctions/src/loaders/ofac.rs | sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML | Daily | US public domain (17 USC § 105) |
| EU Consolidated | XML | crates/sanctions/src/loaders/eu.rs | webgate.ec.europa.eu/fsd/fsf/public/files/xmlFullSanctionsList_1_1/content | Daily | Commission Decision 2011/833/EU |
| UK OFSI | XML + CSV | crates/sanctions/src/loaders/uk.rs | assets.publishing.service.gov.uk/.../ConList.xml | Daily | Open Government Licence v3.0 |
| UN Security Council | XML | crates/sanctions/src/loaders/un.rs | scsanctions.un.org/resources/xml/en/consolidated.xml | Irregular | Free use with attribution |
Production deployments select the FileLoadingScreener via KIIWORKS_SANCTIONS_BACKEND=file and point SANCTIONS_{OFAC,EU,UK,UN}_PATH at the mirrored files. See docs/guides/sanctions-screening.md for the full operational guide.
Relevant service: sanctions.
Catena-X / SAMM (Semantic Aspect Meta Model)
Module: crates/catena-x. Parser + mapper for Catena-X aspect models.
Implements the SAMM characteristic subset needed for the automotive
battery DPP (io.catenax.battery.battery_pass): Quantifiable + unit,
Trait + constraints, Enumeration, Code, SingleEntity, Set / List /
SortedSet / Collection, TimeSeries, Text, Boolean, Either,
StructuredValue. Both JSON and TTL projections are accepted; unmapped
properties are preserved on passport.extensions.catena_x so no
Catena-X data is silently discarded.
Relevant service: dpp (via POST /api/dpp/import/catena-x).
See Catena-X Interoperability Guide.