Skip to main content

Customs Clearance - Audit Trails

This real-world example models a customs-clearance process for an international shipment. Multiple parties — a documents operator, export broker, import broker, inspector, and supervisor — each contribute their part of the process to a shared, tamper-proof Audit Trail. Once clearance is granted, the trail is permanently locked to prevent post-clearance modifications.

Business Context​

International customs clearance involves multiple stakeholders, sequential handoffs, and regulatory requirements for document retention. A blockchain-based audit trail provides:

  • Regulatory Compliance: Tamper-proof records satisfying customs data retention requirements
  • Multi-Party Coordination: Each stakeholder writes only the events they own, enforced by tag-scoped roles
  • Finality Guarantee: A write lock after clearance ensures the official record cannot be altered
  • Auditability: Any party can independently verify the complete clearance history

Field Usage Strategy​

  • immutable_metadata: Shipment identity — shipment ID, route, declaration number
  • updatable_metadata: Current customs-processing status (e.g., "Status: Awaiting Export Clearance")
  • record.data: Event payload describing each step of the clearance process
  • record.metadata: Structured event context (e.g., "event:export_cleared")
  • record.tag: Event category — documents, export, import, or inspection

Role Design​

RolePermissionsRoleTagsHolder
AdminFull administrative control—Trail creator
DocsOperatorAddRecord, DeleteRecord, CorrectRecord"documents"Shipping agent
ExportBrokerAddRecord, DeleteRecord, CorrectRecord"export"Export customs broker
ImportBrokerAddRecord, DeleteRecord, CorrectRecord"import"Import customs broker
InspectorAddRecord, DeleteRecord, CorrectRecord"inspection"Customs inspector (created on demand)
SupervisorUpdateMetadata, DeleteMetadata—Process supervisor
LockingAdminUpdateLockingConfig variants—Process supervisor

Prerequisites​

Implementation Overview​

1. Set Up Multiple Wallets​

Create one wallet per actor in the clearance process — an admin, a documents operator, an export broker, an import broker, a supervisor, a locking admin, and an inspector — so each party signs with its own address.

Used Utility Functions
examples/audit-trail/real-world/01_customs_clearance.rs
loading...

2. Create the Customs Clearance Trail​

Create a trail with four record tags, shipment identity as immutable metadata, and a status tracker as updatable metadata.

examples/audit-trail/real-world/01_customs_clearance.rs
loading...

3. Define Tag-Scoped Roles​

Create operational roles scoped to their respective tags, plus a Supervisor role for metadata updates and a LockingAdmin for final locking.

Used Utility Functions
examples/audit-trail/real-world/01_customs_clearance.rs
loading...

4. Process the Clearance Steps​

Each stakeholder adds records tagged with their category. The supervisor updates the status metadata at each phase transition. The Inspector role is created on demand when an inspection is required.

examples/audit-trail/real-world/01_customs_clearance.rs
loading...

5. Lock the Trail After Clearance​

Once the shipment is fully cleared, apply an infinite write lock to freeze the audit record. Any attempt to add further records is rejected.

examples/audit-trail/real-world/01_customs_clearance.rs
loading...

Real-World Applications​

Freight Forwarding​

  • Scenario: Multi-modal shipment tracking across sea, air, and ground with customs clearance at each border
  • Tags: "bill_of_lading", "customs_declaration", "inspection", "delivery_confirmation"

Trade Finance​

  • Scenario: Letter of credit lifecycle tracking with document verification at each stage
  • Tags: "application", "issuance", "shipment_docs", "payment", "settlement"

Agricultural Export​

  • Scenario: Phytosanitary certification and export compliance for agricultural commodities
  • Tags: "certification", "inspection", "export_permit", "quarantine"

Running Examples Locally​

In order to run the examples, you will need to run an IOTA network locally. See the local network setup guide.

Full Example Code​

Used Utility Functions
examples/audit-trail/real-world/01_customs_clearance.rs
loading...