VPDS Blockchain API

RegistryContract

Beneficiary and family identity — the DID registry, officer approval records, and ingestion manifests.

• POST/api/blockchain/approvalsWrite

  Anchor an officer's signed registration decision.

  Chaincode

  RegistryContract:ApproveRegistration

  Signed by

  GovernanceMSPstate_admindistrict_officer

  Parameters of ApproveRegistration, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	caseCode	string	body	yes
  2	familyDID	string	body	yes
  3	payloadHash	hash64	body	yes
  4	decision	string	body	yes
  5	signature	string	body	yes

• POST/api/blockchain/didsWrite

  Register a W3C-style DID for a card, family or member.

  Chaincode

  RegistryContract:CreateDID

  Signed by

  GovernanceMSPdistrict_officerverification_officerstate_admin

  Parameters of CreateDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	body	yes
  2	subjectType	string	body	yes
  3	subjectRef	string	body	yes
  4	controller	string	body	yes
  5	publicKeyHash	hash64	body	yes
  6	metadata	string	body	optional

• POST/api/blockchain/ingestion-manifestsWrite

  Anchor the digest of an ePDS / Smart-PDS ingestion batch.

  Chaincode

  RegistryContract:RecordIngestionManifest

  Signed by

  GovernanceMSPstate_admindistrict_officer

  Parameters of RecordIngestionManifest, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchCode	string	body	yes
  2	sourceRef	string	body	yes
  3	mappingVersion	string	body	yes
  4	recordCount	integer	body	yes
  5	manifestHash	hash64	body	yes

• POST/api/blockchain/dids/:did/revokeWrite

  Revoke a DID. State-level act — district officers are excluded on-chain.

  Chaincode

  RegistryContract:RevokeDID

  Signed by

  GovernanceMSPstate_admin

  Parameters of RevokeDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	path	yes
  2	reason	string	body	optional

• PUT/api/blockchain/dids/:didWrite

  Re-anchor a DID document (new key hash and/or metadata).

  Chaincode

  RegistryContract:UpdateDID

  Signed by

  GovernanceMSPstate_admindistrict_officerverification_officer

  Parameters of UpdateDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	path	yes
  2	publicKeyHash	hash64	body	optional
  3	metadata	string	body	optional

• GET/api/blockchain/approvals/:caseCodeRead

  Read the current approval record for a registration case.

  Chaincode

  RegistryContract:GetApproval

  Signed by

  any organisation

  Parameters of GetApproval, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	caseCode	string	path	yes

• GET/api/blockchain/approvals/:caseCode/historyRead

  Every decision ever recorded against a case, including reversals.

  Chaincode

  RegistryContract:GetApprovalHistory

  Signed by

  any organisation

  Parameters of GetApprovalHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	caseCode	string	path	yes

• GET/api/blockchain/dids/:did/historyRead

  Full version history of a DID document.

  Chaincode

  RegistryContract:GetDIDHistory

  Signed by

  any organisation

  Parameters of GetDIDHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	path	yes

• GET/api/blockchain/ingestion-manifests/:batchCodeRead

  Read an ingestion manifest.

  Chaincode

  RegistryContract:GetIngestionManifest

  Signed by

  any organisation

  Parameters of GetIngestionManifest, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchCode	string	path	yes

• GET/api/blockchain/ingestion-manifests/:batchCode/historyRead

  Every manifest version recorded for an ingestion batch.

  Chaincode

  RegistryContract:GetIngestionManifestHistory

  Signed by

  any organisation

  Parameters of GetIngestionManifestHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchCode	string	path	yes

• GET/api/blockchain/dids/:didRead

  Read a DID document.

  Chaincode

  RegistryContract:ResolveDID

  Signed by

  any organisation

  Parameters of ResolveDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	path	yes

• GET/api/blockchain/dids/:did/verifyRead

  Check whether a DID exists, is active and is unrevoked.

  Chaincode

  RegistryContract:VerifyDID

  Signed by

  any organisation

  Parameters of VerifyDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	did	string	path	yes

VerificationContract

What the system has CONCLUDED about a household — screening verdicts and risk assessments.

• POST/api/blockchain/risk-assessmentsWrite

  Anchor a fraud risk score, band and the rule codes that fired.

  Chaincode

  VerificationContract:RecordRiskAssessment

  Signed by

  StateMSP or GovernanceMSP

  Parameters of RecordRiskAssessment, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardRef	string	body	yes
  2	riskScore	string	body	yes
  3	riskBand	string	body	yes
  4	ruleCodes	string	body	yes
  5	evidenceHash	hash64	body	yes
  6	rulesVersion	string	body	yes

