KYC tiers & data protection

KYC at Guild has three tiers. Each one unlocks more of the platform; each one demands more from the user; each one stores more sensitive data, with stronger protections.

The three tiers

Tier	What the user gives	What unlocks
Tier 1	Phone number + SMS OTP	Receive payments to wallet, browse and apply to jobs, basic dashboard.
Tier 2	Profile data (trade/business, location, languages) + payout bank account	Send withdrawals to bank, higher rank in matching, send job postings (employers).
Tier 3	BVN + NIN + address verification	Higher transaction limits, eligible for lender consent reads, full product surface.

A user can stop at any tier. Most Job Seekers move to Tier 2 in the first week (the day they want to withdraw earnings). Tier 3 is typically reached when a user opts into the credit pathway with a partner lender.

Tier 1 — phone + OTP

The minimum.

What we collect	Where it sits	Encrypted?
Phone number (E.164)	`identity.users.phone`	No
First name	`identity.users.first_name`	No
City	`identity.users.city`	No
Preferred language	`identity.users.language`	No
Actor role (JOB_SEEKER / TRADER / EMPLOYER)	`identity.users.actor_role`	No
OTP (temporary)	Redis, short TTL	No (ephemeral)

The phone number is the identity anchor. We don’t encrypt it because we need it for routing every inbound (voice, WhatsApp, SMS, web login). Encryption of the identity anchor would force decryption on every login lookup; the cost would be enormous for marginal security gain when the attacker who has database access already has the phone number. The first name is unencrypted because it shows up in every greeting (“Welcome back, Musa”) and would need to be decrypted on every read.

Tier 2 — profile + payout

The unlock for receiving real money to your own bank.

What we collect	Where it sits	Encrypted?
Trade / business type	per-actor schema	No
Tenure (years in business)	per-actor schema	No
Daily volume band (trader)	per-actor schema	No
Skills / categories (Job Seeker)	per-actor schema	No
Languages spoken	per-actor schema	No
Bank code + masked account number	`identity.payout_destinations`	Account number partially redacted
Account name (from OPay name lookup)	`identity.payout_destinations.account_name`	No
Bank account verification timestamp	`identity.payout_destinations.verified_at`	No

Account numbers are stored with the last four visible (••••3911) so we can display them in user-facing surfaces without exposing the full number on every read. The full number is needed only when initiating a payout; we look it up by user ID at that moment, decrypt if needed, fire the payout, and don’t surface it elsewhere.

Tier 3 — BVN + NIN + address

The unlock for lender consent and the full transactional surface.

What we collect	Where it sits	Encrypted?
BVN	`identity.kyc_records.encrypted_payload`	Yes — envelope
NIN	`identity.kyc_records.encrypted_payload`	Yes — envelope
Last name	`identity.kyc_records.encrypted_payload`	Yes — envelope
Middle name (if any)	`identity.kyc_records.encrypted_payload`	Yes — envelope
Date of birth	`identity.kyc_records.encrypted_payload`	Yes — envelope
Gender	`identity.kyc_records.encrypted_payload`	Yes — envelope
Email	`identity.kyc_records.encrypted_payload`	Yes — envelope
BVN-registered phone (if different)	`identity.kyc_records.encrypted_payload`	Yes — envelope
Full address	`identity.kyc_records.encrypted_payload`	Yes — envelope
Verification timestamps (BVN, NIN, address)	`identity.kyc_records` (separate columns)	No

Verification timestamps and verification flags live as separate columns so we can query “has this user been BVN-verified” without decrypting. The actual BVN, NIN, and personal identifiers live inside an encrypted JSON blob.

The envelope encryption

Provided by @guild/crypto. Uses XChaCha20-Poly1305 through sodium-native (Node’s bindings for libsodium).

// Pseudocode
import sodium from 'sodium-native';

const MASTER_KEY = Buffer.from(process.env.MASTER_KEY_V1, 'base64'); // 32 bytes

function encryptKycPayload(userId: string, plaintext: object): EncryptedBlob {
  const nonce = Buffer.alloc(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
  sodium.randombytes_buf(nonce);

  const aad = Buffer.from(userId, 'utf8'); // bound to user ULID
  const plaintextBuf = Buffer.from(JSON.stringify(plaintext), 'utf8');
  const cipherBuf = Buffer.alloc(plaintextBuf.length + sodium.crypto_aead_xchacha20poly1305_ietf_ABYTES);

  sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
    cipherBuf, plaintextBuf, aad, null, nonce, MASTER_KEY
  );

  return {
    keyVersion: 'v1',
    nonce: nonce.toString('base64'),
    ciphertext: cipherBuf.toString('base64')
  };
}

Why XChaCha20-Poly1305

