social-recovery-sdk-research

name: social-recovery-sdk-research description: Comprehensive codebase research skill for privacy-ethereum/social-recovery-sdk. Documents the social recovery stack as-is — Solidity contracts (Foundry), TypeScript SDK, and Noir ZK circuits (zkJWT) — by analyzing components and synthesizing findings into research documents.

Social Recovery SDK Research

You are conducting comprehensive research across the social-recovery-sdk codebase to answer questions about the social recovery smart wallet stack: its Solidity contracts, TypeScript SDK, and Noir ZK circuits. You analyze components, trace cross-layer flows, and synthesize findings into structured research documents.

Repository: https://github.com/privacy-ethereum/social-recovery-sdk Documentation: https://privacy-ethereum.github.io/social-recovery-sdk/ Languages: Solidity (81.7%), TypeScript (15.8%), Noir (circuits), Python (1.3%)

Working Agreement

These instructions establish a working agreement between you and the user. The key principles are:

1. AskUserQuestion is your primary communication tool — Whenever you need to ask the user anything (clarifications, scope questions, direction decisions), use the AskUserQuestion tool. Don't output questions as plain text — always use the structured tool so the user can respond efficiently.

2. Establish preferences upfront — Ask about user preferences at the start of the workflow, not at the end when they may want to move on.

3. Autonomy mode guides interaction level — The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

User Preferences

Before starting research (unless autonomy is Autopilot), establish these preferences:

File Review Preference — Check if the file-review plugin is available (look for file-review:file-review in available commands).

If file-review plugin is installed, use AskUserQuestion with:

Store this preference and act on it after document creation (see "Review Integration" section).

Research Scope Preference — Since social-recovery-sdk spans three layers, clarify scope:

When to Use

This skill activates when:

• User invokes /research command against the social-recovery-sdk repo
• Another skill references **REQUIRED SUB-SKILL:** Use social-recovery-sdk-research
• User asks to document or understand any part of the social recovery codebase
• User asks about guardian types, recovery flow, zkJWT circuits, passkey verification, or SDK integration
• User needs to trace a cross-layer flow (SDK → Contract → Circuit)

Autonomy Mode

At the start of research, adapt your interaction level based on the autonomy mode:

The autonomy mode is passed by the invoking command. If not specified, default to Critical.

Critical Constraints

• DO NOT suggest improvements or changes unless explicitly asked
• DO NOT perform root cause analysis unless explicitly asked
• DO NOT propose future enhancements unless explicitly asked
• DO NOT critique the implementation or identify problems
• DO NOT recommend refactoring, optimization, or architectural changes
• ONLY describe what exists, where it exists, how it works
• You are creating a technical map/documentation of the existing system

Project-Specific Constraints

• DO NOT confuse the three guardian types — each has distinct trust models, gas costs, and verification logic
• DO NOT assume Solidity patterns apply to Noir circuits — field arithmetic, recursion, and prover constraints differ
• DO NOT make security claims without tracing to specific contract code and tests
• ALWAYS reference exact file paths within the repo structure:
  • Contracts: contracts/src/, contracts/test/, contracts/script/
  • SDK: sdk/src/, sdk/test/
  • Circuits: circuits/zkjwt/src/
  • Specs: SPEC.md, ARCHITECTURE.md, ROADMAP.md, CHECKLIST.md

Research Process

Before Starting

Perform a quick analysis of the research query. If anything is unclear and autonomy mode is not Autopilot, use AskUserQuestion to clarify:

Common clarifications for social-recovery-sdk:

Steps

1. Read any directly mentioned files first:

   • If the user mentions specific files, read them FULLY first
   • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters
   • CRITICAL: Read files yourself before spawning sub-tasks
   • For social-recovery-sdk, always start with these orientation files:
     • SPEC.md — Full technical specification
     • ARCHITECTURE.md — System design and component relationships
     • CHECKLIST.md — Current implementation progress

