How Known works

01 Concepts

Credential

An account bound to the holder’s wallet by the holder’s own signature, written by the issuer that verified them. It publishes six claims and a commitment to the encrypted file the issuer keeps. Personal data never goes on chain.

Reliance

One app’s acceptance of one holder: a program-derived account per relier and holder. It exists only with the holder’s signature and the issuer’s price paid from the app’s balance, and it is live only while its credential is active and unexpired.

Policy

What an app accepts: accepted issuers, minimum level, kinds, adult, blocked residences, maximum screening age, maximum price.

Recall

The app’s right to the documents behind a reliance. It opens a recall with a reason; the issuer seals the file to the app’s recall key within its window and records the delivery’s hash on chain. The holder’s ledger shows who asked, why and when it was answered.

Gate

A Token-2022 transfer hook that passes a transfer only between wallets an app relies on, with live credentials.

Ledger

The holder’s view of every reliance on them, what each app paid, and every recall of their file.

The public claims

Level · Kind · Adult · Residence · Screened at · Expires at.

Levels

• Basic: document, liveness, face match, sanctions screening.
• Enhanced: document, liveness, face match, sanctions screening, proof of address.

What the program guarantees

1. A reliance exists only with the holder’s signature and the issuer’s price paid from the relier’s balance.
2. A reliance is live only while its credential is active and unexpired.
3. An issuer cannot withdraw earnings while a recall it owes is past due.
4. Every recall is on chain and on the holder’s ledger.
5. Personal data never goes on chain and leaves the issuer only sealed to a relier’s recall key, on a recorded recall.

02 Relier quickstart

1. Register your app in the relier console: name, domain, and a recall key made in your browser under a password you set. Download the backup file. Publish /.well-known/known.json on your domain naming your authority wallet.
2. Write a policy: the issuers you accept from the directory, the minimum level, kinds, adulthood, blocked residences, the maximum screening age and the most you pay per reliance.
3. Fund your balance in the dollar stablecoin your accepted issuers are paid in.
4. Add the one line. It opens the present sheet; the holder signs once and the promise resolves with the reliance.

npm install @known/sdk

import { known } from "@known/sdk"

known.configure({ siteUrl: "https://useknown.dev", apiUrl: "https://api.useknown.dev" })

button.onclick = async () => {
  const reliance = await known.rely({ policy: "<your policy id>" })
  onboard(reliance.holder, reliance.credential)
}

Read a reliance later, on your server or in the browser:

const reliance = await known.readReliance(relierId, holderWallet)
if (reliance.status === "live") { /* the holder is known to your app */ }

03 Issuer guide

Registration is open, from the issuer console. You set a price per level in a dollar stablecoin from the network’s fee mints, your recall window, and your class. Every app that relies on one of your credentials pays your price into your earnings vault, less the protocol’s share. Withdrawing waits while any recall you owe is past due.

In console mode you prepare a claim for a customer you already verified: the browser computes the commitment to their file, a claim code is made in your browser, and only its public key goes on chain. The holder opens /claim#<code>: the code stays in the URL fragment and their browser, which derives the claim key from it, and they bind the credential to their wallet.

04 Program

known (Anchor) holds the accounts Network, Issuer, Credential, PendingClaim, Relier, Policy, Reliance, Recall. Credentials are addressed by issuer and holder, reliances by relier and holder, so any program reads them inside its own instructions.

• init_network
• register_issuer
• update_issuer
• issue
• prepare_claim
• claim
• cancel_claim
• refresh
• revoke
• register_relier
• set_policy
• fund
• withdraw_balance
• rely
• end_reliance
• open_recall
• answer_recall
• withdraw_earnings

known-gate is the Token-2022 transfer hook: initialize_extra_account_meta_list, execute.

05 SDK

@known/sdk exports known.configure, known.rely, known.readReliance and known.gate.buildTransfer. Call rely from a user gesture so the browser opens its window. It resolves with the existing reliance when the holder is already relied on, and rejects with a KnownSdkError naming the reason when the holder cancels or the app can’t onboard them.

The present sheet speaks known.present.v1 with the window that opened it: it checks the exact origin, the window and the request id, and answers once.

06 Webhooks

Set a URL in the relier console. Each delivery carries X-Known-Signature: the time and an HMAC-SHA256 of the time and the raw body under your secret. Check both before trusting the event; rotate the secret from the console at any time.

• reliance.created
• reliance.ended
• credential.refreshed
• credential.revoked
• credential.expired
• recall.answered

POST https://your-app.example/known/webhook
X-Known-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under your secret>

{ "id": "…", "type": "reliance.created", "timestamp": "…", "data": { … } }

07 API

JSON over HTTPS at https://api.useknown.dev. Console routes take a Sign-In With Solana session as Authorization: Bearer; transaction builders return a v0 transaction for the wallet to sign, and one submit route relays it. The full description is at /openapi.json.

08 Gate guide

1. Hold a Token-2022 mint whose transfer-hook authority is your relier’s wallet.
2. In the relier console, attach the gate to the mint with one of your policies.
3. Initialize the extra account metas, so Token-2022 resolves both owners’ reliances and credentials on every transfer.
4. Test a transfer. It passes only between wallets you rely on with live credentials; a revoked or expired credential stops it at once.