HoneyLedge: honey provenance on Arbitrum Sepolia with a hive-health dashboard

Honey is one of the easiest foods to fake and one of the hardest to check. A jar on a shelf gives you a label and nothing else, and a beekeeper who sells real honey cannot prove it to a buyer who cannot tell the difference. HoneyLedge is the project I built for that gap: a Next.js app that writes each honey batch to a smart contract on Arbitrum Sepolia, tracks who owns it and how it was split from a bigger batch, attaches a geotagged photo, and shows a hive-health dashboard fed by a sensor simulator. This post walks through how it works one requirement at a time, where it is solid, and where the proposal runs ahead of the code.

Understand the problem#

A buyer of raw honey faces three questions the label cannot answer: where it came from, whether it was tampered with on the way, and who held it. The hackathon proposal that started this project cites the 2020 CSE investigation, in which 17 of 22 tested honey samples were found adulterated with sugar syrup. I built the traceability half end to end on a testnet: the registry, the custody chain, the payments and the verification page. The sensor half is a simulation.

Functional requirements#

1. A beekeeper registers a batch with honey type, quantity, base price, extraction and expiry dates, a geotagged photo and a minimum portion size.
2. Anyone can read a batch, its current owner and its lab verification status from the chain.
3. A distributor can buy a whole batch or a portion, and a portion becomes a child batch that records its parent.
4. A buyer pays by card or UPI in a sandbox, and ownership moves only after the server confirms the payment.
5. A jar carries a QR code that opens its traceability page.
6. A hive panel shows temperature, humidity, acoustic frequency and weight change, and alerts the beekeeper on risk.

Non-functional requirements#

1. Tamper evidence. Custody and quantity changes must be public and permanent, with the transaction visible on a block explorer.
2. No wallets for users. A beekeeper or a shopper should not need a browser wallet or testnet ETH.
3. Fast pages. Listing batches must not wait several seconds for chain reads on every navigation.
4. One deployable. Frontend and API in a single Vercel project, no extra servers to run.
5. Works for the audience. A phone-first layout, an installable PWA and an English and Hindi toggle.

Requirements: register, read, split, pay, QR, hive alerts
Constraints:  no user wallets, fast lists, one Vercel project
Missing:      anything that checks a claim before it is written

The set-up#

Core entities#

The model is smaller than the problem sounds. There is one record type, the batch, and four roles that can hold it: beekeeper, distributor, retailer and consumer. A verifier is an address the contract trusts to move honey and set lab status on behalf of others; in this app it is the relayer. A split batch points at its parent.

The interface#

The API is a set of Next.js route handlers, and the interface that matters is the contract. These are the real entry points, trimmed to what the app calls.

POST /api/register-batch        { honeyType, quantityKg, basePriceINR, minSplitKg, ... } -> { ok, batchId, tx }
POST /api/mock-payment          { batchId, toAddress, isSplit, splitQuantity }           -> { success, newBatchId, tx }
POST /api/cashfree/create-order { batchId, role, quantityKg, ... }                      -> { orderId, paymentSessionId }
GET  /api/cashfree/verify-order ?order_id=...                                           -> { isPaid, onChainSettlement }
GET  /api/batches               ?fresh=true                                             -> { batches, total, cached }
GET  /api/verification-status/:id
POST /api/hive/iot/simulate     { temp, humidity, acoustics, weightChange, batchId }    -> { reading: { riskLevel, alerts } }
GET  /api/qr                    ?batchId=1&format=svg|png|json

contract HoneyChain
  registerBatchFor(beekeeper, honeyType, quantityKg, basePriceINR, extractionDate, metadataCID, expiryDate)
  splitBatchByVerifier(parentBatchId, splitQuantity, newOwner) returns (newBatchId)
  transferOwnershipByVerifier(batchId, to)
  setVerificationStatus(batchId, status, verificationMetadataCID, verifiedQuantity)
  setMinPriceInr / setPriceByDistributorInr / setPriceByRetailerInr

The data model#

Everything on chain is one 26-field Batch struct in a mapping keyed by id, plus an array of ids for enumeration. I draw it as three tables because the fields fall into three jobs: what the honey is, who held it when, and whether it was checked and where it came from.

Build it one requirement at a time#

1. Register a batch#

A beekeeper fills in the harvest form and takes a photo. The browser asks for GPS with navigator.geolocation, and /api/ipfs/upload-photo pins the image to Pinata with the latitude, longitude and beekeeper id as key-values. The returned CID goes into register-batch, which wraps it, the minimum portion size and the harvest details into a meta: JSON string and asks the relayer to call registerBatchFor. The contract assigns the next id, makes the beekeeper the current owner and emits BatchRegistered.

1. The camera frame and GPS fix go to upload-photo.
2. Pinata pins the file and returns a CID.
3. The form posts the harvest details with that CID to register-batch.
4. The handler packs the details into the metadata string.
5. The relayer signs registerBatchFor; the handler reads the batch id out of the BatchRegistered log.

After the receipt the handler calls invalidateBatchesCache(), so the next list request sees the new batch instead of a cached copy.

2. Read a batch and verify it#

Reading needs no wallet and no relayer. /api/batches calls getAllBatchIds, then reads each batch with a batches(id) call in parallel and turns the tuple into named fields. The verify page takes a batch id or a scanned QR link and draws a six-stage timeline: survey and hive inspection, harvest and extraction, a lab purity assay, on-chain anchoring, distributor transit and sealing to the consumer. The last two stages light up as the contract's distributor and consumer slots fill.

