Stream processing instructions in CESR that provide more general and flexible operations than simple concatenation of primitives or primitive groups, designed to enable a future stack-based virtual machine for executing operations on CESR streams.
Related Concepts
No related concepts available
Comprehensive Explanation
opcode
Structure Definition
Opcodes in the CESR (Composable Event Streaming Representation) protocol are specialized stream processing instructions that extend CESR's capabilities beyond the basic concatenation model of primitives and primitive groups. Unlike standard CESR primitives that encode cryptographic material (keys, signatures, digests) or count codes that frame groups of primitives, opcodes represent a higher-level abstraction designed to provide programmable control flow within CESR streams.
The fundamental purpose of opcodes is to enable more general and flexible stream processing than what can be achieved through simple concatenation. While CESR's core design focuses on composability - the ability to convert concatenated primitives between text and binary domains without loss - opcodes introduce the concept of executable instructions that can operate on primitives, primitive groups, or entire stream segments.
Opcodes are positioned as a future extension to CESR rather than a currently implemented feature. The specification documents consistently describe opcodes as supporting a "stack-based virtual machine (yet to be determined)" that would execute these instructions. This indicates that while the conceptual framework exists, the detailed instruction set architecture, execution model, and specific opcode definitions remain to be fully specified.
Reserved Selector Character
The CESR specification reserves the '_' (underscore) selector character for future opcode table definitions. In CESR's code table architecture, the first character of a primitive's text representation serves as a selector that determines which code table to use for parsing. By reserving specifically for opcodes, the specification ensures that:
Implementation Notes
Current Implementation Status
Opcodes are NOT currently implemented in CESR. All source documentation consistently describes opcodes as a future extension with the following characteristics:
The '_' (underscore) selector character is reserved for opcode tables
The stack-based virtual machine is described as "yet to be determined"
No specific opcode definitions, instruction sets, or execution models are provided
This is a planned capability rather than an operational feature
Implementation Guidance for Future Development
1. Maintain CESR Core Properties
Any opcode implementation MUST preserve CESR's fundamental properties:
Composability:
Opcodes must align on 24-bit boundaries (4 characters text / 3 bytes binary)
Round-trip conversion between text and binary domains must be lossless
Concatenated streams containing opcodes must maintain separable parseability
Self-Framing:
Each opcode must contain sufficient information to determine its length
Parsers must be able to extract opcodes without external context
The '_' selector must unambiguously identify opcode primitives
2. Virtual Machine Architecture Considerations
Stack-Based Design:
Define maximum stack depth to prevent overflow attacks
Specify stack element types (primitives, intermediate results, etc.)
Establish clear push/pop semantics for each opcode
Define error handling for stack underflow conditions
Execution Model:
Determine whether execution is synchronous or asynchronous
Define state management between opcode executions
Specify memory limits and resource constraints
Establish security boundaries and sandboxing requirements
3. Opcode Table Design
Opcode Identifier Allocation:
Reserve sufficient identifier space for future expansion
Use systematic naming conventions for opcode families
Consider versioning mechanisms for opcode table evolution
Define deprecation policies for obsolete opcodes
Parameter Encoding:
'_'
Opcode primitives will be immediately distinguishable from other CESR primitives
The opcode namespace is protected from collision with existing primitive types
Future opcode table definitions can be added without breaking existing CESR implementations
Multiple opcode tables could potentially be defined using sub-selectors
Architectural Role
Opcodes represent a shift from CESR's declarative data encoding model to a more imperative programming model. While standard CESR primitives declare "this is a signature" or "this is a digest," opcodes would declare "perform this operation." This architectural distinction positions opcodes as:
Control flow instructions: Directing how streams should be processed
Transformation operators: Modifying or combining primitives
Conditional logic: Enabling branching based on stream content
Stack manipulation: Managing a virtual machine's execution state
The stack-based virtual machine model suggests that opcodes would operate on a conceptual stack where primitives and intermediate results are pushed and popped during stream processing. This is a common architecture in bytecode interpreters and would provide a clean execution model for CESR stream operations.
Data Format
Encoding Structure
While specific opcode formats are not yet defined in the available documentation, we can infer the likely structure based on CESR's design principles and the reserved '_' selector:
Text Domain Representation:
_XXX...
Where:
_ = Opcode selector character (reserved)
XXX... = Opcode-specific encoding following CESR alignment rules
Binary Domain Representation:
The binary equivalent would follow CESR's standard transformation rules, maintaining the 24-bit alignment constraint that ensures composability between text and binary domains.
Alignment Requirements
Like all CESR primitives, opcodes must conform to the 24-bit boundary alignment requirement:
Text domain: Integer multiples of 4 Base64 characters (24 bits)
Binary domain: Integer multiples of 3 bytes (24 bits)
This ensures opcodes can be concatenated with other primitives and maintain round-trip conversion properties
The 24-bit alignment is fundamental to CESR's composability property, which states that:
T(cat(b[k])) = cat(T(b[k])) for all k
B(cat(t[k])) = cat(B(t[k])) for all k
Opcodes must preserve this property to remain compatible with CESR's stream processing model.
Potential Opcode Classes
Based on the stated purpose of providing "primitive processing instructions, primitive group processing instructions, or stream processing instructions," we can anticipate three classes of opcodes:
1. Primitive-Level Opcodes:
Operations on individual cryptographic primitives
Examples might include: verify signature, compute digest, extract public key
Would provide high-level control flow capabilities
Size and Constraints
The minimum opcode size would be 4 characters in text domain (1 character for '_' selector + 3 characters for opcode specification) or 3 bytes in binary domain, maintaining the 24-bit alignment. Larger opcodes would scale in multiples of 4 characters (text) or 3 bytes (binary).
The actual size of specific opcodes would depend on:
Opcode identifier: How many distinct operations need to be encoded
Operand encoding: Whether opcodes include inline operands or reference stack positions
Parameter data: Any additional data required for the operation
Operations
Creation and Initialization
While specific opcode creation mechanisms are not yet defined, the general CESR primitive creation pattern would apply:
1. Opcode Selection:
Choose the appropriate opcode for the desired operation
Determine required operands or parameters
2. Encoding:
Apply CESR encoding rules with '_' selector
Ensure 24-bit alignment through appropriate padding
Generate both text and binary representations
3. Stream Insertion:
Insert opcode at appropriate position in CESR stream
The proposed stack-based virtual machine would execute opcodes through:
1. Stream Parsing:
Parse CESR stream sequentially
Identify opcodes via '_' selector
Extract opcode type and parameters
2. Stack Operations:
Push primitives onto execution stack
Execute opcodes that pop operands and push results
Maintain stack state across operations
3. Result Generation:
Produce output primitives or modified streams
Maintain CESR encoding for all results
Preserve composability for downstream processing
Verification and Validation
Opcode validation would involve:
Syntactic Validation:
Verify '_' selector presence
Confirm 24-bit alignment
Validate opcode identifier against defined opcode table
Check parameter encoding correctness
Semantic Validation:
Verify sufficient operands on stack
Validate operand types match opcode requirements
Ensure operation is permitted in current context
Check for stack overflow/underflow conditions
Execution Validation:
Verify cryptographic operations succeed
Validate threshold conditions are met
Ensure output primitives are properly formed
Confirm stream integrity is maintained
Usage Context
Integration with CESR Protocol Stack
Opcodes are designed to enhance the CESR encoding layer that underlies the KERI/ACDC/SPAC-TSP protocol stack. Their primary usage contexts would include:
SPAC-TSP Protocol:
In SPAC (Secure Private Authentic Confidentiality) and TSP (Trust Spanning Protocol), opcodes could provide:
Confidentiality operation encoding
Privacy-preserving transformations
Authentication protocol steps
Trust establishment logic
Implementation Considerations
Current Status
It is critical to understand that opcodes are not currently implemented in CESR. All source documents consistently describe opcodes as:
"Yet to be determined"
"Future extension"
"Planned capability"
Reserved via the '_' selector but not specified
This means:
No opcode tables currently exist
No virtual machine implementation is available
No specific opcode definitions are standardized
The feature is conceptual rather than operational
Design Philosophy
The opcode concept aligns with CESR's broader design philosophy of:
Composability:
Opcodes must maintain CESR's fundamental composability property, ensuring that streams containing opcodes can be converted between text and binary domains without loss.
Self-Framing:
Opcodes must be self-framing, containing all information needed to parse them without external context.
Extensibility:
The reserved '_' selector provides a clean extension point for adding programmable capabilities without breaking existing CESR implementations.
Minimalism:
Consistent with CESR's "minimally sufficient means" philosophy, opcodes should provide only essential operations, avoiding feature bloat.
Future Development
When opcodes are fully specified, the development process will likely involve:
1. Opcode Table Definition:
Enumerate specific operations to be supported
Assign unique identifiers to each opcode
Define parameter encoding schemes
Specify operand types and stack effects
2. Virtual Machine Specification:
Define stack architecture and size limits
Specify execution model and state management
Define error handling and exception mechanisms
Establish security boundaries and sandboxing
3. Implementation Guidelines:
Provide reference implementations in multiple languages
Define test vectors for opcode operations
Establish performance benchmarks
Create security audit requirements
4. Protocol Integration:
Define how opcodes integrate with KERI/ACDC/SPAC-TSP
Specify protocol-specific opcode usage patterns
Establish versioning and compatibility rules
Define migration paths for existing implementations
The opcode concept represents a significant potential evolution of CESR from a pure encoding format to a programmable stream processing framework, enabling more sophisticated protocol operations while maintaining CESR's core properties of composability, efficiency, and verifiability.
Specify how opcodes encode inline parameters
Define whether parameters are stack-based or inline
Establish type system for opcode operands
Consider variable-length parameter support
4. Integration with Existing CESR
Backward Compatibility:
Existing CESR implementations must be able to skip/ignore opcodes if not supported
Opcode-aware parsers must handle streams with and without opcodes
Define graceful degradation strategies for unsupported opcodes
Protocol Layer Integration:
Define how KERI/ACDC/SPAC-TSP protocols utilize opcodes
Specify protocol-specific opcode usage patterns
Establish security policies for opcode execution in different contexts