• POST/api/blockchain/screeningsWrite

  Anchor an eligibility screening verdict (AAY / PHH / NPHH / Rejected).

  Chaincode

  VerificationContract:RecordScreening

  Signed by

  GovernanceMSPdistrict_officerverification_officerstate_admin

  Parameters of RecordScreening, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardRef	string	body	yes
  2	resultHash	hash64	body	yes
  3	eligibilityCategory	string	body	yes
  4	screeningStatus	string	body	yes

• GET/api/blockchain/screenings/:cardRefRead

  Read the current screening record for a card.

  Chaincode

  VerificationContract:GetScreening

  Signed by

  any organisation

  Parameters of GetScreening, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardRef	string	path	yes

• GET/api/blockchain/screenings/:cardRef/historyRead

  Every screening and risk assessment recorded for a card.

  Chaincode

  VerificationContract:GetScreeningHistory

  Signed by

  any organisation

  Parameters of GetScreeningHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardRef	string	path	yes

LifecycleContract

The append-only beneficiary lifecycle log — births, deaths, migrations, bifurcations.

• POST/api/blockchain/registry-eventsWrite

  Append a lifecycle event (birth, death, migration, bifurcation, …).

  Chaincode

  LifecycleContract:RecordRegistryEvent

  Signed by

  GovernanceMSPdistrict_officerverification_officerstate_admin

  Parameters of RecordRegistryEvent, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	eventID	string	body	yes
  2	cardRef	string	body	yes
  3	memberRef	string	body	optional
  4	eventType	string	body	yes
  5	detailHash	hash64	body	yes

• GET/api/blockchain/registry-events/by-card/:cardRefRead

  A card's full lifecycle log, oldest first.

  Chaincode

  LifecycleContract:QueryRegistryEventsByCard

  Signed by

  any organisation

  Parameters of QueryRegistryEventsByCard, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardRef	string	path	yes

SupplyChainContract

Grain movement from procurement to FPS receipt — batches, dispatches, transport, receipts, exceptions, and the 3-way delivery match.

• POST/api/blockchain/dispatches/:dispatchID/receiptWrite

  Confirm delivery receipt at a State Warehouse or Fair Price Shop.

  Chaincode

  SupplyChainContract:ConfirmReceipt

  Signed by

  StateMSPstate_warehouse_operatorfps_operator

  Parameters of ConfirmReceipt, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes
  2	receivedQty	number	body	yes
  3	fpsSign	string	body	optional
  4	qrScan	string	body	yes

• POST/api/blockchain/batchesWrite

  Create a procurement batch at an FCI godown, with quality capture.

  Chaincode

  SupplyChainContract:CreateBatch

  Signed by

  CentralMSPwarehouse_operator

  Parameters of CreateBatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchID	string	body	yes
  2	grainType	string	body	yes
  3	quantityMT	number	body	yes
  4	sourceWH	string	body	yes
  5	destFPS	string	body	yes
  6	scheme	string	body	yes
  7	stage	integer	body	yes
  8	originType	string	body	yes
  9	destType	string	body	yes
  10	parentBatchID	string	body	optional
  11	qualityGrade	string	body	optional
  12	moisturePct	number	body	optional
  13	inspectionRef	string	body	optional
  14	inspectorDID	string	body	optional

• POST/api/blockchain/batches/childWrite

  Split a received batch into an onward consignment for an FPS.

  Chaincode

  SupplyChainContract:CreateChildBatch

  Signed by

  StateMSPstate_warehouse_operator

  Parameters of CreateChildBatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	childBatchID	string	body	yes
  2	parentBatchID	string	body	yes
  3	stateWarehouseID	string	body	yes
  4	destFPS	string	body	yes
  5	scheme	string	body	optional

• POST/api/blockchain/dispatchesWrite

  Dispatch a consignment: vehicle, driver, GPS device and planned route.

  Chaincode

  SupplyChainContract:CreateDispatch

  Signed by

  CentralMSP or StateMSPwarehouse_operatorstate_warehouse_operator

  Parameters of CreateDispatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	body	yes
  2	batchID	string	body	yes
  3	vehicleReg	string	body	yes
  4	driverID	string	body	yes
  5	gpsDeviceID	string	body	yes
  6	routeJSON	json	body	yes
  7	dispatchQty	number	body	yes

