Vexalus — Supply Chain Intelligence

Vexalus is a supply chain tracking and attestation module built on Vexidus L1 primitives. It provides verifiable, tamper-evident shipment tracking, multi-party custody handoffs, document attestation, and invoice tokenization — without requiring any new protocol infrastructure.

Every Vexalus operation maps directly to a native Vexidus primitive. There is no new trust model to audit: the security guarantees are inherited from the underlying chain.

---

How Existing Primitives Map to Supply Chain Operations

Supply Chain Concept	Vexidus Primitive	What It Provides
Shipment identity	VSC-21 NFT	Unique, non-fungible token representing a physical shipment — ownership = custodianship
Checkpoint events	VSC-55 multi-token mint	Scoped tokens (temperature, location, condition) minted at each checkpoint — immutable log
Custody transfer	VSC-88 multi-sig proposal + execution	M-of-N approval for handoff between carrier, customs, and recipient
Document attestation	BLAKE3 hash anchored on-chain	Bill of lading, certificates of origin, inspection reports — hash stored, content off-chain
Invoice tokenization	VSC-7 fungible token	Tradeable receivable backed by on-chain shipment proof
Compliance audit	Explorer RPC queries	Full immutable history of every checkpoint, handoff, and attestation

---

SDK Overview

The Vexalus SDK wraps these primitives with domain-specific methods. Install via npm:

npm install @vexidus/vexalus-sdk

Core Methods

import { Vexalus } from '@vexidus/vexalus-sdk';

const vexalus = new Vexalus({ rpc: 'https://api.vexalus.com' });

// Create a new shipment (mints a VSC-21 NFT)
const shipment = await vexalus.createShipment({
  id: 'SHP-2026-00441',
  origin: 'Shanghai, CN',
  destination: 'Rotterdam, NL',
  cargo: 'Electronics — 240 units',
  custodian: 'Vx...',       // Initial custodian address
});

// Add a checkpoint (mints VSC-55 tokens for this event)
await vexalus.addCheckpoint({
  shipmentId: 'SHP-2026-00441',
  location: 'Port of Shanghai',
  status: 'departed',
  temperature: '18°C',
  humidity: '45%',
  agent: 'Vx...',
});

// Propose a custody handoff (VSC-88 multi-sig proposal)
await vexalus.proposeHandoff({
  shipmentId: 'SHP-2026-00441',
  from: 'Vx...',            // Current custodian
  to: 'Vx...',              // Receiving party
  requiredSigners: ['Vx...', 'Vx...'],
  threshold: 2,
});

// Attest a document (anchors BLAKE3 hash on-chain)
await vexalus.attestDocument({
  shipmentId: 'SHP-2026-00441',
  documentType: 'bill_of_lading',
  content: documentBuffer,  // Hashed client-side, only hash stored on-chain
  issuer: 'Vx...',
});

// Verify compliance status
const status = await vexalus.verifyCompliance({
  shipmentId: 'SHP-2026-00441',
  rules: ['temperature_within_range', 'no_unauthorized_handoff'],
});

// Tokenize an invoice (mints VSC-7 token)
await vexalus.tokenizeInvoice({
  shipmentId: 'SHP-2026-00441',
  amount: '48000',
  currency: 'USDC',
  paymentDue: '2026-04-15',
});

---

REST API

Base URL: https://api.vexalus.com

Endpoint	Method	Description
/v1/shipment	POST/GET	Create or retrieve a shipment
/v1/checkpoint	POST/GET	Add or list checkpoints for a shipment
/v1/custody	POST/GET	Propose, approve, or query custody handoffs
/v1/document	POST/GET	Attest or verify a document hash
/v1/finance	POST/GET	Tokenize or query invoices and receivables
/v1/audit	GET	Full audit trail for a shipment — all events in order
/v1/party	POST/GET	Register or resolve counterparty identities

Example: Retrieve a shipment audit trail

curl "https://api.vexalus.com/v1/audit?shipmentId=SHP-2026-00441"

{
  "shipmentId": "SHP-2026-00441",
  "nftId": "VSC21:0x...",
  "events": [
    { "type": "created",    "block": 1041200, "custodian": "Vx...", "location": "Shanghai, CN" },
    { "type": "checkpoint", "block": 1041387, "status": "departed", "temperature": "18°C" },
    { "type": "handoff",    "block": 1041902, "from": "Vx...", "to": "Vx...", "signers": 2 },
    { "type": "attest",     "block": 1042100, "docType": "bill_of_lading", "hash": "Vxh..." }
  ]
}

---

IoT Edge Agent

Vexalus includes a lightweight IoT agent for edge device checkpoint submission. The agent runs on any Linux device (including Raspberry Pi) and signs checkpoints with a device keypair before submitting them to the chain via Dragonfly Stream's direct-to-leader routing.

# Install and configure the agent
npm install -g @vexidus/vexalus-agent

vexalus-agent init --device-id IOT-2026-001 --keypair ./device-key.json

# Start streaming checkpoints
vexalus-agent start \
  --shipment SHP-2026-00441 \
  --interval 60 \
  --sensors temperature,humidity,gps

The agent submits signed checkpoint bundles at the configured interval. If connectivity is lost, it queues locally and flushes on reconnect.

---

Cost Model

Vexalus operations use standard Vexidus gas pricing (~10 nanoVXS per unit). A complete shipment lifecycle — creation, four checkpoints, two custody handoffs, two document attestations, and an invoice tokenization — costs approximately $0.013 at current VXS testnet pricing.

Operation	Approximate Cost
Create shipment (VSC-21 mint)	~$0.0002
Checkpoint (VSC-55 mint)	~$0.0002
Custody handoff (VSC-88 multisig)	~$0.0004
Document attestation (hash anchor)	~$0.0001
Invoice tokenization (VSC-7 mint)	~$0.0002
Complete lifecycle (10 ops)	~$0.013

---

Multi-Zone Deployment

The Vexalus data model includes a zone field on all entities (default: "earth"). This field is future-proofed for multi-zone deployments — enabling the same shipment tracking infrastructure to operate across logistically distinct domains without changes to the core protocol.

---

Key Links

Resource	URL
Vexalus App	vexalus.com
API	api.vexalus.com
Token Standards	VexForge Token Overview
Governance / Multi-sig	VSC-88 Multi-Sig Wallets