org.sigilaris.core

High-level assembly DSL for blockchain application construction.

This package provides convenient tools and DSL methods for assembling blockchain applications from modular blueprints, with compile-time validation and type-safe table access.

=Core Components=

'''org.sigilaris.core.assembly.BlueprintDsl''' - High-level mounting DSL

mount - Mount org.sigilaris.core.application.module.blueprint.ModuleBlueprint at single-segment path
mountAtPath - Mount ModuleBlueprint at multi-segment path
mountComposed - Mount org.sigilaris.core.application.module.blueprint.ComposedBlueprint at single-segment path
mountComposedAtPath - Mount ComposedBlueprint at multi-segment path
Automatic evidence requirements (PrefixFreePath, SchemaMapper, NodeStore)

'''org.sigilaris.core.assembly.EntrySyntax''' - String interpolator for Entry creation

entry"tableName"[K, V] creates Entry[Name, K, V] with compile-time literal extraction
Ensures table names are string literals (not expressions)
Preserves type-level information for schema validation

'''org.sigilaris.core.assembly.TablesProviderOps''' - Provider extraction extensions

module.toTablesProvider - Extract org.sigilaris.core.application.module.provider.TablesProvider from mounted module
Bridges gap between module mounting and dependency injection

'''org.sigilaris.core.assembly.TablesAccessOps''' - Evidence derivation utilities

deriveLookup[Schema, Name, K, V] - Derive org.sigilaris.core.application.support.compiletime.Lookup evidence
deriveRequires[Needs, Schema] - Derive org.sigilaris.core.application.support.compiletime.Requires evidence
provider.providedTable[Name, K, V] - Access table with automatic evidence derivation

'''org.sigilaris.core.assembly.PrefixFreeValidator''' - Runtime prefix validation

Validates that table prefixes are prefix-free at byte level
Useful for testing and debugging schema configurations
Operates on encoded prefixes (after length-prefix encoding)

=Usage Examples=

Attributes

See also

org.sigilaris.core.application.module for underlying module system

org.sigilaris.core.application.state for table and schema types

org.sigilaris.core.application.support.compiletime for evidence types

Example

Basic module mounting:

 import org.sigilaris.core.assembly.BlueprintDsl.*
 import org.sigilaris.core.assembly.EntrySyntax.*
 // Define schema with entry interpolator
 val accountsEntry = entry"accounts" [String, Account]
 val balancesEntry = entry"balances" [String, BigInt]
 // Create and mount blueprint
 val module = mount("accounts" -> accountsBlueprint)
 // Extract provider for dependent modules
 import org.sigilaris.core.assembly.TablesProviderOps.*
 val provider = module.toTablesProvider

Multi-segment path mounting:

 import org.sigilaris.core.assembly.BlueprintDsl.*
 // Mount at nested path
 val module = mountAtPath(("app", "v1", "accounts") -> blueprint)

Composed blueprint mounting:

 import org.sigilaris.core.assembly.BlueprintDsl.*
 import org.sigilaris.core.application.module.blueprint.Blueprint
 // Compose two blueprints
 val composed = Blueprint.composeBlueprint[IO, "app"](
   accountsBlueprint,
   balancesBlueprint,
 )
 // Mount composed blueprint (requires ModuleRoutedTx)
 val module = mountComposed("myapp" -> composed)

Evidence derivation:

 import org.sigilaris.core.assembly.TablesAccessOps.*
 // Derive Lookup evidence without explicit summon
 val lookup = deriveLookup[MySchema, "accounts", String, Account]
 val table  = lookup.table(tables)
 // Or use extension method for direct access
 val accountsTable = provider.providedTable["accounts", String, Account]

Prefix validation (testing):

 import org.sigilaris.core.assembly.PrefixFreeValidator
 // Validate at compile-time
 val result =
   PrefixFreeValidator.validateSchema["app" *: EmptyTuple, MySchema]
 assert(result == PrefixFreeValidator.Valid)
 // Validate at runtime with names for debugging
 val prefixes = List(
   ("accounts", tablePrefix["app" *: EmptyTuple, "accounts"]),
   ("balances", tablePrefix["app" *: EmptyTuple, "balances"]),
 )
 val result2 = PrefixFreeValidator.validateWithNames(prefixes)