• POST/api/blockchain/dispatches/:dispatchID/exceptionWrite

  Raise a receipt discrepancy (shortage, damage, quality).

  Chaincode

  SupplyChainContract:EscalateReceiptException

  Signed by

  StateMSPstate_warehouse_operatorfps_operator

  Parameters of EscalateReceiptException, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes
  2	receivedQty	number	body	yes
  3	reason	string	body	optional
  4	detail	string	body	optional

• POST/api/blockchain/dispatches/:dispatchID/exception/resolveWrite

  Close a receipt exception with a resolution note.

  Chaincode

  SupplyChainContract:ResolveReceiptException

  Signed by

  GovernanceMSPstate_admin

  Parameters of ResolveReceiptException, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes
  2	note	string	body	optional

• POST/api/blockchain/dispatches/:dispatchID/transportWrite

  Validate a consignment in transit against its AIS-140 GPS trail.

  Chaincode

  SupplyChainContract:ValidateTransport

  Signed by

  StateMSPtransfer_operator

  Parameters of ValidateTransport, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes
  2	gpsEventsJSON	json	body	yes
  3	driverSignature	string	body	yes
  4	transportQtyMT	number	body	yes
  5	deviationToleranceKM	number	body	yes

• POST/api/blockchain/dispatches/:dispatchID/verificationWrite

  Run the 3-way match and anchor the VERIFIED / FAILED verdict.

  Chaincode

  SupplyChainContract:VerifyDelivery

  Signed by

  GovernanceMSPstate_admin

  Parameters of VerifyDelivery, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/batches/:batchIDRead

  Read one batch.

  Chaincode

  SupplyChainContract:GetBatch

  Signed by

  any organisation

  Parameters of GetBatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchID	string	path	yes

• GET/api/blockchain/batches/:batchID/historyRead

  Every ledger version of a batch, with transaction ids.

  Chaincode

  SupplyChainContract:GetBatchHistory

  Signed by

  any organisation

  Parameters of GetBatchHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchID	string	path	yes

• GET/api/blockchain/dispatches/:dispatchIDRead

  Read one dispatch.

  Chaincode

  SupplyChainContract:GetDispatch

  Signed by

  any organisation

  Parameters of GetDispatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/dispatches/:dispatchID/exceptionRead

  Read the open exception on a dispatch.

  Chaincode

  SupplyChainContract:GetDispatchException

  Signed by

  any organisation

  Parameters of GetDispatchException, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/exceptions/:exceptionIDRead

  Read one exception by its own id.

  Chaincode

  SupplyChainContract:GetException

  Signed by

  any organisation

  Parameters of GetException, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	exceptionID	string	path	yes

• GET/api/blockchain/dispatches/:dispatchID/exception/historyRead

  Every state an exception passed through, with transaction ids.

  Chaincode

  SupplyChainContract:GetExceptionHistory

  Signed by

  any organisation

  Parameters of GetExceptionHistory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/dispatches/:dispatchID/receiptRead

  Read the receipt recorded against a dispatch.

  Chaincode

  SupplyChainContract:GetReceipt

  Signed by

  any organisation

  Parameters of GetReceipt, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/dispatches/:dispatchID/verificationRead

  Read the 3-way match verdict for a dispatch.

  Chaincode

  SupplyChainContract:GetVerification

  Signed by

  any organisation

  Parameters of GetVerification, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	dispatchID	string	path	yes

• GET/api/blockchain/batches/by-stage/:stageRead

  List batches at one stage of the two-stage chain.

  Chaincode

  SupplyChainContract:QueryBatchesByStage

  Signed by

  any organisation

  Parameters of QueryBatchesByStage, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	stage	integer	path	yes

• GET/api/blockchain/batchesRead

  List batches, optionally filtered by status. Empty status = all.

  Chaincode

  SupplyChainContract:QueryBatchesByStatus

  Signed by

  any organisation

  Parameters of QueryBatchesByStatus, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	status	string	query	optional

• GET/api/blockchain/batches/by-warehouse/:warehouseIDRead

  List batches originating at one warehouse.

  Chaincode

  SupplyChainContract:QueryBatchesByWarehouse

  Signed by

  any organisation

  Parameters of QueryBatchesByWarehouse, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	warehouseID	string	path	yes

• GET/api/blockchain/dispatchesRead

  List dispatches, optionally filtered by status. Empty status = all.

  Chaincode

  SupplyChainContract:QueryDispatches

  Signed by

  any organisation

  Parameters of QueryDispatches, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	status	string	query	optional

