SettleMint
Runbooks

Rotate provider issuer EOA

Operational runbook for rotating the DALP-custodied issuer key used by a tenant compliance provider integration.

When to rotate

Rotate a provider issuer EOA when:

  • The provider's signing key is suspected to be compromised.
  • A scheduled key-rotation policy requires replacement.
  • A provider integration is being decommissioned and the old EOA must stop attesting.
  • The tenant is moving provider operations to a new integration record.

The provider issuer EOA is single-tenant and single-purpose: never share an EOA across tenants or providers. Remove the EOA from the trusted issuer registry before decommissioning the underlying key, and keep enough non-bootstrapper management-key holders to recover the registry if anything fails mid-rotation.

Procedure

Identify the integration

In the dapp, go to Platform Settings → Compliance providers and open the integration's detail page. Note:

  • The provider name and topic.
  • The current provider issuer address displayed at the top of the detail page.
  • The webhook URL (you'll keep using the same URL after rotation).

Remove the old issuer from the trusted issuer registry

Submit a trusted-issuer removal in the dapp's Identity surface (or via your platform's trusted-issuer admin tooling) for the current provider issuer address and the integration's claim topic. This stops the old EOA from being trusted before the new one takes over.

Do not delete or disable the underlying key until this removal transaction is final.

Provision the replacement issuer

On the integration detail page, click Retry provisioning (the same action used to recover from a failed initial provisioning). DALP will:

  1. Reuse the stored provider credentials and webhook signing secret.
  2. Provision a new tenant-scoped, custodied EOA dedicated to this integration.
  3. Register the replacement EOA in the trusted issuer registry for the integration's topic.

The action is idempotent: it picks up where the previous attempt stopped and only runs the steps that didn't yet land.

Confirm the new issuer is active

Reload the integration detail page and confirm:

  • The status is Active.
  • The provider issuer address has changed to the replacement EOA.
  • The "Last rotated" timestamp reflects this rotation window.

Verification

After the integration shows Active with the new issuer address, deliver a small synthetic test event from the provider dashboard (a no-op state-change webhook is fine). Confirm in the integration's monitoring or activity surface that the event was processed under the new issuer and produced the expected on-chain effect (or no effect, for monitoring providers that did not cross the configured severity threshold).

If the test event surfaces under the old issuer address, the trusted-issuer registry still trusts the old key — restart provisioning and verify the registry transactions completed.

Rollback

If replacement provisioning fails before the old key is decommissioned:

  • Re-add the old EOA to the trusted issuer registry for the integration's topic.
  • Pause the integration until a maintenance window allows a clean retry.

If the old key is suspected to be compromised, do not re-add it. Keep the integration paused; downstream transfers gated on the integration's topic will block until a replacement EOA is trusted, which is the correct fail-closed behavior under suspected compromise.

Runbooks

Operator runbooks for rotating provider EOAs and performing high-control lifecycle operations.

On this page

When to rotateProcedureIdentify the integrationRemove the old issuer from the trusted issuer registryProvision the replacement issuerConfirm the new issuer is activeVerificationRollbackRelated