Plings Path Registry System

Created: Thu Jul 10 21:47:22 CEST 2025
Last Updated: Thu 24 Jul 2025 08:11:36 CEST
Architecture Version: 3.0 - Business-Focused Design
Document Version: 2.1 - Updated path structure, added wallet prefix, improved examples
Security Classification: Public Technical Documentation
Target Audience: Manufacturers, Integrators, Business Partners, Developers
Author: Paul Wisén

Overview

The Plings Path Registry System is the foundation for globally unique object identification in the Plings ecosystem. It provides a hierarchical namespace system that enables manufacturers to organize and track their physical products while maintaining collision-free identification across the entire network.

HD Wallet Architecture

Plings uses HD (Hierarchical Deterministic) Wallet technology instead of traditional PKI (Public Key Infrastructure) for two critical business capabilities:

Payment Integration: Each identifier maps to a Program Derived Address (PDA) on Solana blockchain, enabling direct payments to objects without manufacturers controlling the funds (e.g., parking meters, vending machines, IoT devices)
Manufacturing Control: Manufacturers can delegate specific path ranges to subcontractors or plants, controlling exactly which objects and batches they can create without compromising security

For detailed technical implementation, see Plings Identifier Overview.

Core Purpose

The path registry serves as a universal addressing system for physical objects, similar to how domain names work for websites. Each path uniquely identifies a specific object or batch of objects, enabling:

Global Object Identification: Every physical object gets a unique, scannable identifier
Manufacturer Autonomy: Organizations control their own namespace
Hierarchical Organization: Products organized by category, class, and batch
Supply Chain Integration: Seamless tracking across ownership changes
Point-of-Sale Efficiency: Class pointers enable rapid product identification with cryptographic verification

Path Structure and Format

Anatomy of a Plings Path

Migration Note: The path structure uses class pointers for product classification. For details, see update-class-system.md.

Every Plings path follows a hierarchical format:

manufacturer.category.hierarchy.batch.instance

Example Path: 2.3.2.G.3j Class Pointer: 4K7mX9abDcE (derived separately)

Breaking this down:

2 = Wallet version identifier (base58 encoded: 1)
3 = Manufacturer ID (base58 encoded: 2, e.g., IKEA)
2 = Category (base58 encoded: 1, e.g., Furniture)
G = Batch number (base58 encoded: 15)
3j = Individual instance number (base58 encoded: 158)
Class is identified separately via cryptographic pointer: 4K7mX9abDcE

Real-World Path Examples

Consumer Electronics (Apple)

Path: 2.9.3.4.2.Q.6.3C
Class Pointer: 2Ld4KxmNpQ7

2 = Wallet v1 (base58)
9 = Apple Inc. (base58: 8)
3.4.2 = Electronics → Mobile Devices → Phones (base58: 2,3,1)
Q.6 = Batch → USA California Facility 5 (base58: 23,5)
3C = Instance (base58: 127)
Class: iPhone 15 Pro Max 256GB Natural Titanium (Pointer: 2Ld4KxmNpQ7)

Automotive Parts (Bosch)

Path: 2.G.5.3.2.D.4.7ue
Class Pointer: jj9QmRxPtK8

2 = Wallet v1 (base58)
G = Bosch (base58: 15)
5.3.2 = Automotive → Sensors → Oxygen Sensors (base58: 4,2,1)
D.4 = Batch 12, Line 3 (base58: 12,3)
7ue = Instance 451 (base58: 451)
Class: Lambda Sensor LSU 4.9 Part #0258017025 (Pointer: jj9QmRxPtK8)

Fashion Retail (H&M)

Path: 2.Q.2.4.3.rn.cBP
Class Pointer: 3dS8KxmNpQ2

2 = Wallet v1 (base58)
Q = H&M (base58: 23)
2.4.3 = Clothing → Women → Dresses (base58: 1,3,2)
rn = Batch (base58: 48)
cBP = Instance (base58: 2910)
Class: Floral Midi Dress Size M Art. 1158607 (Pointer: 3dS8KxmNpQ2)