1. The page asks /api/batches or /api/verification-status/:id.
2. The handler returns the cached list if it is under two seconds old, or joins a read already in flight.
3. Otherwise it reads ids, then each batch, from the contract and decodes the metadata string.

3. Split a batch and keep the lineage#

The distributor portal shows each batch with a minimum purchase, which the beekeeper set at registration. Buying the full lot is a plain ownership transfer. Buying a portion calls splitBatchByVerifier, which does four things in one transaction: it checks the parent holds strictly more than the portion, subtracts the portion from the parent, creates a child with the same honey type, dates, photo CID and verification fields, and sets parentId and isSplit on the child. The child's holder slots depend on who the parent's holder is: beekeeper to distributor, distributor to retailer, retailer to consumer.

1. The portal sends a portion and the buyer address; the handler reads the parent from chain.
2. It rejects a portion that is zero, not smaller than the stock, or below the minimum portion in the metadata string.
3. The relayer sends splitBatchByVerifier(parentId, quantity, newOwner).
4. The contract decrements the parent and mints the child in the same transaction.
5. The handler decodes the BatchSplit receipt log to return newBatchId.

4. Pay, then settle#

The checkout is a Cashfree sandbox hosted-checkout order. create-order stores the batch, role, quantity and destination address, both as order tags and in a local fallback because the sandbox sometimes drops tags. After the buyer pays, verify-order does not trust the redirect: it fetches the order status from Cashfree's API, and only when isPaid is true does it call the relayer to transfer or split. Transient sandbox errors are retried with a linear back-off of 600 ms per attempt.

5. Jar QR codes#

/api/qr renders a honey-coloured QR in SVG, PNG or JSON, defaulting to dark brown on pale yellow, and encodes /verify?id=<batch> on the app's own URL. A consumer jar is just another batch id, so the code on a sealed jar leads to a page that shows the child batch, its parent and the root beekeeper.

6. Hive telemetry and alerts#

The hive panel has four sliders, each with a range and a shaded normal band: brood temperature from 25 to 45 C, humidity from 30 to 95 percent, acoustic frequency from 150 to 700 Hz and weight change from minus 10 to plus 10 kg. A button posts the four values to /api/hive/iot/simulate, which applies fixed thresholds and returns a risk level, a list of alerts and a disease hint. For anything above LOW it also posts to an ntfy topic, with priority urgent for CRITICAL, high for HIGH and default otherwise, so the phone buzzes.

1. The panel sends temperature, humidity, acoustics and weight change.
2. The handler walks four rules and sets riskLevel.
3. A non-LOW result is posted to ntfy with a priority header.
4. The phone receives the push; the response shows the alert list on screen.

Deep dive 1: one string carries the metadata#

Deep dive 2: a chain that is slow to read#

Deep dive 3: settling a payment without double-paying#

Deep dive 4: the relayer, and who may move honey#

Deep dive 5: telemetry rules, and the proposal's three-check gate#

The proposal pairs the gate with ESP32 sensor nodes covering about ten boxes each, at a bill-of-materials estimate of around 3,000 rupees per node, so about 300 rupees per box. It stores the hash of each record on Arbitrum Sepolia and keeps full records off chain, which fits the data-protection law the proposal cites. The first pilot it describes is one KVIC cluster of about 100 boxes with 10 sensor nodes and one lab-linked processor. The 36-hour MVP in the proposal is the simulated sensor feed, the batch registry, the gate and the scan page; the code in this post covers the registry, the scan page and the simulated feed.

The final design#

Pulling the parts together, the shipped system is a stateless web tier in front of a single contract, with the relayer as the only writer and IPFS as the only file store. Reads are public; writes are verified by the app first.

One request, one rebuild#

1. The distributor chooses a 10 kg portion of a 50 kg batch and pays at Cashfree's hosted checkout.
2. The redirect lands on verify-order, which asks Cashfree for the status and finds it paid.
3. The relayer sends splitBatchByVerifier with the parent id, 10 and the distributor address.
4. The contract lowers the parent to 40 kg, mints a child of 10 kg with parentId set, and emits BatchSplit.
5. The handler decodes the child id, clears the batch cache and returns the receipt.
6. The next list request misses the cache, reads the chain once and every viewer sees the new owner.

What I would change#

• Enforce the rules in the contract. The minimum portion, the three-check gate and the lab status belong in Solidity, not in route handlers that a direct caller can skip. I would add a proper minSplitKg field and a require on it.
• Return the real verification status. /api/verification-status/:id returns a constant "verified" alongside the batch and does not return the contract's verification fields. The README describes a live lab-assay lookup that the handler does not do. I would return the real status, verifier and timestamp.
• Fix the risk-level order. In the simulator each rule assigns riskLevel directly, so a later, milder rule can overwrite a worse one: a hot, humid hive ends at MEDIUM unless weight forces CRITICAL. A max over levels would fix it.
• Make the two rule sets agree. The sliders show a normal band of 34 to 36 C and the server alerts at below 32 and above 37; the picture and the rules should come from one table.
• Durable settlement. Store the settled order id in Redis or a table, and add a contract-side idempotency check.
• Real roles. The login page issues fixed demo addresses with a prefilled one-time code. Real sign-in, and per-role signing keys, come before any pilot.
• A genuine sensor path. Replace the sliders with an ESP32 posting to an ingest route, as the proposal describes, and let the three-check gate read that data.
• Remove the baked-in key. Fail closed when RELAYER_PRIVATE_KEY is missing, and rotate any key that was ever committed.

Test yourself#