feat(types): expose principal + attestation type surface (experimental)

Adds the agent-layer type surface to @hashlock-tech/sdk so SDK
consumers get TypeScript autocomplete and shape-validation for
principal attestation, agent instance metadata, KYC tier filters,
and hideIdentity flags today. GraphQL wire-through to the Cayman
backend lands in a later release once the backend accepts
PrincipalAttestationInput and AgentInstanceInput.

New
- src/principal.ts: KycTier + PrincipalType + PrincipalAttestation
  + AgentInstance interfaces, KYC_TIER_RANK ordering, meetsKycTier
  helper. Mirror of the canonical types in
  @hashlock-tech/intent-schema, duplicated as plain TS interfaces
  per the SDK pattern (no zod runtime dep).

Updated
- src/types.ts
  - RFQ: attestationTier, attestationBlindId, minCounterpartyTier
    response fields (all optional + nullable)
  - Quote: attestationTier, attestationBlindId
  - Trade: initiatorAttestationTier, counterpartyAttestationTier
  - CreateRFQInput: attestation, agentInstance, minCounterpartyTier,
    hideIdentity inputs
  - SubmitQuoteInput: attestation, agentInstance, hideIdentity
  - FundHTLCInput: attestation, agentInstance
  All marked EXPERIMENTAL in doc comments — accepted by SDK,
  dropped by current GraphQL mutation strings, wire-through
  pending Cayman backend update.

- src/index.ts: re-export new principal helpers + type aliases

Tests
- src/__tests__/hashlock.test.ts gains a "principal + attestation
  types" suite covering:
    * KycTier ordering and meetsKycTier comparisons
    * createRFQ with full agent payload (attestation + agentInstance
      + minCounterpartyTier + hideIdentity)
    * submitQuote with market-maker attestation
    * fundHTLC with funding-party attestation
    * backward compatibility: human calls without attestation
      remain unchanged
    * RFQ response parsing with attestationTier fields
- All 25 tests pass (19 existing + 6 new); build is clean

Not included
- No changes to src/hashlock.ts GraphQL mutation strings. The new
  fields ride through the input interfaces but are silently
  omitted by the variables serialization until the backend schema
  accepts them.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: BarisSozen

src/__tests__/hashlock.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { HashLock } from '../hashlock.js';
 import { GraphQLError, AuthError, NetworkError } from '../errors.js';