• GET/api/blockchain/batches/:batchID/dispatchesRead

  Every dispatch raised against a batch.

  Chaincode

  SupplyChainContract:QueryDispatchesByBatch

  Signed by

  any organisation

  Parameters of QueryDispatchesByBatch, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	batchID	string	path	yes

• GET/api/blockchain/exceptionsRead

  List exceptions, optionally filtered by status and severity.

  Chaincode

  SupplyChainContract:QueryExceptions

  Signed by

  any organisation

  Parameters of QueryExceptions, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	status	string	query	optional
  2	severity	string	query	optional

DistributionContract

The last mile — the immutable proof that grain was issued from a Fair Price Shop to a household.

• POST/api/blockchain/distributionsWrite

  Anchor grain issued from an FPS to a household. No PII on-chain.

  Chaincode

  DistributionContract:RecordDistribution

  Signed by

  StateMSP or GovernanceMSPfps_operatorstate_admin

  Parameters of RecordDistribution, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	receiptNumber	string	body	yes
  2	cardDID	string	body	optional
  3	memberDID	string	body	optional
  4	fpsID	string	body	yes
  5	itemsJSON	json	body	yes
  6	cycleMonth	string	body	yes
  7	receiptHash	hash64	body	optional

• POST/api/blockchain/entitlement-qrsWrite

  Anchor a cycle's entitlement QR. Refuses a second QR for the same card and cycle.

  Chaincode

  DistributionContract:RecordEntitlementQR

  Signed by

  GovernanceMSPdistrict_officerverification_officerstate_admin

  Parameters of RecordEntitlementQR, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	familyDID	string	body	optional
  2	cardDID	string	body	yes
  3	cycleMonth	string	body	yes
  4	qrHash	hash64	body	yes
  5	expiresAt	string	body	yes

• GET/api/blockchain/distributions/:receiptNumberRead

  Read one distribution receipt.

  Chaincode

  DistributionContract:GetDistribution

  Signed by

  any organisation

  Parameters of GetDistribution, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	receiptNumber	string	path	yes

• GET/api/blockchain/entitlement-qrs/:cardDID/:cycleMonthRead

  Read the anchored QR for a card and cycle.

  Chaincode

  DistributionContract:GetEntitlementQR

  Signed by

  any organisation

  Parameters of GetEntitlementQR, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardDID	string	path	yes
  2	cycleMonth	string	path	yes

• GET/api/blockchain/distributions/by-card/:cardDIDRead

  A household's full collection history.

  Chaincode

  DistributionContract:QueryDistributionsByCardDID

  Signed by

  any organisation

  Parameters of QueryDistributionsByCardDID, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	cardDID	string	path	yes

• GET/api/blockchain/distributions/by-fps/:fpsIDRead

  Everything one Fair Price Shop has issued.

  Chaincode

  DistributionContract:QueryDistributionsByFPS

  Signed by

  any organisation

  Parameters of QueryDistributionsByFPS, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	fpsID	string	path	yes

AuditContract

Platform audit anchors — the record of an administrative ACTION, and the type-agnostic ledger key history reader.

• POST/api/blockchain/audit-anchorsWrite

  Anchor the digest of a platform action so its off-chain row cannot be edited undetected.

  Chaincode

  AuditContract:RecordAuditAnchor

  Signed by

  GovernanceMSP

  Parameters of RecordAuditAnchor, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	auditID	string	body	yes
  2	category	string	body	yes
  3	actorRole	string	body	yes
  4	payloadHash	hash64	body	yes

• GET/api/blockchain/audit-anchors/:auditIDRead

  Read one audit anchor.

  Chaincode

  AuditContract:GetAuditAnchor

  Signed by

  any organisation

  Parameters of GetAuditAnchor, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	auditID	string	path	yes

• GET/api/blockchain/ledger/keys/:key/historyRead

  Type-agnostic history of any ledger key — the explorer's trail reader.

  Chaincode

  AuditContract:GetHistoryForKey

  Signed by

  any organisation

  Parameters of GetHistoryForKey, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	key	string	path	yes

• GET/api/blockchain/audit-anchorsRead

  List audit anchors in one category.

  Chaincode

  AuditContract:QueryAuditAnchorsByCategory

  Signed by

  any organisation

  Parameters of QueryAuditAnchorsByCategory, in the order the chaincode receives them

  #	Name	Type	In	Required
  1	category	string	query	yes

Platform endpoints

Everything that is not a chaincode call: issuing and revoking the credentials that decide who may make one, following the chain, reading it, and the gateway’s own health. Authenticated with the same X-API-Key.