State management

It’s the responsibility of the immudb client to track the server state. That way it can check each verified read or write operation against a trusted state.

The component in charge of state handling is the StateService. To set up the stateService 3 interfaces need to be implemented and provided to the StateService constructor:

  • Cache interface in the cache package. Standard cache.NewFileCache provides a file state store solution.
  • StateProvider in the stateService package. It provides a fresh state from immudb server when the client is being initialized for the first time. Standard StateProvider provides a service that retrieve immudb first state hash from a gRPC endpoint.
  • UUIDProvider in the stateService package. It provides the immudb identifier. This is needed to allow the client to safely connect to multiple immudb instances. Standard UUIDProvider provides the immudb server identifier from a gRPC endpoint.

Following an example how to obtain a client instance with a custom state service.


1. func MyCustomImmuClient(options *c.Options) (cli c.ImmuClient, err error) {
2. ctx := context.Background()

4. cli = c.DefaultClient()

6. options.DialOptions = cli.SetupDialOptions(options)

8. cli.WithOptions(options)

10. var clientConn *grpc.ClientConn
11. if clientConn, err = cli.Connect(ctx); err != nil {
12. return nil, err
13. }

15. cli.WithClientConn(clientConn)

17. serviceClient := schema.NewImmuServiceClient(clientConn)
18. cli.WithServiceClient(serviceClient)

20. if err = cli.WaitForHealthCheck(ctx); err != nil {
21. return nil, err
22. }

24. immudbStateProvider := stateService.NewImmudbStateProvider(serviceClient)
25. immudbUUIDProvider := stateService.NewImmudbUUIDProvider(serviceClient)

27. customDir := "custom_state_dir"
28. os.Mkdir(customDir, os.ModePerm)
29. stateService, err := stateService.NewStateService(
30. cache.NewFileCache(customDir),
31. logger.NewSimpleLogger("immuclient", os.Stderr),
32. immudbStateProvider,
33. immudbUUIDProvider)
34. if err != nil {
35. return nil, err
36. }

38. dt, err := timestamp.NewDefaultTimestamp()
39. if err != nil {
40. return nil, err
41. }

43. ts := c.NewTimestampService(dt)
44. cli.WithTimestampService(ts).WithStateService(stateService)

46. return cli, nil
47. }

Any immudb server has its own UUID. This is exposed as part of the login response. Java SDK can use any implementation of the ImmuStateHolder interface, which specifies two methods:

  • ImmuState getState(String serverUuid, String database) for getting a state.
  • void setState(String serverUuid, ImmuState state) for setting a state.

Note that a state is related to a specific database (identified by its name) and a server (identified by the UUID). Currently, Java SDK offers two implementations of this interface for storing and retriving a state:

  • FileImmuStateHolder that uses a disk file based store.
  • SerializableImmuStateHolder that uses an in-memory store.

As most of the code snippets include FileImmuStateHolder, please find below an example using the in-memory alternative:


1. SerializableImmuStateHolder stateHolder = new SerializableImmuStateHolder();

3. ImmuClient immuClient = ImmuClient.newBuilder()
4. .withStateHolder(stateHolder)
5. .withServerUrl("localhost")
6. .withServerPort(3322)
7. .build();

9. immuClient.login("immudb", "immudb");
10. immuClient.useDatabase("defaultdb");
11. // ...
12. immuClient.logout();

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectState management - 图1 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github projectState management - 图2 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectState management - 图3 (opens new window)

If you’re using another development language, please read up on our immugwState management - 图4 (opens new window) option.

Verify state signature

If immudb is launched with a private signing key, each signed request can be verified with the public key. In this way the identity of the server can be proven. Check state signature to see how to generate a valid key.


1. c, err := client.NewImmuClient(client.DefaultOptions().WithServerSigningPubKey("../../immudb/src/wrong.public.key"))
2. if err != nil {
3. log.Fatal(err)
4. }
5. ctx := context.Background()

7. lr , err := c.Login(ctx, []byte(`immudb`), []byte(`immudb`))
8. if err != nil {
9. log.Fatal(err)
10. }