+import { meetsKycTier, KYC_TIER_RANK } from '../principal.js';
+import type { PrincipalAttestation } from '../principal.js';
 
 function mockFetch(data: unknown, status = 200) {
   return vi.fn().mockResolvedValue({
@@ -228,4 +230,168 @@ describe('HashLock SDK', () => {
       expect(callArgs[1].headers['Authorization']).toBe('Bearer new-token');
     });
   });
+
+  // ─── Principal / Attestation (EXPERIMENTAL) ─────────────
+
+  describe('principal + attestation types', () => {
+    const validAttestation: PrincipalAttestation = {
+      principalId: 'pr_acme_001',
+      principalType: 'INSTITUTION',
+      tier: 'INSTITUTIONAL',
+      blindId: 'ag_5g7k92bq',
+      issuedAt: Math.floor(Date.now() / 1000),
+      expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      proof: '0xdeadbeef',
+    };
+
+    it('KycTier helpers rank tiers correctly', () => {
+      expect(KYC_TIER_RANK.NONE).toBe(0);
+      expect(KYC_TIER_RANK.INSTITUTIONAL).toBe(4);
+      expect(meetsKycTier('ENHANCED', 'STANDARD')).toBe(true);
+      expect(meetsKycTier('BASIC', 'ENHANCED')).toBe(false);
+    });
+
+    it('createRFQ accepts attestation + agentInstance + tier filters', async () => {
+      const rfq = {
+        id: 'rfq-agent',
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'SELL',
+        amount: '5.0',
+        status: 'ACTIVE',
+        isBlind: true,
+        createdAt: '2026-04-11',
+        userId: 'u1',
+        expiresAt: null,
+        quotesCount: 0,
+      };
+      const fetch = mockFetch({ data: { createRFQ: rfq } });
+      const hl = createClient(fetch);
+
+      // Type-level acceptance: the SDK compiles and runs with the
+      // new fields. GraphQL wire-through is a later release.
+      const result = await hl.createRFQ({
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'SELL',
+        amount: '5.0',
+        isBlind: true,
+        attestation: validAttestation,
+        agentInstance: {
+          instanceId: 'ag_5g7k92bq',
+          strategy: 'mm-eth-usdt',
+          version: '1.0.0',
+        },
+        minCounterpartyTier: 'STANDARD',
+        hideIdentity: true,
+      });
+
+      expect(result.id).toBe('rfq-agent');
+    });
+
+    it('submitQuote accepts attestation + agentInstance + hideIdentity', async () => {
+      const quote = {
+        id: 'q-agent',
+        rfqId: 'rfq-1',
+        marketMakerId: 'mm-1',
+        price: '3450',
+        amount: '1.0',
+        status: 'PENDING',
+        createdAt: '2026-04-11',
+        expiresAt: null,
+      };
+      const fetch = mockFetch({ data: { submitQuote: quote } });
+      const hl = createClient(fetch);
+
+      const result = await hl.submitQuote({
+        rfqId: 'rfq-1',
+        price: '3450',
+        amount: '1.0',
+        attestation: validAttestation,
+        agentInstance: { instanceId: 'ag_5g7k92bq' },
+        hideIdentity: true,
+      });
+
+      expect(result.id).toBe('q-agent');
+    });
+
+    it('fundHTLC accepts attestation + agentInstance', async () => {
+      const fetch = mockFetch({
+        data: { fundHTLC: { tradeId: 't-1', txHash: '0xabc', status: 'PENDING' } },
+      });
+      const hl = createClient(fetch);
+
+      const result = await hl.fundHTLC({
+        tradeId: 't-1',
+        txHash: '0xabc',
+        role: 'INITIATOR',
+        chainType: 'evm',
+        attestation: validAttestation,
+        agentInstance: { instanceId: 'ag_5g7k92bq' },
+      });
+
+      expect(result.status).toBe('PENDING');
+    });
+
+    it('existing calls without attestation still work (backward compat)', async () => {
+      const rfq = {
+        id: 'rfq-human',
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'BUY',
+        amount: '1.0',
+        status: 'ACTIVE',
+        isBlind: false,
+        createdAt: '2026-04-11',
+        userId: 'u1',
+        expiresAt: null,
+        quotesCount: 0,
+      };
+      const fetch = mockFetch({ data: { createRFQ: rfq } });
+      const hl = createClient(fetch);
+
+      const result = await hl.createRFQ({
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'BUY',
+        amount: '1.0',
+      });
+
+      expect(result.id).toBe('rfq-human');
+    });
+
+    it('parses attestation tier fields from RFQ responses', async () => {
+      const rfq = {
+        id: 'rfq-1',
+        userId: 'u1',
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'SELL',
+        amount: '5',
+        status: 'ACTIVE',
+        isBlind: true,
+        createdAt: '2026-04-11',
+        expiresAt: null,
+        quotesCount: 0,
+        attestationTier: 'INSTITUTIONAL',
+        attestationBlindId: 'ag_5g7k92bq',
+        minCounterpartyTier: 'STANDARD',
+      };
+      const fetch = mockFetch({ data: { createRFQ: rfq } });
+      const hl = createClient(fetch);
+
+      const result = await hl.createRFQ({
+        baseToken: 'ETH',
+        quoteToken: 'USDT',
+        side: 'SELL',
+        amount: '5',
+      });
+
+      // Type is `KycTier | null | undefined`; the JSON response is
+      // assignable (TS response types are a loose projection).
+      expect(result.attestationTier).toBe('INSTITUTIONAL');
+      expect(result.attestationBlindId).toBe('ag_5g7k92bq');
+      expect(result.minCounterpartyTier).toBe('STANDARD');
+    });
+  });
 });

src/index.ts

@@ -1,3 +1,10 @@
 export { HashLock, MAINNET_ENDPOINT } from './hashlock.js';
 export { HashLockError, GraphQLError, NetworkError, AuthError } from './errors.js';
 export type * from './types.js';
+export { KYC_TIER_RANK, meetsKycTier } from './principal.js';
+export type {
+  KycTier,
+  PrincipalType,
+  PrincipalAttestation,
+  AgentInstance,
+} from './principal.js';

src/principal.ts

@@ -0,0 +1,64 @@
+// ─── Principal + Attestation Types ───────────────────────────
+//
+// Mirror of the canonical types defined in @hashlock-tech/intent-schema.
+// Duplicated here as plain TS interfaces (the SDK pattern) so the
+// SDK has no runtime dependency on the intent-schema package.
+//
+// Keep these shapes in sync with:
+//   @hashlock-tech/intent-schema → src/types/principal.ts
+//
+// EXPERIMENTAL: these fields are defined at the SDK type surface so
+// agents can construct the right shape today. GraphQL wire-through
+// to the Cayman backend happens in a later release once the backend
+// schema is updated to accept PrincipalAttestationInput and
+// AgentInstanceInput. Until then, passing these fields to SDK
+// methods is a no-op at the network layer.
+
+export type KycTier =
+  | 'NONE'
+  | 'BASIC'
+  | 'STANDARD'
+  | 'ENHANCED'
+  | 'INSTITUTIONAL';
+
+export type PrincipalType = 'HUMAN' | 'INSTITUTION' | 'AGENT';
+
+export interface PrincipalAttestation {
+  /** Opaque identifier (hash) of the KYC'd principal entity */
+  principalId: string;
+  /** Kind of principal backing the intent/order */
+  principalType: PrincipalType;
+  /** Attested compliance tier of the principal */
+  tier: KycTier;
+  /** Rotating pseudonym visible to counterparty (omit for post-match attribution only) */
+  blindId?: string;
+  /** Attestation issuance time (unix seconds) */
+  issuedAt: number;
+  /** Attestation expiration (unix seconds) */
+  expiresAt: number;
+  /** Opaque proof (signature or ZK proof) verified by the HashLock gateway */
+  proof: string;
+}
+
+export interface AgentInstance {
+  /** Stable identifier for the agent instance */
+  instanceId: string;
+  /** Human-readable strategy label (e.g. "mm-eth-usdc") */
+  strategy?: string;
+  /** Agent software version */
+  version?: string;
+  /** Instance spawn time (unix seconds) */
+  spawnedAt?: number;
+}
+
+export const KYC_TIER_RANK: Record<KycTier, number> = {
+  NONE: 0,
+  BASIC: 1,
+  STANDARD: 2,
+  ENHANCED: 3,
+  INSTITUTIONAL: 4,
+};
+
+export function meetsKycTier(actual: KycTier, required: KycTier): boolean {
+  return KYC_TIER_RANK[actual] >= KYC_TIER_RANK[required];
+}