Pharmaceutical (Pfizer)

Path: 2.2m.4.2.5.3.8.3.3j.jj
Class Pointer: 2rt5KqL9mXw

2 = Wallet v1 (base58)
2m = Pfizer (base58: 91)
4.2.5.3 = Pharma → Vaccines → COVID-19 → Bivalent (base58: 3,1,4,2)
-2rt = Comirnaty Bivalent BA.4/BA.5 (base58: 5501)
8.3 = Belgium → Brussels Plant (base58: 7,2)
3j = Batch (base58: 156)
jj = Instance (base58: 892)

HD Wallet Structural Limits

The Plings path system is constrained only by the BIP32 HD (Hierarchical Deterministic) wallet specification:

BIP32 Technical Constraints

HD Wallet Index Range: Each path component uses BIP32 32-bit indices
Hardened Derivation: 0 to 2^31-1 (2,147,483,647) - about 2.1 billion addresses
Non-hardened Derivation: 0 to 2^32-1 (4,294,967,295) - about 4.3 billion addresses
Base58 Efficiency: Encodes large numbers efficiently for QR codes

Maximum BIP32 Limits

Component	Derivation Type	Max Decimal	Max Base58	Notes
Wallet Version	Hardened	2,147,483,647	`YcVfxz`	~2.1 billion versions
Manufacturer ID	Hardened	2,147,483,647	`YcVfxz`	~2.1 billion manufacturers
Category Segments	Non-hardened	4,294,967,295	`7YXq9G`	~4.3 billion per level
Batch Numbers	Non-hardened	4,294,967,295	`7YXq9G`	~4.3 billion batches
Instance Numbers	Non-hardened	4,294,967,295	`7YXq9G`	~4.3 billion per batch
Class Pointers	External	Unlimited	11 chars	Generated cryptographically

Practical Considerations

While BIP32 allows massive scale, practical QR code considerations suggest:

Path Length: Shorter paths create smaller, more scannable QR codes
Base58 Encoding: Automatically optimizes for compactness
No Artificial Limits: Plings doesn’t enforce arbitrary restrictions beyond BIP32

Path Structure Flexibility

The Plings path system provides flexibility while maintaining core requirements:

Fixed Components (Always Required):

Wallet Version - First position
Manufacturer ID - Second position
Class Pointer - Separate 11-character cryptographic class identifier
Batch - Second to last position
Instance - Last position

Flexible Components (Manufacturer-Defined):

Category Tree - Between manufacturer and class (depth varies)
Production Hierarchy - Between class and batch (optional)

Component Specifications

1. Wallet Version (Required - Position 1)

Format: Numeric (currently 1, Base58: 2)
Purpose: HD wallet version for key derivation
Range: 0 to 2,147,483,647 (BIP32 hardened limit)
Details: See Wallet Management Architecture

2. Manufacturer ID (Required - Position 2)

Format: Numeric, Base58 encoded
Range: 0 to 2,147,483,647 (BIP32 hardened limit)
Assignment: Centrally managed by Plings
Purpose: Top-level namespace isolation
Examples:
- 1 (decimal) → 2 (Base58): Plings
- 2 (decimal) → 3 (Base58): IKEA
- 42 (decimal) → rn (Base58): Example Corp
- 999 (decimal) → 7C (Base58): Large manufacturer
- 1,000,000 (decimal) → 4c93 (Base58): Very large ID

3. Category Tree (Flexible)

Format: Numeric segments, Base58 encoded
Range: 0 to 4,294,967,295 per segment (BIP32 non-hardened limit)
Depth: Unlimited (constrained only by practical QR code considerations)
Assignment: Manufacturer-controlled
Purpose: Product hierarchy organization
Examples:
- Simple: 1 (decimal) → 2 (Base58): Furniture
- Complex: 3.5.1 (decimal) → 4.6.2 (Base58): Vehicles → Cars → Electric
- Very large: 1000000.500000.1 (decimal) → 4c93.2w2h.2 (Base58)

