# Compliance Providers Source: https://docs.settlemint.com/docs/architects/integrations/compliance-providers Architecture reference for compliance-provider intake across identity, business, AML, and wallet-monitoring providers. Explains how provider events become tenant-scoped on-chain claims and where per-transfer decisions belong instead. Compliance providers connect external KYC, KYB, AML, and wallet-monitoring systems to DALP claim issuance. Events from providers such as [Sumsub](https://docs.sumsub.com/), [Elliptic](https://developers.elliptic.co/), [ComplyAdvantage](https://docs.complyadvantage.com/), [Jumio](https://docs.jumio.com/), [Middesk](https://docs.middesk.com/), [Onfido](https://documentation.onfido.com/), [Persona](https://docs.withpersona.com/), [Trulioo](https://developer.trulioo.com/), and [Veriff](https://developers.veriff.com/) become tenant-scoped on-chain claims issued by a trusted issuer. ClaimSource is the durable compliance-provider intake path for persistent identity, business, or wallet subjects. Per-transfer decisions use a separate transfer-time path. ## Current coverage boundary [#current-coverage-boundary] Current DALP compliance-provider adapters cover provider events that can be reduced to durable identity, business, or wallet claims through ClaimSource: * Identity and KYB verdicts from configured KYC/KYB providers * Monitoring alerts from applicant, entity, and wallet-monitoring providers * Wallet-monitoring alerts from Elliptic Travel Rule transfer gating is a separate per-transfer decision surface rather than a compliance-provider adapter. DALP does not publish a default named Travel Rule provider adapter in the current compliance-provider catalog. [Chainalysis KYT](https://docs.chainalysis.com/) is also not a current DALP compliance-provider adapter. ## Choose the right compliance path [#choose-the-right-compliance-path] DALP separates durable claim intake from per-transfer decisions. Choose the path by the subject you need to evaluate: | If the provider evaluates... | Use this DALP path | Result | | -------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | A person, organisation, or wallet that should keep a compliance status after the event | ClaimSource through the compliance-provider webhook | DALP maps the provider subject to a DALP identity and issues or revokes an on-chain claim for the configured topic | | A trusted issuer that should manually issue claims through DALP APIs | Trusted issuer claim issuance | DALP checks the caller's trusted-issuer topics before queueing the claim transaction | | One outbound or inbound transfer | TransferGate or another per-transfer adapter | DALP evaluates the transfer-time decision without turning it into a persistent identity claim | Do not route Travel Rule or other transaction-specific decisions through ClaimSource. ClaimSource is for provider events that attach to an identity, business, or wallet subject and can be represented as a standard claim topic. ## Provider intake model [#provider-intake-model] Compliance integrations split by what the provider produces and how long the subject lives: | Surface | Provider shape | DALP behaviour | | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A | Identity verdicts | Sumsub, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff terminal verdicts issue or remove on-chain claims for one or more topics the provider is trusted for | | B | Monitoring alerts | Sumsub AML watchlist events, Sumsub applicant-on-hold events, ComplyAdvantage entity monitoring, and Elliptic wallet alerts are normalised to a 0 to 100 severity scale and can revoke claims above a configured per-topic threshold | | C | Per-transaction Travel Rule | Outside the current dapp compliance-provider flow | ClaimSource covers identity or wallet subjects that persist beyond one transaction. Sumsub applicant-review events produce identity verdicts; Sumsub AML watchlist events, Sumsub applicant-on-hold events, and ComplyAdvantage monitored-search events produce monitoring alerts; Elliptic produces wallet-monitoring alerts. TransferGate is reserved for Travel Rule and similar per-transaction decisions, where the subject is one transfer rather than a durable identity or wallet. ### Supported provider topics [#supported-provider-topics] Each provider kind can only attest the topic names DALP publishes for that adapter. Multi-topic providers can reuse the same provider identity for each supported topic. Single-topic providers require a separate provider lifecycle if the tenant needs a different topic. | Provider kind | Supported topic names | | --------------- | -------------------------------------- | | Sumsub | `knowYourCustomer` | | Sumsub AML | `antiMoneyLaundering` | | Sumsub KYT | `knowYourTransaction` | | ComplyAdvantage | `antiMoneyLaundering` | | Elliptic | `antiMoneyLaundering` | | Jumio | `knowYourCustomer` | | Middesk | `knowYourBusiness` | | Onfido | `knowYourCustomer`, `knowYourBusiness` | | Persona | `knowYourCustomer`, `knowYourBusiness` | | Trulioo | `knowYourCustomer` | | Veriff | `knowYourCustomer` | ## Provider record model [#provider-record-model] Each compliance provider in DALP is a parent record with one or more attached **claim topics**. One provider identity can attest every topic it is trusted for. Topic policy stays explicit: * **`compliance_providers`** holds the provider record: credentials, signing secret(s), the autonomous EOA, the on-chain claim-issuer identity address, and the webhook URL token. There is exactly **one provider record per (provider × tenant)**. * **`compliance_provider_topics`** holds the per-topic policy: topic name, on-chain topic id, status (`active` / `revoked`), revocation severity threshold, and notification channels. Multiple topic rows attach to the same provider. Subject mappings (Sumsub applicants, Elliptic wallets) are re-keyed at the **provider** level, not at the topic level. A single subject mapping covers every topic the provider is trusted for. ### Provider identity and key list [#provider-identity-and-key-list] A provider's on-chain trust path uses the same participant, OnchainID, and key list primitives as the organisation deployment: * **Participant.** Provisioning creates a `claim_issuer` participant for the provider (via `createClaimIssuerParticipant`). The participant id is deterministic so retries are idempotent. * **Autonomous EOA.** The configured custody adapter provisions a tenant-scoped, custodied EOA dedicated to this participant. The EOA signs every claim emitted by the provider without another DALP approval step. * **OnchainID claim-issuer identity.** The Identity Factory deploys a fresh OnchainID identity contract for the participant. The provider's identity is **separate** from the tenant organization identity and from any subject identity. * **Key list.** The autonomous EOA is added to the provider's identity as a `MANAGEMENT_KEY` (purpose 1). ERC-734's `keyHasPurpose` checks against `MANAGEMENT_KEY` as a **superset**: one key entry simultaneously satisfies the addClaim authorisation check (`ACTION_KEY` semantics), the claim signature verification check (`CLAIM_SIGNER_KEY` semantics), and the addKey rotation check (`MANAGEMENT_KEY` semantics). This mirrors the organisation deployment pattern and avoids maintaining three separate purpose entries. The same generic primitives drive both organisation and provider deployments: ```text provisionParticipantEoa(walletName) ← generic primitive ↳ provisionOrganisationEoa(orgId) ← thin wrapper for organisation deployment ↳ provisionClaimIssuerEoa(participantId) ← thin wrapper for provider provisioning createParticipantRow(kind, id, …) ← generic query ↳ createOrganisationParticipant(orgId, …) ← thin wrapper ↳ createClaimIssuerParticipant(providerId, …) ← thin wrapper ``` ### Multi-topic trusted-issuer registration [#multi-topic-trusted-issuer-registration] The trusted issuers registry contract registers an issuer **identity** with an array of claim topics: ```solidity function addTrustedIssuer(IClaimIssuer issuer, uint256[] topics); function updateIssuerClaimTopics(IClaimIssuer issuer, uint256[] topics); function removeTrustedIssuer(IClaimIssuer issuer); ``` Provider provisioning calls `addTrustedIssuer(providerIdentity, [firstTopicId])`. Subsequent topic mutations call `updateIssuerClaimTopics(providerIdentity, [...])` to extend or shrink the topic array. Whole-provider revocation calls `removeTrustedIssuer(providerIdentity)` and soft-deletes the provider row. Per-topic granularity in DALP maps to per-element changes in the on-chain topic array. The provider's claim-issuer identity stays on-chain for the lifetime of the provider record (and beyond, the contract is not destroyed on revocation), so historical claims previously issued by the provider continue to verify against the same issuer address. Subject mapping happens at intake time: * Sumsub, Jumio, Onfido, Persona, Trulioo, and Veriff applicant intake, plus Middesk business intake, map the provider subject to a DALP identity address. * ComplyAdvantage search intake maps a monitored person or company search to its DALP identity. * Elliptic wallet intake maps the monitored wallet to its DALP identity. ## Inbound contract [#inbound-contract] Each provider exposes **one webhook URL** for the tenant to paste into the provider dashboard. The URL is shared by every topic attached to the provider. Inbound webhooks must arrive on that URL with the provider authentication material set. DALP verifies the request against the secret or allowlist configured during onboarding. Signature handling is provider-specific: | Provider | Webhook authentication | Header or network source | | --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | Sumsub | HMAC over raw body | `x-payload-digest`, `x-payload-digest-alg` | | Sumsub AML | HMAC over raw body | `x-payload-digest`, `x-payload-digest-alg` | | Sumsub KYT | HMAC over raw body | `x-payload-digest`, `x-payload-digest-alg` | | ComplyAdvantage | HMAC-SHA256 digest | `x-complyadvantage-signature` | | Elliptic | HMAC-SHA256 digest | `x-elliptic-signature` | | Jumio | Basic Auth + IP allowlist | `Authorization: Basic …` and callback source IP | | Middesk | HMAC-SHA256 over raw body | `X-Middesk-Signature-256` | | Onfido | HMAC-SHA256 over raw body | `X-SHA2-Signature` | | Persona | HMAC-SHA256 over `${timestamp}.${rawBody}` | `Persona-Signature` timestamp and hexadecimal signature values (space-separated sets accepted during key rotation) | | Trulioo | HMAC-SHA256 over raw body | `x-trulioo-signature` | | Veriff | HMAC-SHA256 over raw body | `X-HMAC-SIGNATURE` | Sumsub's dashboard webhook manager documents the HMAC digest headers and the raw-payload comparison requirement in its [Webhook manager guide](https://docs.sumsub.com/docs/webhook-manager). Elliptic documents alert webhooks and signature validation in [Rescreening and Alerting](https://developers.elliptic.co/docs/rescreening-and-alerting). For a brand-new provider event, DALP enforces a replay window of at most 5 minutes between the body's signed timestamp and arrival. DALP also applies idempotency on the provider's event identifier and rejects out-of-order events relative to the latest applied state for that subject and topic. If a matching event is already stored and still pending, DALP can dispatch it again under the same idempotency record so a crashed first delivery can resume. Events targeting a topic that is missing or revoked on the provider are rejected as `rejected_topic_mismatch` rather than reaching the claim-authoring path. **Dual-secret rotation grace.** When you rotate a webhook signing secret in the dapp, the new secret takes effect immediately while the old one stays valid for a configurable grace window (default 15 minutes, up to 24 hours). During that window DALP accepts a signature from either secret, so events the provider has already enqueued under the old secret are not lost. After the window expires the old secret stops working. ## Outbound contract [#outbound-contract] Each provider receives one paste-back URL of the form: ```text /webhooks/compliance//:providerId/:urlToken ``` The provider identifier scopes the URL to one tenant provider record; every topic attached to the provider is multiplexed onto the same URL. The URL token is a non-guessable UUID generated when the tenant creates the provider. HMAC remains the primary authentication mechanism; the token limits accidental cross-provider delivery and adds a defence-in-depth layer against URL leaks. Raw provider payloads are retained for audit so a regulator can reconstruct the full chain of custody from raw event to on-chain claim. Decision-driving fields (verdict state, severity, subject reference, claim topic, applied timestamp, outcome) are extracted alongside the raw payload at intake time so audit queries do not need to re-parse historical data. ## Issuer-of-record: the identity, not the EOA [#issuer-of-record-the-identity-not-the-eoa] The on-chain attestor of every compliance-issued claim is the provider's **claim-issuer identity contract address**, never the EOA, never DALP itself, and never the tenant compliance officer. The EOA is the **sender** of the on-chain transaction (and the cryptographic signer of the claim payload), but the claim's `issuer` field is set to the identity contract address. This issuer-of-record rule propagates to downstream consumers of `claims.issuer`: the indexer, the trusted-claim primitive, the per-tenant `IDALPTrustedIssuersRegistry` lookup, and the ERC-3643 compliance evaluation path. The trusted issuers registry checks `isTrustedIssuer(identity)` and `hasClaimTopic(identity, topicId)` on every claim. The EOA never needs to be trusted directly. A regulator audit can identify which provider asserted a given claim, retrieve the original signed webhook payload, and verify the trusted-issuer registration history (add / update / remove) from on-chain events. ## Provisioning sequence [#provisioning-sequence] The provider provisioning workflow performs five on-chain operations in sequence. A durable workflow journal lets a partial failure resume from the last unfinished step: Three idempotency guards (signer `WALLET_ALREADY_EXISTS`, identity factory pre-check, ERC-734 `keyHasPurpose` short-circuit) plus the durable journal handle retries cleanly. The dapp's five-phase provisioning pulse mirrors these steps in real time. ## Webhook intake and claim authoring [#webhook-intake-and-claim-authoring] Inbound provider events flow through a per-`(providerId, subjectKey)` claim-authoring worker that serialises events per subject and looks up the active topic policy before authoring: The claim-authoring worker is keyed on `(providerId, subjectKey)` so concurrent events for different subjects on the same provider proceed in parallel while events for the same subject serialise. Topic-policy lookup happens inside that worker so a topic revoked between event arrival and dispatch is caught before the on-chain transaction. ## Topic mutations and revocation [#topic-mutations-and-revocation] Topic mutations operate against the existing provider's claim-issuer identity. None of them touch the EOA, the identity contract, or the webhook URL: * **Add topic.** `updateIssuerClaimTopics(identity, [...existing, newTopic])`. DALP inserts a new `compliance_provider_topics` row with `status=active`. The dapp Add Topic dialog drives this from the provider detail page. * **Topic-scoped revoke.** `updateIssuerClaimTopics(identity, [...existing without topic])`. Soft-deletes the topic row (`status=revoked`). The provider stays active for any remaining topics. Revoking the last active topic is rejected. Use whole-provider revoke instead. * **Whole-provider revoke.** `removeTrustedIssuer(identity)`. Soft-deletes the provider row and cascades soft-delete to every topic. Subject mappings persist for audit. In every case the claim-issuer identity contract stays on-chain, so historical claims previously issued by the provider continue to verify against the same `claims.issuer` address. The provider simply loses TIR membership for the revoked topic(s). ## Two-primitive split [#two-primitive-split] ClaimSource and TransferGate stay separate because their subjects and timing differ: * **ClaimSource.** Subject is a persistent identity or wallet. Intake is event-driven (webhooks). Output is standard on-chain claim issuance and revocation. * **TransferGate.** Subject is one specific outbound or inbound transfer. The decision is requested at transfer-initiation time, not in response to a background event. Output is a transfer-time gate, not a persistent claim. Keeping both shapes separate prevents per-transaction decisions from being mixed into the event-driven ClaimSource model. ClaimSource remains the public compliance-provider intake path for persistent identity and wallet subjects. Current DALP compliance-provider integrations support these event families through ClaimSource: * Sumsub identity verdicts * Sumsub AML watchlist monitoring alerts for existing applicants * Sumsub applicant-on-hold monitoring alerts * Sumsub KYT transaction monitoring * ComplyAdvantage entity monitoring alerts * Elliptic wallet monitoring * Jumio identity verdicts * Middesk KYB verdicts, attested to `knowYourBusiness` * Onfido Workflow Studio and classic API identity verdicts, attested to `knowYourCustomer` * Persona inquiry verdicts, attested to `knowYourCustomer` * Trulioo DataVerify identity and business verdicts, attested to `knowYourCustomer` * Veriff hosted identity-verification verdicts, attested to `knowYourCustomer` Travel Rule transfer gating remains a separate per-transfer surface rather than a compliance-provider adapter. A deployment that needs Travel Rule gating should integrate a per-transfer adapter instead of folding that decision into ClaimSource. DALP does not publish a default named Travel Rule provider adapter in the current compliance-provider catalog. [Chainalysis KYT](https://docs.chainalysis.com/) is also not a current DALP compliance-provider adapter. ## See also [#see-also] * [Compliance provider onboarding](/docs/developers/compliance/onboarding-a-provider) * [Rotate provider claim signer key](/docs/operators/runbooks/rotate-provider-claim-signer-key) * [Custody providers](/docs/architects/integrations/custody-providers) * [Supported networks](/docs/architects/integrations/supported-networks)