API Reference - Orbit Ledger

OrbitLedger

The main interface for interacting with the ledger engine.

OrbitLedger.java

                            public interface OrbitLedger {
    static Builder builder();
    
    void credit(String key, long amount);
    void debit(String key, long amount);
    OrbitRelease release(String key);
    void releaseAll();
    void start();
    void shutdown();
}
                        

Methods

Method	Returns	Description
`builder()`	Builder	Creates a new builder instance
`credit(key, amount)`	void	Submit a credit event (non-blocking)
`debit(key, amount)`	void	Submit a debit event (non-blocking)
`release(key)`	OrbitRelease	Force release for a specific key (blocking)
`releaseAll()`	void	Force release all pending keys
`start()`	void	Start the engine
`shutdown()`	void	Graceful shutdown

OrbitLedger.Builder

Method	Parameter	Description
`bufferSize(int)`	Power of 2	Ring buffer capacity
`threadCount(int)`	= 1	Number of worker threads
`releaseType(ReleaseType)`	Enum	Release strategy
`releaseThreshold(int)`	= 1	Events before auto-release
`releaseInterval(Duration)`	Duration	Time between auto-releases
`onRelease(listener)`	Listener	Required. Persistence callback
`balanceLoader(loader)`	BalanceLoader	Initial balance loader
`defaultBalance(long)`	long	Default starting balance
`evictionPolicy(policy)`	EvictionPolicy	Memory management strategy
`performanceMode(mode)`	PerformanceMode	STANDARD (default) or MAXIMUM
`build()`	—	Creates the OrbitLedger instance

BalanceLoader

Functional interface for loading initial balances from your database.

BalanceLoader.java

                            @FunctionalInterface
public interface BalanceLoader {
    long load(String key);
}
                        

OrbitReleaseListener

Callback interface for handling released batches.

OrbitReleaseListener.java

                            @FunctionalInterface
public interface OrbitReleaseListener {
    void onRelease(OrbitRelease release);
}
                        

OrbitRelease

Immutable record containing a batch of events ready for persistence.

Method	Returns	Description
`key()`	String	Account/entity identifier
`delta()`	long	Net change (sum of signed amounts)
`runningBalance()`	Long	Final balance after batch
`eventCount()`	int	Number of events in batch
`events()`	List<LedgerEvent>	Immutable list of events
`durationNs()`	long	Processing time in nanoseconds

LedgerEvent

Immutable record representing a single transaction event.

Method	Returns	Description
`key()`	String	Account/entity identifier
`sequence()`	long	Monotonic sequence number
`type()`	LedgerType	CREDIT or DEBIT
`amount()`	long	Absolute amount
`timestamp()`	Instant	Event creation time
`balanceAfter()`	Long	Balance after this event

ReleaseType

Value	Description
`COUNT`	Release when event count reaches threshold
`TIME`	Release on time interval
`HYBRID`	Release on either condition (first wins)

EvictionPolicy

Value	Description
`NONE`	Keep state in memory indefinitely
`AFTER_RELEASE`	Clear state after batch release. Requires balanceLoader

PerformanceMode

Value	Description
`STANDARD`	(Default) Low CPU usage, uses thread parking. ~2.8M ops/sec.
`MAXIMUM`	Moderate CPU usage, uses thread yielding. ~4.5M ops/sec.