4. Production Hierarchy (Optional)

Format: Base58 encoded numeric segments
Range: 0 to 4,294,967,295 per segment (BIP32 non-hardened limit)
Assignment: Manufacturer-controlled
Purpose: Track production location/line
Examples:
- rn.6.3 (decimal: 46,5,2): Country → Region → Plant
- L2 (decimal: L1): Production Line 1
- 4c93.2w2h (decimal: 1000000,500000): Large facility numbers

5. Batch (Required - Second to Last)

Format: Base58 encoded numeric (no padding)
Range: 0 to 4,294,967,295 (BIP32 non-hardened limit)
Assignment: Sequential, manufacturer-controlled
Purpose: Production run grouping
Examples:
- 2 (decimal: 1): First batch
- G (decimal: 15): Batch 15
- 4G (decimal: 237): Batch 237
- 5Q (decimal: 5847): Large batch number
- 3dU (decimal: 11,316,495): Very large batch
Note: Batch metadata stored in database

6. Instance (Required - Last Position)

Format: Base58 encoded numeric (no padding)
Range: 0 to 4,294,967,295 (BIP32 non-hardened limit)
Assignment: Sequential within batch
Purpose: Individual object identification
Examples:
- 2 (decimal: 1): First instance
- 3j (decimal: 158): Instance 158
- 3L8z (decimal: 99999): Large batch instance
- 3dU (decimal: 11,316,495): Very large instance number

Why Class Pointers?

Migration Note: Class pointers provide cryptographic verification and unlimited class space. See update-class-system.md.

The separate class pointer (4K7mX9abDcE in our example) serves critical business functions:

Point-of-Sale Integration: POS systems can map class pointers to SKUs, prices, and product details offline
- Example: 4K7mX9abDcE → “BILLY Bookcase White 80x28x202cm”, SKU 00263850, €59.99
- POS stores class mappings locally, no internet lookup required during checkout
- Cryptographic verification prevents counterfeit products
- Enables GS1 barcode compatibility and price updates
Inventory Management: Quick categorization for stock systems
- Class pointers group identical products regardless of batch/instance
- Simplifies stock counting and reordering
- Unlimited class space (not constrained by BIP32 limits)
Loss Prevention: Security systems recognize high-value classes
- Configure alarms for specific class ranges
- Track high-theft items by class
- Cryptographic verification prevents spoofing
Customer Service: Staff immediately know exact product variant
- Class identifies specific SKU, not just product category
- Enables accurate replacement and warranty handling
- Offline verification of product authenticity
Warranty Processing: Service centers identify covered products
- Class pointer links to warranty terms
- Cryptographic proof of manufacturer authorization
- Automatic warranty period calculation

URL Format and Object Access

Standard URL Structure

https://s.plings.io?t=q&p=<path>&cp=<class_pointer>&i=<solana_address>

Example:

https://s.plings.io?t=q&p=2.3.2.G.3j&cp=4K7mX9abDcE&i=A7Kj9mN2pQ8Rt5KdBUoD3fCRJcyPbTWTBf2n8Z4Vt9u2K7s

Parameters:

t=q: Tag type (QR code)
p=<path>: Object path (class information via separate class pointer)
cp=<class_pointer>: 11-character cryptographic class pointer
i=<solana_address>: 44-character Solana address for payments

URL Usage Scenarios

Product Labels: QR codes on physical products
Digital Receipts: Clickable links in purchase confirmations
Service Records: Maintenance history access
Ownership Transfer: Sharing object access
API Integration: Programmatic object lookup

Manufacturer Registration and Management

Becoming a Plings Manufacturer

Organizations can register to receive their own manufacturer ID and begin creating product identifiers:

Application Process
- Submit organization details
- Specify expected product volume
- Define initial product categories
- Accept terms of service
Manufacturer ID Assignment
- Unique numeric ID (2-999)
- Permanent assignment
- Cannot be transferred or reused
Initial Setup
- Define product categories
- Define class pointers
- Plan batch strategies
- Configure API access

