← Back to Main Documentation Core Systems Index

Plings Class System

Updated: Sat 26 Jul 2025 20:49:56 CEST - Updated to reflect global class pointer system with cryptographic verification
Document Version: 2.0 - Streamlined Class System Architecture
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, Frontend Developers, Database Architects, Product Managers
Author: Paul Wisén

1. Overview

The Plings Class System is a global hierarchical framework for defining all physical and conceptual objects within the Universal Object Graph System (UOGS). It distinguishes between an object’s blueprint (ObjectClass) and its physical manifestation (ObjectInstance). This separation allows for powerful templateing, inheritance, and tracking of individual items.

Key Innovation: Global Class Pointer System

Migration Note: The Plings class system has evolved from embedded dash-markers to a global class pointer architecture. For complete technical details, see update-class-system.md.

Core Principle: Classes are globally identified by cryptographically-derived class pointers that provide:

  • Unlimited class space: Not constrained by BIP32 wallet limits
  • Cryptographic verification: Manufacturers can’t be counterfeited
  • Offline authentication: POS systems can verify authenticity without internet
  • Global uniqueness: Class pointers are unique across all manufacturers

2. Core Concepts

ObjectClass

An ObjectClass is a template or blueprint that represents a specific product defined by a manufacturer. Each class is globally identified by one or more cryptographically-derived class pointers that prove manufacturer authenticity.

  • Examples: “IKEA BILLY Bookcase White 80x28x202cm”, “Coca-Cola Classic 355ml Can”, “Apple iPhone 15 Pro Max 256GB Blue”.
  • Global Identity: Each class has one or more 11-character class pointers (e.g., 4K7mX9abDcE) derived from SHA256(manufacturer_pubkey:path_to_pointer)
  • Verification: Class pointers provide cryptographic proof that only the manufacturer could have created this product definition
  • Key Attributes:
    • name and description: Product identification
    • version: Increments with minor updates
    • parent_class: Hierarchy link (e.g., IKEA_BILLY -> Bookcase -> Furniture)
    • manufacturer_organization_id: Links to manufacturer (enables class pointer verification)
    • class_pointers: Array of 11-character pointers identifying this class globally
    • visibility: Controls access (“public”, “private”)
    • components: Required or optional sub-objects
    • capabilities: Potential uses and functions

ObjectInstance

An ObjectInstance is a specific, physical object that exists in the real world. Each instance is based on a specific version of an ObjectClass and can be linked to that class through one of its class pointers. An ObjectInstance can exist without an identifier and can have multiple identifiers pointing to it.

  • Examples: “My IKEA BILLY bookcase #158 from batch 15”, “Coca-Cola Classic can #90000 from Atlanta plant batch 5847”.
  • Class Pointer Link: Instance is connected to its class via the class pointer used in its identifier URL
  • Key Attributes:
    • instance_of: Link to the ObjectClass that defines it
    • class_pointer: The specific 11-character class pointer used for this instance
    • statuses: Current state(s) - multiple can be active (e.g., [“for_sale”, “broken”])
    • owner: Current owner of the physical object
    • part_of: Link to another ObjectInstance it is physically part of
    • hd_path: Full HD wallet path for cryptographic derivation (e.g., “2.3.2.G.3j”)
    • solana_address: The 44-character Solana address for direct payments

PlingsIdentifier

A PlingsIdentifier is a standalone digital entity that points to a specific ObjectInstance through a cryptographically-derived URL. It contains both the HD wallet path (for hierarchy) and the class pointer (for product verification).

  • URL Format: https://s.plings.io?t=q&p={path}&cp={class_pointer}&i={solana_address}
  • Components:
    • path: HD wallet path with NO class information (e.g., “2.3.2.G.3j”)
    • class_pointer: 11-character cryptographic class identifier (e.g., “4K7mX9abDcE”)
    • solana_address: 44-character address for direct payments
  • Verification: The class pointer can be verified offline using manufacturer public keys

For detailed information about identifiers, see Plings Identifier Overview.

These classes form the backbone of the Plings application, modeling the core entities and their interactions within the universal object graph.

3. Key Design Decisions & Use Cases

Based on our discussion, the system will adhere to the following principles:

Feature Implementation
Hierarchy A formal parent-child class hierarchy is mandatory. All new classes must extend an existing class, promoting a structured graph.
Component Relations We use a ComponentRequirement subdocument. This allows a class to define what it’s made of (e.g., “requires 2 wheels of type WheelClass”).
Versioning Classes have a version number for minor updates. Significant changes (e.g., new features) result in a new ObjectClass, often inheriting from the old one.
Multi-purpose Objects An object’s potential uses are defined by a capabilities property (e.g., ["BikeLamp", "HelmetLamp"]). This avoids class duplication for different contexts.
Privacy A combination of visibility on the ObjectClass and owner properties on both classes and instances provides granular access control. Class owners define what instance owners can see.
Instance Creation When a user scans a PlingsID, they can choose which sub-components of the object to create as distinct ObjectInstances. This is to conserve data storage.
Class Updates ObjectInstances are linked to a specific class version but are aware of newer versions. The system can notify users of updates to the class definition.