src/types.ts

@@ -1,3 +1,9 @@
+import type {
+  PrincipalAttestation,
+  AgentInstance,
+  KycTier,
+} from './principal.js';
+
 // ─── Enums ───────────────────────────────────────────────────
 
 export type Side = 'BUY' | 'SELL';
@@ -53,6 +59,12 @@ export interface RFQ {
   createdAt: string;
   quotesCount: number | null;
   quotes: Quote[] | null;
+  /** EXPERIMENTAL: tier the creator attested to (visible, non-leaky) */
+  attestationTier?: KycTier | null;
+  /** EXPERIMENTAL: rotating pseudonym of the creator (blind identity) */
+  attestationBlindId?: string | null;
+  /** EXPERIMENTAL: minimum KYC tier the creator wants in a counterparty */
+  minCounterpartyTier?: KycTier | null;
 }
 
 export interface Quote {
@@ -67,6 +79,10 @@ export interface Quote {
   deliveryDelayHours: number | null;
   collateralBtcSats: string | null;
   isCollateralBacked: boolean;
+  /** EXPERIMENTAL: tier the market maker attested to */
+  attestationTier?: KycTier | null;
+  /** EXPERIMENTAL: blind identity of the market maker */
+  attestationBlindId?: string | null;
 }
 
 export interface Trade {
@@ -81,6 +97,10 @@ export interface Trade {
   price: string;
   status: TradeStatus;
   createdAt: string;
+  /** EXPERIMENTAL: initiator's attested compliance tier */
+  initiatorAttestationTier?: KycTier | null;
+  /** EXPERIMENTAL: counterparty's attested compliance tier */
+  counterpartyAttestationTier?: KycTier | null;
 }
 
 export interface HTLC {
@@ -119,6 +139,18 @@ export interface CreateRFQInput {
   expiresIn?: number;
   /** Hide counterparty identity in blind auction mode */
   isBlind?: boolean;
+  /** EXPERIMENTAL — Principal attestation for agent / institution
+   *  flows. The shape is accepted by the SDK today but is not yet
+   *  sent to the Cayman backend. Wire-through will land in a later
+   *  release once the backend accepts PrincipalAttestationInput. */
+  attestation?: PrincipalAttestation;
+  /** EXPERIMENTAL — Agent instance metadata. See `attestation`. */
+  agentInstance?: AgentInstance;
+  /** EXPERIMENTAL — Minimum KYC tier the counterparty must attest to. */
+  minCounterpartyTier?: KycTier;
+  /** EXPERIMENTAL — Hide blind identity in the solver proof. Requires
+   *  `isBlind: true` or a blind auction context. */
+  hideIdentity?: boolean;
 }
 
 export interface SubmitQuoteInput {
@@ -130,6 +162,12 @@ export interface SubmitQuoteInput {
   amount: string;
   /** Expiration time in seconds */
   expiresIn?: number;
+  /** EXPERIMENTAL — Market maker's principal attestation. */
+  attestation?: PrincipalAttestation;
+  /** EXPERIMENTAL — Agent instance metadata. */
+  agentInstance?: AgentInstance;
+  /** EXPERIMENTAL — Hide blind identity from the RFQ creator. */
+  hideIdentity?: boolean;
 }
 
 export interface FundHTLCInput {
@@ -155,6 +193,10 @@ export interface FundHTLCInput {
   refundTxHex?: string;
   /** Preimage for initiator (kept encrypted server-side) */
   preimage?: string;
+  /** EXPERIMENTAL — Principal attestation of the funding party. */
+  attestation?: PrincipalAttestation;
+  /** EXPERIMENTAL — Agent instance metadata. */
+  agentInstance?: AgentInstance;
 }
 
 export interface ClaimHTLCInput {