Managing Your Namespace

Once registered, manufacturers have full control over their namespace:

Your Manufacturer ID: 42 (base58: rn)
Your namespace: rn.*.*.*.*

Examples of paths you can create:
- 2.rn.2.2.2 (First product) + class pointer 4K7mX9abDcE
- 2.rn.2.2.3 (Second product) + class pointer 4K7mX9abDcE
- 2.rn.3.2.2 (Different category) + class pointer 3K7mX9abDcE
- 2.rn.2.3.2 (Next batch) + class pointer 4K7mX9abDcE

Best Practices for Path Organization

Category Planning
- Group related products
- Plan for future expansion
- Consider supply chain needs
- Maintain consistent numbering
Class Pointer Strategy
- Define cryptographic class pointers for each product
- Document class definitions for team reference
- Share class pointers with retail partners for POS integration
- Consider 11-character pointer format for QR code efficiency
Batch Management
- Use sequential numbers (1, 2, 3…)
- Store batch metadata (date, location, etc.) in database
- Reserve ranges for special editions
- Plan for product lifecycle
- Enable easy recall identification

Path Allocation Process

How Path Allocation Works

Request Allocation

POST /api/allocate-path
{
  "manufacturer_name": "IKEA",
  "category": 1,
  "class_pointer": "4K7mX9abDcE",
  "batch": 15,
  "quantity": 1000,
  "purpose": "Mountain bike production Q1 2024"
}

System Validation
- Verify manufacturer authorization
- Check namespace ownership
- Ensure no collisions
- Validate quantity limits
Path Generation
- Reserve instance number range
- Generate cryptographic keys
- Create database records
- Return allocation confirmation
Identifier Creation
- Generate QR codes
- Create NFC data
- Produce label files
- Enable API access

Allocation Limits and Quotas

Tier	Daily Limit	Batch Size	API Rate
Starter	1,000	100	10/min
Business	10,000	1,000	100/min
Enterprise	100,000	10,000	1000/min
Custom	Negotiated	Unlimited	Custom

Use Cases and Possibilities

1. Retail and E-commerce

Scenario: A furniture retailer uses Plings paths for inventory and sales

At Manufacturing: Each item tagged with path-based QR code
In Warehouse: Scan to update location and status
In Store: Staff scan to check stock and specifications
At POS: Automatic warranty registration on purchase
Post-Sale: Customer accesses assembly instructions and support

→ Detailed Retail Use Case

2. Supply Chain Tracking

Scenario: Tracking products through complex supply chains

Component Tracking: Sub-assemblies with linked paths
Logistics: Real-time location updates
Customs: Instant documentation access
Quality Control: Defect tracking by batch
Recalls: Precise affected product identification

→ Detailed Supply Chain Use Case

3. Circular Economy

Scenario: Enabling product reuse and recycling

Resale Markets: Authentic product verification
Repair Services: Access to service manuals
Recycling: Material composition data
Take-back Programs: Automated return processing
Sustainability Reporting: Lifecycle tracking

→ Detailed Circular Economy Use Case

4. Service and Maintenance

Scenario: Managing product service lifecycles

Warranty Claims: Instant validation
Service History: Complete maintenance records
Parts Ordering: Exact component identification
Technician Access: Repair procedures and diagrams
Predictive Maintenance: Usage-based service alerts

→ Detailed Service Use Case

Integration Guide

Primary API - GraphQL

The Plings API is GraphQL-first, providing flexible queries and efficient data fetching:

# Allocate new paths
mutation AllocatePaths {
  allocatePaths(input: {
    category: 1
    classPointer: "4K7mX9abDcE"
    batch: 15
    quantity: 100
    metadata: {
      productName: "BILLY Bookcase White"
      manufacturingDate: "2024-01-15"
    }
  }) {
    paths {
      fullPath
      instanceKey
      qrCodeUrl
    }
    allocation {
      id
      status
      createdAt
    }
  }
}

