KYA: know your agent
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
A budget's mandate can require that every agent it pays has been verified by a verification provider. The provider attests, as a signed statement, which named checks an agent's address has passed. Dynamo compares the attested level with the level the mandate requires. This release has one provider interface and one adapter, mock, which runs against a test provider only. KYA is off by default.
Status: Preview.
Levels
Each level names the checks the provider reports as passed. A level is never a score.
| Level | Checks the provider attests |
|---|---|
none | none |
key_bound | key_control: the agent proved it controls the key at its address |
operator_identified | key_control, operator_identity: the party running the agent is identified |
operator_verified | key_control, operator_identity, operator_identity_verified: that identity is verified by the provider |
Require a level in a mandate (owner-api 1.8.0)
Send Dynamo-Version: 1.8.0 and name the lowest level in the mandate:
{ "funding": "none", "capTotal": "5000000", "mandate": { "categories": "*", "maxDepth": 3, "minAgentVerification": "operator_identified" } }
The same field works on POST /owner/v1/budgets/:id/streams (root and child streams), POST /owner/v1/streams/:id/amend and POST /owner/v1/card-agent-programs/fundings (when card agent programs are on). Other routes that take a mandate (budget adoption, child adoption, top-ups) do not accept it in this release; their streams inherit it from a parent that has it. A client not pinned at 1.8.0 is refused as for any unknown field.
The rules:
- It only narrows. A child stream inherits its parent's level and can only
raise it; a lower level is refused (mandate_widen). An amendment can raise the level of a running stream, never lower it.
- Where a level is required, it fails closed. A stream opens, spends or
authorizes a payment only when the serviceNode has a current attestation at or above the strictest level on its path. An agent the provider does not know, an expired attestation, or a provider that is off or unavailable is refused (mandate_verification). Nothing is allocated or billed.
- Where no level is required, nothing changes. The provider is never asked,
and the hop records carry no verification fields.
- The level an agent was admitted at is signed into its hop record
(payeeVerification, payeeVerificationProvider, payeeVerificationAttestation).
minAgentVerification sits beside minPayeeAssurance, the payee's identity level from economic accounts. Each one narrows on its own.
In the SDKs. @dynamoprotocol/sdk 3.3.0 takes the field in a mandate (minAgentVerification: "operator_identified") and reads it back from the core. When it signs its own hop it inherits the field into the child mandate, so the hop's mandateHash matches the one the core writes. It refuses to sign a child that would lower the level. The Python dynamoprotocol client does the same (min_agent_verification is accepted too). Both offline evidence verifiers check the narrowing. The shared vectors identity/valid-agent-verification and identity/agent-verification-lowered give the same verdict in both. A wallet policy (@dynamoprotocol/wallet-policies) cannot express an attested level, so a mandate carrying the field does not compile to one: it is refused as an unknown field.
Check an agent
POST /owner/v1/kya/checks {serviceNode}
→ {serviceNode, status: "attested", governsAdmission: true, level, checks, provider, attestationId, issuer, issuedAt, expiresAt, checkedAt}
GET /owner/v1/kya/agents/:serviceNode the stored attestation (no provider call)
GET /owner/v1/kya the switch state, provider, signer and levels
Dynamo stores an attestation only when it verifies: it is signed by the pinned provider signer, it is about this address, its level has exactly that level's checks, and it is fresh (30 days at most). Admission reads stored attestations only and makes no network call. The scheduler checks stored agents again before their attestations expire. On the multi-tenant tier each tenant's checks are its own: another tenant's check never verifies an agent for you.
In the console, People and payments shows the KYA switch state.
Turn it on (operators)
| Variable | Meaning |
|---|---|
CORE_KYA | off (default) or mock |
CORE_KYA_MOCK_URL | the provider's base URL (https, or http on loopback) |
CORE_KYA_MOCK_API_KEY | a test key, kya_test_<secret>. A kya_live_ or kya_prod_ key in any variable refuses boot (kya_live_key) |
CORE_KYA_MOCK_SIGNER | the address of the provider's attestation signer |
The key is never logged or stored. On the multi-tenant tier KYA serves test-environment tenants only. The provider protocol the adapter speaks is in packages/core-host/src/kya/mock.ts; an offline mock provider for tests is in packages/core-host/src/kya/mock-provider.ts.
Errors
mandate_verification, kya_off, kya_unavailable, kya_subject_unknown.