Algorithm	Why we picked it
XChaCha20	Stream cipher, faster than AES on commodity hardware without AES-NI. Extended-nonce variant means we can use random 192-bit nonces without collision concerns.
Poly1305	MAC. Provides authenticated encryption (AEAD). Tamper detection.
sodium-native	Mature C library bindings. Constant-time implementations. Industry-trusted.

The AAD binding

The aad (additional authenticated data) parameter binds the ciphertext to the user’s ULID. If an attacker swaps user A’s encrypted blob into user B’s record, decryption with user B’s ULID as AAD will fail with an authentication error. This is a defence against a scenario where someone with database write access tries to “move” a KYC record from one account to another. The cryptography rejects the move.

Key version field

The encrypted blob includes a keyVersion field. When we rotate the master key, we re-encrypt KYC payloads with the new key over a rolling window. Old blobs with keyVersion: v1 are decryptable until the rotation completes; new blobs use v2. The rotation is transparent to application code.

How a Tier 3 verification flows

The BVN never sits in our database in plaintext. The verification partner sees it momentarily (over TLS). We never log it. The verification result and the encrypted record persist; the raw BVN ages out of our memory the instant the request handler returns.

When KYC data is decrypted

Three legitimate triggers:

A user request to view their own KYC data. They authenticated; they’re entitled to see what we hold. The decryption happens in the request handler and the data is sent over TLS to the user; not logged.
A re-verification (e.g., periodic NIBSS or partner refresh). The decryption happens, the partner call fires with the data, we update the verification timestamp.
A regulatory request for the data, with proper authority. The decryption happens manually under audit. Logged in channel_audit with a system-actor entry.

The application code does not surface decrypted KYC fields elsewhere. There’s no “show me a list of all BVNs in the system” function. The decrypt helper is scoped at the call site.

When KYC data is anonymised

When a user invokes their right to erasure (NDPR-compliant data deletion):

The encrypted KYC payload is deleted from identity.kyc_records.
The user’s identity.users row is anonymised — phone becomes a placeholder, first name becomes a placeholder, all personally-identifying columns are replaced.
The user’s audit rows (channel_audit, payments_audit) persist with the anonymised user ID.
The user receives a confirmation.

This preserves the audit integrity (the events are still there) while removing the personal link. A future regulatory request to “tell us what this person did” wouldn’t be answerable, which is the user’s intent in invoking erasure.

The master key

A 32-byte key. Lives in environment variables on the VPS, never in the database. Backed up to a sealed file on the operations team’s password manager. Rotated annually under a documented procedure. The day-to-day risk model: a database leak alone yields ciphertext blobs that cannot be decrypted. To decrypt, an attacker would need both the database AND the host’s environment (or the password manager). The “and” is the critical security property.

What we don’t ask for

A few things you might expect, that we deliberately skip:

Selfie / facial verification at v1. The BVN + NIN match against the partner database is the live-person check. Adding selfie liveness is on the roadmap for higher-tier verification but isn’t in scope at v1.
Document uploads (ID card photos) for Tier 1 or Tier 2. Only for Tier 3, where we accept utility bills for address verification.
Social network OAuth. Guild doesn’t depend on Google / Facebook / Apple identity. The phone number is the anchor.
Biometrics on-device. Out of scope.

Audit ledger

The permanent record alongside the encrypted-PII story.

NDPR posture

The compliance framing in detail.

Lender consent

What Tier 3 unlocks on the lender side.

Get Started

For Job Seekers

For Traders

For Employers

For Partners

Channels

Standing & the Ledger

Architecture

Security & Trust

KYC tiers & data protection

The three tiers

Tier 1 — phone + OTP

Tier 2 — profile + payout

Tier 3 — BVN + NIN + address

The envelope encryption

Why XChaCha20-Poly1305

The AAD binding

Key version field

How a Tier 3 verification flows

When KYC data is decrypted

When KYC data is anonymised

The master key

What we don’t ask for

What to read next

Audit ledger

NDPR posture

Lender consent

​The three tiers

​Tier 1 — phone + OTP

​Tier 2 — profile + payout

​Tier 3 — BVN + NIN + address

​The envelope encryption

​Why XChaCha20-Poly1305

​The AAD binding

​Key version field

​How a Tier 3 verification flows

​When KYC data is decrypted

​When KYC data is anonymised

​The master key

​What we don’t ask for

​What to read next

Audit ledger

NDPR posture

Lender consent

The three tiers

Tier 1 — phone + OTP

Tier 2 — profile + payout

Tier 3 — BVN + NIN + address

The envelope encryption

Why XChaCha20-Poly1305

The AAD binding

Key version field

How a Tier 3 verification flows

When KYC data is decrypted

When KYC data is anonymised

The master key

What we don’t ask for

What to read next