# Query path information
query VerifyPath {
  verifyPath(path: "2.3.2.G.3j", classPointer: "4K7mX9abDcE") {
    valid
    owner {
      name
      email
    }
    product {
      name
      sku
      warranty
    }
    history {
      scans
      transfers
    }
  }
}

REST API Endpoints (Limited Use Cases)

REST endpoints are available for specific scenarios where GraphQL is impractical:

Path Verification (IoT/Embedded Devices)

GET /api/v1/rest/verify?path=2.3.2.G.3j&class_pointer=4K7mX9abDcE
Authorization: Bearer <your-api-token>

Response: 200 OK
{
  "valid": true,
  "owner": "user@example.com",
  "class": "-4"
}

Use REST for:

Hardware devices (POS terminals, IoT sensors)
Simple path verification
Webhook receivers
Legacy system integration
CDN/edge caching scenarios

Use GraphQL for:

Complex queries
Mobile/web applications
Bulk operations
Real-time subscriptions
Flexible data requirements

SDK Examples

JavaScript/TypeScript:

import { PlingsSDK } from '@plings/sdk';

const plings = new PlingsSDK({ apiKey: 'your-api-key' });

// Allocate new paths
const allocation = await plings.paths.allocate({
  category: 1,
  class: 3,
  batch: 2024,
  quantity: 100
});

// Generate QR codes
const qrCodes = await plings.identifiers.generateQR(allocation.paths);

Python:

from plings import PlingsClient

client = PlingsClient(api_key='your-api-key')

# Allocate paths
allocation = client.paths.allocate(
    category=1,
    class_pointer="4K7mX9abDcE",
    batch=15,
    quantity=100
)

# Create printable labels
labels = client.identifiers.create_labels(
    paths=allocation['paths'],
    format='pdf',
    size='50x30mm'
)

Limitations and Considerations

Technical Constraints

Path Length
- Maximum: 30 characters (shorter due to base58 encoding)
- Recommended: Keep under 20 for QR code efficiency
Character Set
- Base58: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
- Separator: . (period)
- Class prefix: - (dash)
- No other special characters or spaces
Allocation Limits
- Maximum batch size: 100,000 per request
- Daily limits based on subscription tier
- Rate limiting on API endpoints

Business Considerations

Path Permanence
- Paths cannot be deleted once allocated
- Plan allocation strategy carefully
- Consider future product lines
Namespace Management
- Manufacturer IDs are permanent
- Cannot transfer between organizations
- Mergers require special handling
International Usage
- Paths are globally unique
- Consider regional batch strategies
- Plan for multi-market products

Performance Guidelines

Batch Operations
- Allocate in batches for efficiency
- Use bulk APIs for queries
- Cache frequently accessed paths
QR Code Optimization
- Shorter paths = smaller QR codes
- Test scanning distances
- Consider label placement

Security and Compliance

Path Security Model

Allocation Security
- API authentication required
- Manufacturer isolation enforced
- Audit trail for all operations
Access Control
- Public read for basic info
- Authenticated write operations
- Owner-controlled privacy settings
Compliance Features
- GDPR-compliant data handling
- Regional data residency options
- Audit logs for compliance reporting

→ Detailed Security Documentation

Getting Started Checklist

Apply for manufacturer registration
Receive manufacturer ID assignment
Plan category and class structure
Set up API authentication
Design batch numbering strategy
Allocate test paths
Integrate QR/NFC generation
Test end-to-end workflow
Launch production allocation

Support and Resources

Documentation

Technical Support

Email: developers@plings.io
Slack: plings-community.slack.com
Forum: forum.plings.io

Business Support

Manufacturer Onboarding: onboarding@plings.io
Enterprise Solutions: enterprise@plings.io
Partnership Inquiries: partners@plings.io

For implementation details and technical architecture:

Wallet Management Architecture - Technical implementation of path storage
Database Schema - Path registry data models
API Documentation - Complete API reference

Last Updated: Thu 24 Jul 2025 14:40:01 CEST - Updated path format to use base58 encoding with separate class pointers for efficient QR codes

Search Results: