Tracking state

The extension exposes its progress as a small state machine. The SDK reads it on demand with getExtensionState or continuously with subscribeToExtensionState.

The status values

The diagram shows each status and the transitions between them.

Read once with getExtensionState (null when the extension is unavailable) or subscribe; the callback fires only when the state changes.

Reading once


const state = await KeyringConnect.getExtensionState();

getExtensionState resolves to null rather than throwing when the extension is unavailable or does not answer within two seconds.

Subscribing

subscribeToExtensionState polls every three seconds and invokes the callback only when the state actually changes. It returns an unsubscribe function.


const unsubscribe = KeyringConnect.subscribeToExtensionState((state) => {
  if (!state) return; // extension not available (uninstalled or disabled)
 
  switch (state.status) {
    case "proving":
      showSpinner();
      break;
    case "prove_success":
      unsubscribe();
      onVerified(state.user);
      break;
    case "prove_error":
    case "error":
      showError(state.error);
      break;
  }
});

The user object

state.user carries two independent statuses worth distinguishing in UI: attestation_status for the off-chain side and credential_status for the on-chain side. A returning user with credential_status: "valid" needs no new proof; a user with attestation_ready but an expired credential can refresh on chain without repeating verification. Field-level details are in the SDK reference.