12. md := metadata.Pairs("authorization", lr.Token)
13. ctx = metadata.NewOutgoingContext(context.Background(), md)

15. if _, err := c.Set(ctx, []byte(`immudb`), []byte(`hello world`)); err != nil {
16. log.Fatal(err)
17. }

19. var state *schema.ImmutableState
20. if state, err = c.CurrentState(ctx); err != nil {
21. log.Fatal(err) // if signature is not verified here is trigger an appropriate error
22. }

24. fmt.Print(state)



1. // Having immudb server running with state signature enabled
2. // (by starting it, for example using `immudb --signingKey private_key.pem`)
3. // we provision the client with the public key file, and this implies that
4. // state signature verification is done on the client side
5. // each time the state is retrieved from the server.

7. File publicKeyFile = new File("path/to/public_key.pem");

9. immuClient = ImmuClient.newBuilder()
10. .withServerUrl("localhost")
11. .withServerPort(3322)
12. .withServerSigningKey(publicKeyFile.getAbsolutePath())
13. .build();

15. try {
16. ImmuState state = immuClient.currentState();
17. // It should all be ok as long as the immudb server has been started with
18. // state signature feature enabled, otherwise, this verification will fail.

20. } catch (RuntimeException e) {
21. // State signature failed.
22. }

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectState management - 图5 (opens new window)


1. import ImmudbClient from 'immudb-node'

3. const IMMUDB_HOST = '127.0.0.1'
4. const IMMUDB_PORT = '3322'
5. const IMMUDB_USER = 'immudb'
6. const IMMUDB_PWD = 'immudb'

8. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

10. (async () => {
11. await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
12. await cl.set({ key: 'immudb', value: 'hello world' })

14. const currentStateRes = await cl.currentState();
15. console.log('success: currentState', currentStateRes)
16. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectState management - 图6 (opens new window)

If you’re using another development language, please read up on our immugwState management - 图7 (opens new window) option.

Tamperproof reading and writing

You can read and write records securely using a built-in cryptographic verification.

Verified get and set

The client implements the mathematical validations, while your application uses a traditional read or write function.


1. tx, err := client.VerifiedSet(ctx, []byte(`hello`), []byte(`immutable world`))
2. if  err != nil {
3. log.Fatal(err)
4. }

6. fmt.Printf("Successfully committed and verified tx %d\n", tx.Id)

8. entry, err := client.VerifiedGet(ctx, []byte(`hello`))
9. if  err != nil {
10. log.Fatal(err)
11. }

13. fmt.Printf("Successfully retrieved and verified entry: %v\n", entry)



1. try {
2. TxMetadata txMd = immuClient.verifiedSet(key, val);
3. System.out.println("Successfully committed and verified tx " + txMd.id);
4. } catch (VerificationException e) {
5. // ...
6. }

8. try {
9. Entry vEntry = immuClient.verifiedGet(key);
10. System.out.println("Successfully retrieved and verified entry: " + vEntry);
11. } catch (VerificationException e) {
12. // ...
13. }

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectState management - 图8 (opens new window)


1. import ImmudbClient from 'immudb-node'
2. import Parameters from 'immudb-node/types/parameters'

4. const IMMUDB_HOST = '127.0.0.1'
5. const IMMUDB_PORT = '3322'
6. const IMMUDB_USER = 'immudb'
7. const IMMUDB_PWD = 'immudb'

9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

11. (async () => {
12. await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })

14. const verifiedSetReq: Parameters.VerifiedSet = {
15. key: 'hello',
16. value: 'world',
17. }
18. const verifiedSetRes = await cl.verifiedSet(verifiedSetReq)
19. console.log('success: verifiedSet', verifiedSetRes)

21. const verifiedGetReq: Parameters.VerifiedGet = {
22. key: 'hello',
23. }
24. const verifiedGetRes = await cl.verifiedGet(verifiedGetReq)
25. console.log('success: verifiedGet', verifiedGetRes)
26. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectState management - 图9 (opens new window)

If you’re using another development language, please read up on our immugwState management - 图10 (opens new window) option.