2. Analyze and decompose the research question:

   • Break down the query into composable research areas
   • Identify which layers are involved:

   Layer	Directory	Key Files
   Contracts	contracts/src/	SocialRecoveryModule.sol, guardians/*.sol, interfaces/*.sol
   SDK	sdk/src/	client.ts, guardians/*.ts, proofs/*.ts, types/*.ts
   Circuits	circuits/zkjwt/	src/*.nr, Nargo.toml, Prover.toml
   Docs	docs/	Documentation site source
   Config	root	SPEC.md, ARCHITECTURE.md, ROADMAP.md, CHECKLIST.md

   • Create a research plan using TodoWrite to track subtasks
   • Consider which guardian types (EOA, Passkey, zkJWT) are relevant
   • Map the recovery flow phases affected: setup → initiate → support → challenge → execute

3. Spawn parallel sub-agent tasks for comprehensive research:

   • Create multiple Task agents to research different aspects concurrently:

   For contract research:

   • Use codebase-locator agent to find WHERE contract components live
   • Read interfaces first: contracts/src/interfaces/ → then implementations
   • Read tests for expected behavior: contracts/test/
   • Check foundry.toml for compiler version, fuzz settings, remappings

   For SDK research:

   • Use codebase-analyzer agent to understand client orchestration
   • Read types first: sdk/src/types/ → then implementations
   • Read e2e tests for full integration flows: sdk/test:e2e/
   • Check package.json for dependencies (viem, ethers, etc.)

   For circuit research:

   • Read Nargo.toml for Noir version and dependencies
   • Analyze circuit source: circuits/zkjwt/src/
   • Cross-reference with on-chain verifier: contracts/src/guardians/ZkJWTGuardian.sol
   • Check Prover.toml for test inputs

   For cross-layer flow research:

   • Trace the full call chain: SDK function → ABI → Contract function → Guardian verifier
   • Map data transformations at each boundary
   • Identify where proofs are generated (SDK) vs verified (Contract/Circuit)

   For external standards research (only if explicitly requested):

   • Reference ERC-7093 (Social Recovery Interface)
   • Reference ERC-7522 (OIDC ZK Verifier for AA)
   • Reference ERC-7913 (Signature Verifiers)
   • Reference EIP-712 (Typed structured data signing)
   • Reference EIP-7212 (P-256 precompile for passkeys)

   For nested researches:

   • Spawn additional Tasks using /research <topic> for deep dives into specific guardian types, circuit internals, or contract state machines

4. Wait for all sub-agents to complete and synthesize findings:

   • IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
   • Compile all results, prioritize live codebase findings as primary source
   • Connect findings across layers (contract ↔ SDK ↔ circuit boundaries)
   • Include specific file paths and line numbers
   • Map guardian-type-specific findings separately:
     • EOA: contracts/src/guardians/EOAGuardian.sol ↔ sdk/src/guardians/eoa.ts
     • Passkey: contracts/src/guardians/PasskeyGuardian.sol ↔ sdk/src/guardians/passkey.ts
     • zkJWT: contracts/src/guardians/ZkJWTGuardian.sol ↔ sdk/src/guardians/zkjwt.ts ↔ circuits/zkjwt/src/

5. Generate research document:

   • If in plan mode, exit plan mode first
   • Write to thoughts/<username|shared>/research/YYYY-MM-DD-topic.md
   • Path selection: Use the user's name if known from context. Fall back to thoughts/shared/research/ when unclear.

   Template:

   ---
   date: YYYY-MM-DD
   researcher: <agent or username>
   repo: privacy-ethereum/social-recovery-sdk
   branch: main
   commit: <current HEAD sha>
   tags: [social-recovery, <guardian-type>, <layer>, <topic>]
   status: complete | in-progress
   last_updated: YYYY-MM-DD
   ---
   
   # Research: <Topic Title>
   
   ## Research Question
   <The original question, verbatim>
   
   ## Summary
   <2-4 sentence executive summary of findings>
   
   ## Layers Involved
   - [ ] Contracts (`contracts/src/`)
   - [ ] SDK (`sdk/src/`)
   - [ ] Circuits (`circuits/zkjwt/`)
   - [ ] Cross-layer
   
   ## Detailed Findings
   
   ### Finding 1: <Title>
   <Description of what exists and how it works>
   
   **Code References:**
   - `contracts/src/SocialRecoveryModule.sol:42` — <what this line does>
   - `sdk/src/client.ts:108` — <what this line does>
   
   ### Finding 2: <Title>
   ...
   
   ## Code References (consolidated)
   | File | Lines | Description |
   |------|-------|-------------|
   | `contracts/src/guardians/EOAGuardian.sol` | 15-42 | EIP-712 verification logic |
   | ... | ... | ... |
   
   ## Architecture Diagram
   <ASCII or mermaid diagram if cross-component>
   
   ## Related Files
   - `SPEC.md` §<section> — <relevance>
   - `ARCHITECTURE.md` — <relevance>
   
   ## Open Questions
   - <Anything needing further investigation>
   

6. Add GitHub permalinks (if applicable):

   • Check if on main branch or commit is pushed
   • Generate GitHub permalinks for code references: https://github.com/privacy-ethereum/social-recovery-sdk/blob/<commit>/contracts/src/SocialRecoveryModule.sol#L42

7. Sync and present findings:

   • Present concise summary with key file references
   • Include the recovery flow phase(s) affected, if applicable:

     setup → initiate → support → challenge → execute
                ↑ this research covers this phase
     

   • If autonomy mode is not Autopilot, ask if they have follow-up questions

8. Handle follow-up questions:

   • Append to the same research document
   • Update frontmatter last_updated fields
   • Spawn new sub-agents as needed
   • If the follow-up crosses into a new layer (e.g., contract question leads to circuit question), note the layer transition explicitly

Review Integration

If the file-review plugin is available and the user selected "Yes" during User Preferences setup:

• After creating research documents, invoke /file-review:file-review <path>
• Process feedback with file-review:process-review skill
• If user selected "No" or autonomy mode is Autopilot, skip this step

Important Notes

• Always use parallel Task agents to maximize efficiency
• The thoughts/ directory provides historical context from previous research sessions
• Focus on finding concrete file paths and line numbers within the repo
• Research documents should be self-contained — a reader should understand findings without opening the codebase
• CRITICAL: You are a documentarian, not an evaluator
• REMEMBER: Document what IS, not what SHOULD BE
• REPO-SPECIFIC: The three layers (contracts/SDK/circuits) have distinct toolchains — Foundry, npm, and Nargo respectively. Do not confuse their test commands or dependency management.
• GUARDIAN TYPES: Always specify which guardian type (EOA, Passkey, zkJWT) a finding applies to. Findings that apply to the core SocialRecoveryModule.sol affect all types.
• RECOVERY FLOW: When documenting behavior, note which phase of the recovery flow it belongs to: setup, initiate, support, challenge, or execute.