Use Case: Authenticity and Counterfeit Resolution

The decoupled nature of PlingsIdentifier enables powerful verification workflows through dual identifiers and cryptographic verification.

This use case demonstrates how object classes relate to brand protection and anti-counterfeiting measures. For detailed authentication workflows and brand authority specifications, see Brand Authority Specification.

4. Example Flow: A Bicycle with Class Pointer Verification

  1. Base Class: Plings defines a high-level :ObjectClass node with name: "Bicycle".
  2. Manufacturer Class: ACME Inc. creates a new :ObjectClass node with name: "ACME Mountain Bike Model X". This node has:
    • -[:SUBCLASS_OF]-> relationship pointing to the “Bicycle” class node
    • manufacturer_organization_id linking to ACME’s organization record
    • class_pointers: ["3K7mX9abDcE"] - the cryptographic class identifier
  3. Class Pointer Generation: The class pointer 3K7mX9abDcE is generated using: 
    # ACME's path structure: 2.G.2.2 (wallet.manufacturer.category.model)
message = f"{acme_ed25519_pubkey}:2.G.2.2"
class_pointer = base58.encode(SHA256(message)[:8])  # "3K7mX9abDcE"
  4. Production: ACME manufactures 1000 bikes. For each, they create:
    • :ObjectInstance node with class_pointer: "3K7mX9abDcE"
    • :PlingsIdentifier node with path 2.G.2.2.7P.3j (batch 2024, instance 158)
    • URL: https://s.plings.io?t=q&p=2.G.2.2.7P.3j&cp=3K7mX9abDcE&i=A7Kj9mN2pQ8Rt5KdBUoD3f...
  5. Purchase & Verification: A customer scans the QR code:
    • System extracts path 2.G.2.2.7P.3j and class pointer 3K7mX9abDcE
    • Offline Verification: Uses ACME’s public key to verify class pointer authenticity
    • Product Identification: Resolves class pointer to “ACME Mountain Bike Model X”
    • Ownership Transfer: Updates owner property on the :ObjectInstance
  6. Anti-Counterfeiting: Any attempt to forge a class pointer fails because:
    • Only ACME has the private key to generate valid class pointers for path 2.G.2.2
    • POS systems can verify authenticity offline using ACME’s public key
    • Invalid class pointers are immediately detected and flagged

5. Use Case: Ownership of Aggregates (The Container Pattern)

A core challenge is tracking ownership of bulk items without creating millions of database entries (e.g., for individual cans of soda on a pallet). The system handles this through a “container pattern” that relies on a distinction between implicit and explicit ownership.

This use case demonstrates how classes enable sophisticated ownership tracking through component hierarchies. For detailed ownership intelligence and organizational management, see Organization Ownership Intelligence.

6. Use Case: Primary Components and Smart Instantiation

When a user acquires a product that contains multiple items in a box (e.g., a laptop, charger, and manual), the system must be able to distinguish the “main” item from its accessories.

This is achieved by adding an is_primary_component boolean flag to the ComponentRequirement class.

Example Flow: A Laptop Purchase with Class Pointer Verification

  1. Class Definition: A manufacturer defines an ObjectClass for their “Dell XPS 13 Laptop Bundle”:
    • Class Pointer Generation: 7K8mX9abDcE derived from SHA256(dell_pubkey:"2.9.3.4.2")[:8]
    • Path Structure: 2.9.3.4.2 (wallet.dell.electronics.laptops.xps13)
    • Components: Specifies LaptopClass with is_primary_component: true, plus ChargerClass and ManualClass as accessories
  2. Production: Dell manufactures laptop bundles with identifiers like:
    • Path: 2.9.3.4.2.Q.3C (batch Q=25, instance 3C=139)
    • Class Pointer: 7K8mX9abDcE (cryptographically links to Dell XPS 13 class)
    • URL: https://s.plings.io?t=q&p=2.9.3.4.2.Q.3C&cp=7K8mX9abDcE&i=B8kN3mQ7xRt5Kd...
  3. Acquisition & Verification: Customer scans the QR code:
    • Class Verification: System uses Dell’s public key to verify 7K8mX9abDcE is authentic
    • Product Resolution: Class pointer resolves to “Dell XPS 13 Laptop Bundle”
    • Component Discovery: System identifies this is a multi-component product
  4. Smart Prompting: Based on the verified class definition, system prompts: “Congratulations on your authentic Dell XPS 13! Would you like to create separate digital records for:”
    • ✅ Dell XPS 13 Laptop (primary component)
    • ☐ Dell 65W USB-C Charger (accessory)
    • ☐ User Manual (documentation)
  5. Component Instantiation: User selections create separate ObjectInstance nodes, each inheriting the cryptographic authenticity from the verified parent class.

