Inspiration
A cocoa shipment can have a supplier name, a declared weight, and a folder of supporting documents while still leaving an important question unanswered: can the reviewer trace the declared supply to usable plot evidence, and identify what still needs investigation?
The information needed to answer that question often arrives separately. Quantities are recorded in spreadsheets. Farm locations arrive as coordinates or map files. Environmental observations come from another source. Supplier clarifications remain in emails.
Having those files does not automatically make them consistent. A plot may be referenced in a spreadsheet but missing from the geolocation file. A boundary may cross itself. Two allocations may exceed the quantity declared for one source lot. A published forest-change observation may require investigation before the reviewer can advance the paperwork.
We built LotHold around that moment of uncertainty.
Instead of producing another sustainability score, LotHold helps a reviewer answer three practical questions:
- What is missing or contradictory?
- Where did the finding come from?
- What evidence should I request next?
Our chosen track is Sustainable Supply Chains. The environmental goal is to make unresolved sourcing evidence easier to identify and investigate. We do not claim that this prototype has prevented deforestation or reduced emissions; those outcomes would require a real-world pilot and follow-up measurement.
The problem
Cocoa exporters and EU importers reviewing shipment evidence face a coordination problem as well as a data problem.
A reviewer needs to connect supplier declarations, source quantities, plot boundaries, environmental observations, and investigation records. When those sources disagree, the useful output is not simply a red warning. It is a clear explanation of the discrepancy and a specific request that someone can act on.
A missing boundary, for example, should lead to a request for the relevant plot geometry. An invalid boundary should identify the geometry problem. An allocation conflict should show the arithmetic. An environmental observation should retain its source, date, coverage, and uncertainty.
Without that connection between finding and action, a reviewer can have more information without having a clearer decision.
LotHold brings these checks into one evidence-review workflow.
Who it is for
LotHold is designed primarily for:
- Cocoa exporter compliance teams preparing shipment evidence and coordinating corrections with suppliers.
- EU importer reviewers checking whether the information supplied for a shipment is complete and internally consistent.
- Supplier or cooperative coordinators responding to precise requests for missing or corrected evidence.
The current implementation focuses on cocoa beans and a limited environmental-data coverage area. It is not a general platform for every commodity, jurisdiction, or supply-chain process.
What it does
1. Collect and confirm source information
A reviewer signs in to a private organisation workspace, creates a case, and uploads source-lot records and plot GeoJSON.
The workspace starts empty. LotHold does not preload fictional commercial shipments.
Before accepting an import, the reviewer can inspect what was parsed. Original values appear alongside their interpreted values, with file and row references. This makes normalization visible rather than silently changing the source information.
Quantities are handled in whole grams. Ambiguous values such as 1,000 are rejected rather than guessed.
2. Identify actionable findings
LotHold checks required fields, supported product scope, country codes, quantities, plot references, and geometry.
Findings point back to the relevant source file, row, column, or plot. The reviewer can see the original value and the reason it requires attention.
Examples include:
- A plot referenced in a source record but absent from the uploaded geometry.
- A self-intersecting boundary.
- A potentially reversed coordinate order requiring confirmation.
- An allocation request exceeding the remaining declared source quantity.
Corrections are explicit. Suspected coordinate swaps are offered for confirmation rather than applied automatically.
3. Inspect environmental evidence
LotHold reads published raster data from JRC Global Forest Cover 2020 and Hansen Global Forest Change, including annual tree-cover-loss observations through 2025.
The current downloaded coverage is one tile covering Côte d’Ivoire and western Ghana.
These observations help a reviewer investigate a declared location. They do not establish that a boundary represents a real cocoa farm, that the supplier owns the land, or that a particular shipment originated there.
The application distinguishes unavailable data, locations outside coverage, and results with no observed loss in the supported data. Those states must not collapse into a single reassuring result.
A land-change signal remains an investigation task. It is not automatically labelled illegal deforestation.
4. Generate a supplier evidence request
A finding should lead to something useful outside the application.
LotHold generates a one-page supplier request PDF containing the missing or contradictory information, its source reference, and the correction or supporting evidence requested.
This is the central practical output: a reviewer can move from “something is wrong with this case” to a specific request.
5. Record review decisions against an evidence snapshot
A reviewer investigating a land-change signal must record an explanation and attach supporting evidence.
Sign-off is tied to the evidence snapshot used for the review. Changes to relevant inputs invalidate the earlier approval and mark affected documents out of date.
This prevents an old sign-off from silently applying to a changed case.
6. Prepare reviewed draft documents
LotHold can generate a human-readable review PDF showing where values came from.
It also supports a DDS V3 XML draft, offered after the required sign-off and only when validation against the official schema set succeeds.
The distinction matters: schema validation checks document structure. It does not establish legal compliance or mean that an authority has accepted the declaration.
LotHold does not submit statements to the EU or invent official reference numbers.
7. Enforce shared declared-allocation limits
A Solidity registry on Ethereum Sepolia records declared batch quantities and reservations.
Within that registry, the contract rejects reservations exceeding the registered quantity and prevents reuse of allocation identifiers.
This provides a shared constraint across participating actors rather than relying only on one application’s internal balance.
Its boundary is explicit: the registry cannot prove physical inventory, verify a declaration’s truth, or detect the same cocoa registered under unrelated batch identities.
How we built it
Frontend and review interface
The frontend uses React, TypeScript, and Vite.
We designed the interface around the reviewer’s task: inspect a case, understand a finding, open the source, request evidence, and record a decision.
The visual system uses near-black, warm off-white, and a restrained forest-green accent. Investigation and hold states use distinct semantic colors. Responsive layouts and reduced-motion behavior are part of the interface work.
Backend and persistence
A Node.js and Hono backend manages authentication, organisation workspaces, uploads, review decisions, and document generation.
SQLite stores application records. Uploaded evidence is encrypted at rest.
The application requires a persistent backend environment because it manages accounts, private files, environmental datasets, and background processing. Publishing the static frontend alone does not provide those capabilities.
Deterministic validation
Typed validation and explicit rules handle consequential decisions such as required fields, quantity arithmetic, geometry errors, and review readiness.
We kept these checks separate from model-generated suggestions. An extraction model should not decide whether an allocation is valid or whether an environmental finding has been resolved.
Environmental processing
The analysis reads actual published raster values rather than inferring a result from how a map looks.
The datasets have different resolutions and meanings, so their outputs require careful interpretation. The application retains coverage and uncertainty instead of presenting every result as a definitive sourcing conclusion.
These are annual observations, not near-real-time alerts.
Blockchain integration
We built and tested the allocation contract using Solidity and Foundry, with Viem supporting application integration.
The Sepolia contract is deployed at:
0x1645604d915c55cfd61cf1492ad58ab5e4150b57
Engineering tests exercised successful reservations, excess requests, duplicate protection, and concurrent allocation behavior.
The contract stores commitments and quantities rather than private supplier documents or precise plot coordinates.
Extraction and AI boundaries
The extraction pipeline includes model-provider adapters and a deterministic label-parser fallback.
Proposed values require human acceptance before becoming case records. Missing information must remain missing.
Live model extraction remains unverified. The configured Gemini service returned a quota error before an extraction completed. We therefore describe the working fallback as a deterministic parser, not AI, and do not count successful authentication as successful extraction.
Document generation
PDF generation produces supplier requests and review drafts. XML export uses the official DDS schema dependencies.
We checked generated documents as rendered outputs, including pagination and character handling, rather than assuming successful file creation meant the document was usable.
Challenges we ran into
Separating evidence from assertions
The most important design challenge was deciding what each input could establish.
A supplier declaration is a statement about supply. A satellite observation describes a measured or classified environmental condition. A reviewer records an investigation. A blockchain receipt records a transaction.
Combining those objects does not make their limitations disappear.
We kept them distinguishable throughout the workflow so that stronger-looking presentation would not become a stronger unsupported claim.
Making environmental uncertainty useful
A result can be unavailable, outside coverage, or inconclusive. Those are operationally different from observing no loss in the available data.
We needed uncertainty to produce a useful next step rather than either a misleading green status or a dead end.
Handling retries and shared state
A repeated request must not reserve inventory twice. Concurrent requests must respect the same remaining balance. A rejected transaction must leave that balance unchanged.
We also encountered stale reads from a public Sepolia endpoint immediately after transactions. This required explicit confirmation and reconciliation behavior rather than assuming the next read would reflect the transaction.
Keeping approvals current
An approval is meaningful only in relation to the information reviewed.
We implemented snapshot-based sign-off so that changing relevant source information cannot leave a previous decision looking current.
Producing dependable exports
PDF character handling and pagination exposed problems that were not obvious from application data alone.
XML introduced another distinction: a document can be well-formed while failing the official schema. We used the actual schema dependencies rather than treating XML syntax as compatibility.
Building without permissioned commercial records
We did not obtain real exporter shipment records during the build.
Instead of inventing provenance, we used explicitly labelled engineering records for testing. Their quantities are test values and their boundaries are not verified farms.
This allowed us to exercise software behavior while retaining an honest boundary around commercial validation.
Accomplishments we're proud of
We connected uploads, source-linked findings, environmental analysis, investigation records, sign-off, and document generation into one local application workflow.
Our recorded verification run included:
- 66 unit and integration tests.
- 18 contract tests.
- 6 browser tests.
- Type checking and a production build.
The tested behaviors include organisation isolation, upload restrictions, duplicate handling, review invalidation, persistence, and reconciliation.
Sepolia engineering tests demonstrated that:
- A reviewer could reserve 600 kg from a registered 1,000 kg test batch.
- A second 600 kg request was rejected.
- A forced excess transaction reverted without changing the balance.
- Retrying an allocation could not reserve it twice.
- Concurrent requests respected the shared available quantity.
These are engineering results, not evidence of real cocoa trading or prevented fraud.
We are also proud of making limitations visible: test records remain labelled, environmental observations retain their interpretation boundaries, and unavailable AI is not presented as a working feature.
What we learned
Traceability is a workflow, not just a ledger. A reviewer needs to move from a finding to its source and then to an appropriate request or decision.
Environmental data needs context. Tree-cover loss is not automatically legally defined deforestation, and no observed signal is not proof of sustainable sourcing.
Validation has layers. Correct arithmetic, valid geometry, schema-valid XML, and a confirmed transaction each answer a different question.
Honest failure states are part of the product. Missing data, unavailable services, and unresolved findings must remain visible without being confused with empty or successful results.
Technical tests do not replace a pilot. Engineering records can establish software behavior. They cannot demonstrate exporter adoption, actual review-time savings, or environmental outcomes.
What's next for LotHold
Our immediate priorities are:
- Connect the public frontend to a persistent hosted backend and verify the complete hosted workflow.
- Complete live AI extraction verification when provider quota is available.
- Test with permissioned, anonymised source-lot records and genuine plot evidence from an exporter or cooperative.
- Observe how reviewers use findings and supplier requests in an actual review process.
- Evaluate additional environmental coverage before expanding to other regions or commodities.
A pilot would let us measure practical outcomes such as whether findings are actionable, whether source references are accurate, how often corrections are needed, and whether supplier requests help resolve cases.
Current availability and limitations
The public website presents the interface and project information. The complete workflow runs locally using the repository’s setup instructions; the public frontend is not yet connected to a working persistent backend.
No real commercial shipment has been processed. Commercial records used in testing are labelled engineering records. Environmental datasets and recorded Sepolia transactions are genuine.
LotHold does not certify EUDR compliance, establish land ownership, prove physical shipment origin, prevent duplication outside its participating registry, or submit regulatory declarations.
It is a working local prototype for making cocoa evidence review clearer, more traceable, and more actionable.
Built With
- ethereum
- foundry
- geotiff
- hono
- javascript
- node.js
- pdfkit
- playwright
- python
- react
- sepolia
- solidity
- sqlite
- turf.js
- typescript
- viem
- vite
- vitest
- zod
Log in or sign up for Devpost to join the conversation.