diff --git a/packages/sdk/src/clients/registry.ts b/packages/sdk/src/clients/registry.ts
index cdbe931..57fc665 100644
--- a/packages/sdk/src/clients/registry.ts
+++ b/packages/sdk/src/clients/registry.ts
@@ -21,6 +21,16 @@ export class RegistryClient extends BaseContractClient {
     return this.writeContract("register_issuer", args, signerPublicKey);
   }
 
+  /**
+   * Registers a buyer on-chain.
+   * Side effect: stores a `Profile` with `role: Buyer` and `verified: true`.
+   *
+   * @param address - The Stellar address to register as a buyer. Must match `signerPublicKey`.
+   * @param metadata - Arbitrary key-value metadata stored alongside the buyer profile.
+   * @param signerPublicKey - The Stellar public key that will sign the transaction. `address.require_auth()` is enforced on-chain.
+   * @returns The transaction hash of the on-chain submission.
+   * @throws If the address is already registered (`AlreadyRegistered`), the transaction simulation fails, or on-chain submission errors.
+   */
   async registerBuyer(
     address: string,
     metadata: Record<string, string>,
@@ -30,6 +40,15 @@ export class RegistryClient extends BaseContractClient {
     return this.writeContract("register_buyer", args, signerPublicKey);
   }
 
+  /**
+   * Checks whether an address is verified in the on-chain registry.
+   * This is a read-only (simulated) call — no on-chain side effects.
+   *
+   * @param address - The Stellar address to check.
+   * @param signerPublicKey - The Stellar public key used to simulate the read call.
+   * @returns `true` if the address is registered and verified, `false` otherwise (does not panic for unknown addresses).
+   * @throws If the simulation fails.
+   */
   async isVerified(address: string, signerPublicKey: string): Promise<boolean> {
     const args = [new Address(address).toScVal()];
     return this.readContract(
@@ -40,6 +59,15 @@ export class RegistryClient extends BaseContractClient {
     );
   }
 
+  /**
+   * Retrieves the full on-chain profile for a registered address.
+   * This is a read-only (simulated) call — no on-chain side effects.
+   *
+   * @param address - The Stellar address to look up.
+   * @param signerPublicKey - The Stellar public key used to simulate the read call.
+   * @returns The parsed {@link Profile} object containing address, role, verified status, and registration timestamp.
+   * @throws If the address is not registered (`NotFound`), the simulation fails, or the return value cannot be parsed.
+   */
   async getProfile(address: string, signerPublicKey: string): Promise<Profile> {
     const args = [new Address(address).toScVal()];
     return this.readContract("get_profile", args, signerPublicKey, (val) =>
@@ -47,6 +75,15 @@ export class RegistryClient extends BaseContractClient {
     );
   }
 
+  /**
+   * Revokes an address's verified status on-chain. Admin only.
+   * Side effect: sets `verified: false` on the profile. The address can no longer participate in new invoice transactions.
+   *
+   * @param address - The Stellar address to revoke.
+   * @param signerPublicKey - The Stellar public key that will sign the transaction. Must be the registry admin.
+   * @returns The transaction hash of the on-chain submission.
+   * @throws If the signer is not the admin, the address is not registered, the transaction simulation fails, or on-chain submission errors.
+   */
   async revoke(address: string, signerPublicKey: string): Promise<string> {
     const args = [new Address(address).toScVal()];
     return this.writeContract("revoke", args, signerPublicKey);