Documentation
¶
Index ¶
- type Client
- func (c *Client) Close() error
- func (c *Client) Done() <-chan struct{}
- func (c *Client) Get(query *ledger.Query) ([]ledger.Value, error)
- func (c *Client) GetSingleValue(query *ledger.QuerySingleValue) (ledger.Value, error)
- func (c *Client) HasState(state ledger.State) (bool, error)
- func (c *Client) InitialState() ledger.State
- func (c *Client) Prove(query *ledger.Query) (ledger.Proof, error)
- func (c *Client) Ready() <-chan struct{}
- func (c *Client) Set(update *ledger.Update) (ledger.State, *ledger.TrieUpdate, error)
- func (c *Client) StateByIndex(index int) (ledger.State, error)
- func (c *Client) StateCount() int
- type ClientOption
- type InfoService
- type PayloadlessClient
- func (c *PayloadlessClient) Close() error
- func (c *PayloadlessClient) Done() <-chan struct{}
- func (c *PayloadlessClient) GetLeafHashes(query *ledger.Query) ([]*hash.Hash, error)
- func (c *PayloadlessClient) GetSingleLeafHash(query *ledger.QuerySingleValue) (*hash.Hash, error)
- func (c *PayloadlessClient) HasPaths(query *ledger.Query) ([]bool, error)
- func (c *PayloadlessClient) HasState(state ledger.State) (bool, error)
- func (c *PayloadlessClient) InitialState() ledger.State
- func (c *PayloadlessClient) Prove(query *ledger.Query) (*ledger.PayloadlessTrieBatchProof, error)
- func (c *PayloadlessClient) Ready() <-chan struct{}
- func (c *PayloadlessClient) Set(update *ledger.Update) (ledger.State, *ledger.TrieUpdate, error)
- type PayloadlessService
- func (s *PayloadlessService) GetLeafHashes(_ context.Context, req *ledgerpb.GetRequest) (*ledgerpb.LeafHashesResponse, error)
- func (s *PayloadlessService) GetSingleLeafHash(_ context.Context, req *ledgerpb.GetSingleValueRequest) (*ledgerpb.LeafHashResponse, error)
- func (s *PayloadlessService) HasPaths(_ context.Context, req *ledgerpb.GetRequest) (*ledgerpb.HasPathsResponse, error)
- func (s *PayloadlessService) HasState(_ context.Context, req *ledgerpb.StateRequest) (*ledgerpb.HasStateResponse, error)
- func (s *PayloadlessService) InitialState(_ context.Context, _ *emptypb.Empty) (*ledgerpb.StateResponse, error)
- func (s *PayloadlessService) Prove(_ context.Context, req *ledgerpb.ProveRequest) (*ledgerpb.ProofResponse, error)
- func (s *PayloadlessService) Set(_ context.Context, req *ledgerpb.SetRequest) (*ledgerpb.SetResponse, error)
- type Service
- func (s *Service) Get(ctx context.Context, req *ledgerpb.GetRequest) (*ledgerpb.GetResponse, error)
- func (s *Service) GetSingleValue(ctx context.Context, req *ledgerpb.GetSingleValueRequest) (*ledgerpb.ValueResponse, error)
- func (s *Service) HasState(ctx context.Context, req *ledgerpb.StateRequest) (*ledgerpb.HasStateResponse, error)
- func (s *Service) InitialState(ctx context.Context, req *emptypb.Empty) (*ledgerpb.StateResponse, error)
- func (s *Service) Prove(ctx context.Context, req *ledgerpb.ProveRequest) (*ledgerpb.ProofResponse, error)
- func (s *Service) Set(ctx context.Context, req *ledgerpb.SetRequest) (*ledgerpb.SetResponse, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements ledger.Ledger interface using gRPC calls to a remote ledger service.
func NewClient ¶
NewClient creates a new remote ledger client. grpcAddr can be either a TCP address (e.g., "localhost:9000") or a Unix domain socket. For Unix sockets, you can use either the full gRPC format (e.g., "unix:///tmp/ledger.sock") or just the absolute path (e.g., "/tmp/ledger.sock") - the unix:// prefix will be added automatically. Options can be provided to customize the client configuration. By default, max request and response sizes are 1 GiB.
func (*Client) Done ¶
func (c *Client) Done() <-chan struct{}
Done returns a channel that is closed when the client is done. This cancels any in-flight gRPC calls and closes the connection. The method is idempotent - multiple calls return the same channel.
func (*Client) GetSingleValue ¶
GetSingleValue returns a single value for a given key at a specific state.
func (*Client) HasState ¶
HasState returns true if the given state exists in the ledger.
A gRPC failure is surfaced to the caller rather than collapsed into a false return: false must mean "state genuinely absent", not "the server was unreachable", otherwise callers (e.g. execution state) would misreport a reachable state as pruned.
No error returns are expected during normal operation.
func (*Client) InitialState ¶
InitialState returns the initial state of the ledger.
func (*Client) Ready ¶
func (c *Client) Ready() <-chan struct{}
Ready returns a channel that is closed when the client is ready.
Readiness has two phases. First, this client waits for the ledger service to finish initialization by calling InitialState() with retries (the server may still be replaying its WAL). Second, after the service responds, the client calls LedgerInfoService.ServerInfo to verify the server is running in FULL mode. A mode mismatch is treated as a configuration error and crashes the process via log.Fatal — clients of a payloadless server must use PayloadlessClient, not Client.
func (*Client) Set ¶
Set updates keys with new values at a specific state and returns the new state.
func (*Client) StateByIndex ¶
StateByIndex returns the state at the given index. -1 is the last index. This is not supported for remote clients as it requires gRPC methods that are not yet implemented.
func (*Client) StateCount ¶
StateCount returns the number of states in the ledger. This is not supported for remote clients as it requires gRPC methods that are not yet implemented.
type ClientOption ¶
type ClientOption func(*clientConfig)
ClientOption is a function that configures a Client.
func WithCallTimeout ¶
func WithCallTimeout(timeout time.Duration) ClientOption
WithCallTimeout sets the timeout for individual gRPC calls.
func WithMaxRequestSize ¶
func WithMaxRequestSize(size uint) ClientOption
WithMaxRequestSize sets the maximum request message size in bytes.
func WithMaxResponseSize ¶
func WithMaxResponseSize(size uint) ClientOption
WithMaxResponseSize sets the maximum response message size in bytes.
type InfoService ¶
type InfoService struct {
ledgerpb.UnimplementedLedgerInfoServiceServer
// contains filtered or unexported fields
}
InfoService implements the gRPC LedgerInfoService interface. It is registered on every ledger gRPC server, regardless of the server's mode, so clients can discover the mode of the server they connected to before issuing mode-specific RPCs.
InfoService is stateless and concurrency-safe.
func NewInfoService ¶
func NewInfoService(mode ledgerpb.LedgerMode) *InfoService
NewInfoService creates a new info service that reports the given mode. Callers MUST pass either ledgerpb.LedgerMode_LEDGER_MODE_FULL or ledgerpb.LedgerMode_LEDGER_MODE_PAYLOADLESS; passing UNSPECIFIED produces a server that reports UNSPECIFIED, which clients will treat as a misconfigured server and refuse to use.
func (*InfoService) ServerInfo ¶
func (s *InfoService) ServerInfo(_ context.Context, _ *emptypb.Empty) (*ledgerpb.ServerInfoResponse, error)
ServerInfo returns the server's operating mode.
No error returns are expected during normal operation.
type PayloadlessClient ¶
type PayloadlessClient struct {
// contains filtered or unexported fields
}
PayloadlessClient is a gRPC client for a payloadless ledger server. Reads return leaf hashes (HashLeaf(path, value)) rather than payload values.
PayloadlessClient mirrors Client in dial / retry / lifecycle behavior; the difference is the registered service it talks to and the leaf-hash return types on the read methods. Both clients share the same dial helper and the same mode-discovery check in Ready().
func NewPayloadlessClient ¶
func NewPayloadlessClient(grpcAddr string, logger zerolog.Logger, opts ...ClientOption) (*PayloadlessClient, error)
NewPayloadlessClient creates a new payloadless remote ledger client.
`grpcAddr` accepts the same forms as NewClient. Connection-establishment retries are identical: ~40 minutes of exponential backoff before log.Fatal. Mode verification happens in [Ready] (not here) — a wrong-mode server will be detected the first time the caller waits on Ready().
func (*PayloadlessClient) Close ¶
func (c *PayloadlessClient) Close() error
Close closes the gRPC connection.
func (*PayloadlessClient) Done ¶
func (c *PayloadlessClient) Done() <-chan struct{}
Done returns a channel that is closed when the client is done. Idempotent.
func (*PayloadlessClient) GetLeafHashes ¶
GetLeafHashes returns leaf hashes for multiple keys at a specific state. A nil entry in the returned slice indicates an unallocated register.
Expected error returns during normal operation:
- generic error wrapping the underlying gRPC failure when the call fails.
func (*PayloadlessClient) GetSingleLeafHash ¶
func (c *PayloadlessClient) GetSingleLeafHash(query *ledger.QuerySingleValue) (*hash.Hash, error)
GetSingleLeafHash returns the leaf hash for a single key at a specific state. Returns nil if the key has no allocated register.
Expected error returns during normal operation:
- generic error wrapping the underlying gRPC failure when the call fails.
func (*PayloadlessClient) HasPaths ¶
func (c *PayloadlessClient) HasPaths(query *ledger.Query) ([]bool, error)
HasPaths reports, for each key in `query.Keys()`, whether the key has an allocated register at `query.State()`.
Expected error returns during normal operation:
- generic error wrapping the underlying gRPC failure when the call fails.
func (*PayloadlessClient) HasState ¶
func (c *PayloadlessClient) HasState(state ledger.State) (bool, error)
HasState returns true if the given state exists in the payloadless ledger.
A gRPC failure is surfaced to the caller rather than collapsed into a false return: false must mean "state genuinely absent", not "the server was unreachable", otherwise callers (e.g. execution state) would misreport a reachable state as pruned.
No error returns are expected during normal operation.
func (*PayloadlessClient) InitialState ¶
func (c *PayloadlessClient) InitialState() ledger.State
InitialState returns the initial state of the payloadless ledger.
func (*PayloadlessClient) Prove ¶
func (c *PayloadlessClient) Prove(query *ledger.Query) (*ledger.PayloadlessTrieBatchProof, error)
Prove returns a payloadless batch proof for the given keys at a specific state. The proof is decoded with ledger.DecodePayloadlessTrieBatchProof.
Expected error returns during normal operation:
- generic error wrapping the underlying gRPC failure or a decode failure.
func (*PayloadlessClient) Ready ¶
func (c *PayloadlessClient) Ready() <-chan struct{}
Ready returns a channel that is closed when the client is ready.
Readiness has two phases. First, the client waits for the ledger service to finish initialization by calling InitialState() with retries. Second, it calls LedgerInfoService.ServerInfo to verify the server is running in PAYLOADLESS mode. A mode mismatch is treated as a configuration error and crashes the process via log.Fatal — clients of a full server must use Client, not PayloadlessClient.
func (*PayloadlessClient) Set ¶
func (c *PayloadlessClient) Set(update *ledger.Update) (ledger.State, *ledger.TrieUpdate, error)
Set updates keys with new values at a specific state and returns the new state plus the trie update that was applied.
Expected error returns during normal operation:
- generic error wrapping the underlying gRPC failure when the call fails, or when the response is malformed.
type PayloadlessService ¶
type PayloadlessService struct {
ledgerpb.UnimplementedPayloadlessLedgerServiceServer
// contains filtered or unexported fields
}
PayloadlessService implements the gRPC PayloadlessLedgerService interface on top of a ledger.PayloadlessLedger. Reads return leaf hashes rather than payload values.
A ledger gRPC server registers either Service (full mode) or PayloadlessService (payloadless mode), never both. The mode is chosen at startup config.
func NewPayloadlessService ¶
func NewPayloadlessService(l ledger.PayloadlessLedger, logger zerolog.Logger) *PayloadlessService
NewPayloadlessService creates a new payloadless ledger gRPC service. In production the ledger argument is a *complete.PayloadlessLedger; tests may pass any value that satisfies ledger.PayloadlessLedger.
func (*PayloadlessService) GetLeafHashes ¶
func (s *PayloadlessService) GetLeafHashes(_ context.Context, req *ledgerpb.GetRequest) (*ledgerpb.LeafHashesResponse, error)
GetLeafHashes returns leaf hashes for multiple keys. Unallocated registers are reported as `LeafHash` entries with empty `hash` fields.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil or has the wrong length, or when `req.Keys` is empty.
func (*PayloadlessService) GetSingleLeafHash ¶
func (s *PayloadlessService) GetSingleLeafHash(_ context.Context, req *ledgerpb.GetSingleValueRequest) (*ledgerpb.LeafHashResponse, error)
GetSingleLeafHash returns the leaf hash for a single key. An unallocated register is reported as an empty `hash` field.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil or has the wrong length, or when `req.Key` is nil.
func (*PayloadlessService) HasPaths ¶
func (s *PayloadlessService) HasPaths(_ context.Context, req *ledgerpb.GetRequest) (*ledgerpb.HasPathsResponse, error)
HasPaths reports, for each key in `req.Keys`, whether the key has an allocated register at `req.State`.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil or has the wrong length, or when `req.Keys` is empty.
func (*PayloadlessService) HasState ¶
func (s *PayloadlessService) HasState(_ context.Context, req *ledgerpb.StateRequest) (*ledgerpb.HasStateResponse, error)
HasState checks if the given state exists in the payloadless ledger.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil or has the wrong length.
func (*PayloadlessService) InitialState ¶
func (s *PayloadlessService) InitialState(_ context.Context, _ *emptypb.Empty) (*ledgerpb.StateResponse, error)
InitialState returns the initial state of the payloadless ledger.
No error returns are expected during normal operation.
func (*PayloadlessService) Prove ¶
func (s *PayloadlessService) Prove(_ context.Context, req *ledgerpb.ProveRequest) (*ledgerpb.ProofResponse, error)
Prove returns a payloadless batch proof for the given keys at a specific state. The proof is encoded with ledger.EncodePayloadlessTrieBatchProof.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil/wrong length or `req.Keys` is empty.
func (*PayloadlessService) Set ¶
func (s *PayloadlessService) Set(_ context.Context, req *ledgerpb.SetRequest) (*ledgerpb.SetResponse, error)
Set updates keys with new values at a specific state and returns the new state. The server discards the keys after hashing; only the values contribute to the trie.
Expected error returns during normal operation:
- gRPC InvalidArgument: when `req.State` is nil/wrong length, keys are empty, or keys/values lengths mismatch.
type Service ¶
type Service struct {
ledgerpb.UnimplementedLedgerServiceServer
// contains filtered or unexported fields
}
Service implements the gRPC LedgerService interface
func NewService ¶
NewService creates a new ledger service
func (*Service) Get ¶
func (s *Service) Get(ctx context.Context, req *ledgerpb.GetRequest) (*ledgerpb.GetResponse, error)
Get returns values for multiple keys at a specific state
func (*Service) GetSingleValue ¶
func (s *Service) GetSingleValue(ctx context.Context, req *ledgerpb.GetSingleValueRequest) (*ledgerpb.ValueResponse, error)
GetSingleValue returns a single value for a given key at a specific state
func (*Service) HasState ¶
func (s *Service) HasState(ctx context.Context, req *ledgerpb.StateRequest) (*ledgerpb.HasStateResponse, error)
HasState checks if the given state exists in the ledger
func (*Service) InitialState ¶
func (s *Service) InitialState(ctx context.Context, req *emptypb.Empty) (*ledgerpb.StateResponse, error)
InitialState returns the initial state of the ledger
func (*Service) Prove ¶
func (s *Service) Prove(ctx context.Context, req *ledgerpb.ProveRequest) (*ledgerpb.ProofResponse, error)
Prove returns proofs for the given keys at a specific state
func (*Service) Set ¶
func (s *Service) Set(ctx context.Context, req *ledgerpb.SetRequest) (*ledgerpb.SetResponse, error)
Set updates keys with new values at a specific state and returns the new state
Source Files