Rotate a DALP compliance provider's claim signer key

Operational runbook for rotating the autonomous EOA that signs claims on a compliance provider's claim-issuer identity. Rotation happens via addKey / removeKey on the identity and does not require any trusted issuers registry mutation.

The claim signer key is the EOA DALP uses to sign and revoke provider-backed compliance claims. The issuer of record stays the provider's OnchainID identity contract. Rotate the signer by changing authorised keys on that identity, then align the provider record that tells DALP which signer wallet to use for new claim operations.

When to rotate

Rotate a provider's claim signer key when:

The provider's signing key is suspected to be compromised.
A scheduled key-rotation policy requires replacement.
Custody for the autonomous EOA is moving between approved signer backends.
An operational or compliance audit finding requires a fresh key.

Why rotation changes the key, not the trusted issuer

Rotation does not require a trusted issuers registry mutation. The trusted issuer is the provider's claim-issuer identity contract, not the EOA. The EOA is only an authorised key on that identity. DALP provisions that signer as a MANAGEMENT_KEY (purpose 1), and the OnchainID key-purpose check treats a management key as satisfying the claim signer check.

Rotation therefore happens entirely on the identity contract:

Add the new EOA to the identity as a MANAGEMENT_KEY.
Remove the old EOA from the identity.
Update DALP's provider bookkeeping for the claim-issuer participant (issuerEoaAddress and issuerWalletId).

The identity address, trusted issuers registry registration, topic array, webhook URL, and provider credentials stay the same. Subjects continue to verify claims against the same claims.issuer address before, during, and after rotation.

Procedure

Identify the provider

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

The provider name and the list of active topics.
The current autonomous EOA address (the claim signer key).
The claim-issuer identity address (this stays the same across rotation).
The webhook URL (you'll keep using the same URL after rotation).

Mint a replacement EOA

Provision a new tenant-scoped, custodied EOA dedicated to this provider's claim-issuer identity. The platform's signer infrastructure (Vault / DFNS / Fireblocks adapter) handles the actual key creation; the result is a new EOA address and wallet id.

DALP provisions the first claim-issuer EOA with the claim-issuer-eoa-${participantId} wallet-name convention during provider setup. Do not reuse that name for rotation. Create a replacement wallet with a distinct rotation name or wallet id under the same tenant, then keep that wallet id with the provider operation record so claim issue and revoke workflows can resolve the new signer.

Add the new EOA as a MANAGEMENT_KEY on the provider identity

Submit an addKey(newKeyHash, MANAGEMENT_KEY, ECDSA_KEY) transaction against the provider's claim-issuer identity. The transaction must be sent by an existing MANAGEMENT_KEY holder on that identity (the bootstrapper system role used during F1 provisioning, or the current autonomous EOA before its removal).

After this step lands, both the old and new EOAs hold MANAGEMENT_KEY on the identity. Claims signed by either key continue to verify successfully against keyHasPurpose(keyHash, CLAIM_SIGNER_KEY) because of the superset rule. This is the grace window: in-flight claim signing under the old key drains naturally instead of being cut off mid-flight.

The recommended grace window depends on the provider's webhook delivery cadence and the platform's transaction queue depth. Default to at least 5 minutes; extend to 30 minutes or more if the provider is known to deliver bursty events or if the transaction queue is backed up.

Remove the old EOA from the provider identity

Once the grace window has elapsed and you have observed at least one successful claim signed by the new EOA (see Verification below), submit a removeKey(oldKeyHash, MANAGEMENT_KEY) transaction against the same identity. After this step lands, only the new EOA holds MANAGEMENT_KEY on the identity; claims signed by the old EOA stop verifying.

Order matters. Always run addKey before removeKey. Reversing the order leaves the identity with no authorised key and breaks claim issuance until addKey lands.

Update the provider record

Update DALP's claim-issuer participant bookkeeping to reflect the new signer:

issuerEoaAddress becomes the new EOA address.
issuerWalletId becomes the new wallet id.
onchainIdentityAddress stays unchanged.

The provider detail page reads these fields when it shows the autonomous EOA and claim-issuer identity. Update the record through approved platform administration tooling so new claim issue and revoke workflows use the new signer wallet.

Confirm the rotation is complete

Reload the provider detail page and confirm:

Status is Active.
The autonomous EOA address has changed to the replacement EOA.
The claim-issuer identity address is unchanged.
The trusted issuers registry registration is unchanged: same identity, same topic array.

Verification

After the rotation completes, deliver a small synthetic test event from the provider dashboard (a no-op state-change webhook is fine). Confirm in the provider's monitoring or activity surface that:

The event was processed under the new EOA (the on-chain transaction sender matches the new EOA address).
The resulting claim's issuer field still references the same claim-issuer identity address as before rotation.
The claim verifies against the trusted issuers registry without changes.

If the test event surfaces under the old EOA address, the provider bookkeeping update did not land. Re-check the claim-issuer participant issuerEoaAddress value and re-run the administration update.

If the test event signs successfully but the claim fails to verify, check that addKey landed on the identity and that the new key has MANAGEMENT_KEY (purpose 1). Use a read-only getKey(newKeyHash) call against the identity to inspect the key's purpose set.

Partial-failure recovery

Rotation is three on-chain operations (addKey, removeKey, DB update) plus an off-chain key mint. Each step has a documented recovery path:

EOA mint succeeds, addKey fails. Re-run addKey with the same new EOA. The mint is idempotent; the addKey transaction can be re-submitted under the same nonce-managed signer until it lands.
addKey succeeds, removeKey fails. The identity now has two MANAGEMENT_KEY holders. The provider stays fully operational on either key. Re-run removeKey to complete the rotation. There is no data-loss risk: the grace-window state is the same state you would intentionally hold during a long rotation.
removeKey succeeds, provider-record update fails. The on-chain state is correct because only the new EOA is authorised, but DALP may still try to sign through the old wallet. Update issuerEoaAddress and issuerWalletId; no on-chain work is required.

In every case the claim-issuer identity address, trusted issuers registry registration, topic array, and webhook URL are untouched, so subjects continue to verify claims against the same issuer regardless of where in the rotation sequence the failure occurs.

Rollback

If rotation needs to be aborted after addKey but before removeKey:

Leave the old EOA as the active signer in the claim-issuer participant issuerEoaAddress and issuerWalletId fields.
Run removeKey(newKeyHash) against the identity to remove the partially-installed new key.
The provider returns to its pre-rotation state.

If the old key is suspected to be compromised, do not roll back. Complete the rotation by running removeKey on the old key as soon as the new key is verified working. A compromised old key remaining on the identity is the worst possible state: finishing the rotation, even out of order, is preferable to rolling back.

Compliance provider onboarding: full provider setup
Compliance providers architecture: issuer-of-record model and key-purpose superset rule

Rotate provider claim signer key