7. Use Case: Rich Spatial Relationships

To accurately model where objects are in the real world, classes work together with the spatial relationship system to define how object instances relate to each other in space.

For detailed information about spatial relationships and how they interact with object classes, see Spatial Relationships System and Spatial Parent-Child Architecture.

8. Use Case: Digital Twin for Industrial Maintenance (The Hydraulic Jack)

The combination of detailed component modeling, the container pattern, and on-demand instantiation allows for powerful “digital twin” use cases, especially for complex equipment repair and lifecycle management. This moves beyond simple ownership tracking into active maintenance and facilitating a circular economy for spare parts.

Example Flow: Repairing a Hydraulic Jack with Verified Components

  1. Manufacturer’s Blueprint: Simplex creates an :ObjectClass for their hydraulic jack:
    • Class Pointer: 9G7mX9abDcE derived from SHA256(simplex_pubkey:"2.G.5.3.2")[:8]
    • Path Structure: 2.G.5.3.2 (wallet.simplex.hydraulics.jacks.model_5ton)
    • Component Classes: Defines 36 official component classes, each with their own class pointers
  2. Initial Purchase: User buys a jack with full cryptographic verification:
    • Path: 2.G.5.3.2.D.4.7ue (batch D=13, instance 4.7ue)
    • Class Pointer: 9G7mX9abDcE (cryptographically proves authentic Simplex jack)
    • URL: https://s.plings.io?t=q&p=2.G.5.3.2.D.4.7ue&cp=9G7mX9abDcE&i=7mK9Px2RtCRJcyPb...
    • Verification: System confirms authenticity using Simplex’s public key
  3. Digital Disassembly & Diagnosis: After years of use, the jack fails:
    • Owner scans jack identifier: path 2.G.5.3.2.D.4.7ue, class pointer 9G7mX9abDcE
    • Class Resolution: System verifies and resolves to “Simplex 5-Ton Hydraulic Jack”
    • Component Blueprint: Displays interactive diagram from verified Simplex class definition
    • Part Identification: Owner identifies “Piston Seal” (#24) as broken component
  4. Component Instantiation with Verification: System creates broken component:
    • New Instance: Creates :ObjectInstance for the specific broken seal
    • Component Class Pointer: 2X8mX9abDcE (Simplex Piston Seal class pointer)
    • Verification Chain: Links to verified Simplex component class definition
    • Relationships: -[:PART_OF]-> main jack, -[:INSTANCE_OF]-> SimplexPistonSeal class
    • Status: ["broken"] with ownership inherited from parent jack
  5. Verified Circular Economy: Cryptographic verification enables trust in spare parts market:
    • Authentic Parts Search: Query for SimplexPistonSeal instances with status ["for_sale"]
    • Seller Verification: Each spare part has class pointer 2X8mX9abDcE verifiable against Simplex’s public key
    • Counterfeit Protection: Fake parts cannot generate valid class pointers without Simplex’s private key
    • Compatibility Guarantee: Class pointer system ensures exact part compatibility

This workflow transforms a physical object into a dynamic digital twin, creating a foundation for a truly circular and repair-focused economy.

9. Class Database Schema

The class system is implemented using both PostgreSQL (for metadata) and Neo4j (for relationships), enhanced with class pointer support:

PostgreSQL Tables

  • object_classes: Stores class definitions, properties, and metadata
  • class_pointers: Maps 11-character class pointers to class definitions (with global uniqueness)
  • object_instances: Stores instance data with class pointer references
  • component_requirements: Defines class component relationships
  • manufacturer_registry: Ed25519 public keys for class pointer verification

Neo4j Relationships

  • [:INSTANCE_OF]: Links object instances to their classes via class pointer
  • [:SUBCLASS_OF]: Creates class inheritance hierarchy
  • [:PART_OF]: Defines component relationships between instances
  • [:VERIFIED_BY]: Links class pointers to manufacturer verification keys

Key Schema Enhancements for Class Pointers

-- New class pointer registry (global uniqueness)
CREATE TABLE class_pointers (
    id UUID PRIMARY KEY,
    class_pointer VARCHAR(15) UNIQUE NOT NULL,  -- 11-character class pointer
    class_id UUID REFERENCES object_classes(id),
    manufacturer_pubkey TEXT NOT NULL,          -- Ed25519 public key
    path_to_pointer VARCHAR(50) NOT NULL,       -- Path used for generation
    verified_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Enhanced object instances with class pointer support
ALTER TABLE object_instances 
ADD COLUMN class_pointer VARCHAR(15),
ADD COLUMN hd_path VARCHAR(100),               -- Full HD path
ADD COLUMN solana_address VARCHAR(44);         -- Direct payment address

For detailed database schema information, see Supabase Core Schema and Neo4j Core Schema.