=Design Principles= '''Type Safety:'''

All evidence requirements checked at compile-time
String literals enforced for table names (via macro)
Automatic derivation where possible '''Ergonomics:'''
Concise syntax for common operations
Extension methods for natural API
Import-based feature activation '''Composability:'''
DSL methods compose naturally
Provider extraction enables dependency injection
Evidence derivation reduces boilerplate =Integration with Module System= The assembly package is the recommended entry point for application construction:
Define schemas using org.sigilaris.core.assembly.EntrySyntax
Create blueprints using org.sigilaris.core.application.module.blueprint
Mount blueprints using org.sigilaris.core.assembly.BlueprintDsl
Extract providers using org.sigilaris.core.assembly.TablesProviderOps
Wire dependencies and compose modules

Core data types with specialized encoding and type safety.

This package provides opaque types for common data structures used throughout Sigilaris, each with carefully designed byte and JSON codecs. All types are zero-cost abstractions that provide compile-time safety without runtime overhead.

=Available Types=

'''BigNat''' - Non-negative arbitrary-precision integers

Refined BigInt constrained to values ≥ 0
Safe arithmetic operations (addition, multiplication, division)
Checked subtraction via Either for negative results
Variable-length byte encoding
JSON string encoding by default

'''UInt256''' - 256-bit unsigned integers

Fixed 32-byte big-endian representation
Range: [0, 2^256 - 1]
Construction from bytes, BigInt, or hex strings
Type-safe failures via org.sigilaris.core.failure.UInt256Failure
JSON hex string encoding (lowercase, no 0x prefix)

'''Utf8''' - UTF-8 encoded strings

Length-prefixed byte encoding: [size: BigNat][UTF-8 bytes]
Automatic UTF-8 validation during decoding
JSON string encoding (delegates to String)
JSON key codec support for Map keys

=Common Features=

All types in this package provide:

Cats Eq instances for type-safe equality
ByteEncoder and ByteDecoder for binary serialization
JsonEncoder and JsonDecoder for JSON serialization
Opaque type wrappers for zero-cost abstraction

=Usage Examples=

Attributes

See also

org.sigilaris.core.codec.byte for byte codec details

org.sigilaris.core.codec.json for JSON codec details

org.sigilaris.core.failure for typed failure cases

Example

 import org.sigilaris.core.datatype.*
 import org.sigilaris.core.codec.byte.ByteEncoder
 import org.sigilaris.core.codec.json.JsonEncoder
 // BigNat - natural numbers
 val n1   = BigNat.unsafeFromLong(42)
 val n2   = BigNat.unsafeFromLong(10)
 val sum  = BigNat.add(n1, n2)           // 52
 val diff = BigNat.tryToSubtract(n1, n2) // Right(32)
 // UInt256 - fixed-size unsigned integers
 val u1  = UInt256.fromHex("ff").toOption.get
 val u2  = UInt256.fromBigIntUnsigned(BigInt(255)).toOption.get
 val hex = u1.toHexLower
 // Utf8 - length-prefixed strings
 val text  = Utf8("Hello, 世界!")
 val bytes = ByteEncoder[Utf8].encode(text)
 val json  = JsonEncoder[Utf8].encode(text)

=Encoding Formats= '''Byte Encoding:'''

BigNat: Variable-length (implementation-defined)
UInt256: Fixed 32 bytes, big-endian
Utf8: [size: BigNat][UTF-8 bytes] '''JSON Encoding:'''
BigNat: String by default (configurable via org.sigilaris.core.codec.json.JsonConfig)
UInt256: Lowercase hex string without 0x prefix
Utf8: Plain JSON string

org.sigilaris.core

Members list

Packages

Attributes

Attributes