Add comprehensive NatSpec docs, security tests, and CI tooling

Security assessment improvements based on Trail of Bits guidelines:

- Add complete NatSpec documentation to KYAIdentityResolver and
  KYACapabilityResolver contracts including all functions, events,
  errors, and state variables
- Add 5 new test cases: whitelist toggle behavior, admin transfer
  overwrites, multiple capabilities per identity, attester removal
  doesn't affect existing attestations, cross-schema refUID validation
- Add Slither static analysis GitHub Actions workflow
- Add SDK schema sync script to auto-populate UIDs from deployments
- Add hardhat-gas-reporter for gas benchmarking
- Document permissionless mode security risks in README
- Fix hardhat config to handle malformed private keys gracefully

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: fotescodev

.github/workflows/security.yml

@@ -0,0 +1,62 @@
+name: Security Analysis
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/contracts/**'
+  pull_request:
+    paths:
+      - 'packages/contracts/**'
+
+jobs:
+  slither:
+    name: Slither Static Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: packages/contracts
+
+      - name: Compile contracts
+        run: npm run compile
+        working-directory: packages/contracts
+
+      - name: Run Slither
+        uses: crytic/slither-action@v0.4.0
+        id: slither
+        with:
+          target: packages/contracts
+          sarif: results.sarif
+          fail-on: high
+          slither-args: --filter-paths "node_modules|test" --exclude-dependencies
+
+      - name: Upload Slither SARIF report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: slither-sarif-report
+          path: results.sarif
+          retention-days: 30
+
+      - name: Upload SARIF to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: results.sarif

README.md

@@ -249,6 +249,23 @@ The deploy script will:
 - **2-step admin transfer** — admin privileges require `transferAdmin` + `acceptAdmin` to prevent accidental transfers
 - **Parent validation** — capabilities are rejected if the referenced identity is revoked or expired
 
+### Permissionless Mode Considerations
+
+When `whitelistEnabled=false` on the `KYAIdentityResolver`, anyone can create identity attestations. This permissionless mode carries important risks:
+
+**Risks:**
+- **Spam attestations** — Malicious actors can flood the system with garbage attestations, consuming on-chain storage and indexer resources
+- **Agent address squatting** — Bad actors may claim agent addresses before legitimate owners, blocking future registrations (since one identity per agent is enforced)
+- **DoS via mapping pollution** — Excessive attestations can degrade lookup performance and increase costs for legitimate users
+
+**Mitigations:**
+- Keep `whitelistEnabled=true` for production deployments
+- Only whitelist trusted attesters who have been vetted
+- Implement rate limiting at the application layer (e.g., in your backend or SDK wrapper)
+- Monitor attestation patterns for suspicious activity
+
+**Recommendation:** Always enable the attester whitelist for mainnet deployments. Permissionless mode should only be used for testing or controlled environments.
+
 ### Reporting Vulnerabilities
 
 This is alpha software. **Do not use in production.**

packages/contracts/contracts/KYACapabilityResolver.sol

@@ -5,22 +5,49 @@ import {SchemaResolver} from "@ethereum-attestation-service/eas-contracts/contra
 import {IEAS, Attestation} from "@ethereum-attestation-service/eas-contracts/contracts/IEAS.sol";
 
 /// @title KYACapabilityResolver
-/// @notice Resolver for KYA-Capability attestations. Validates that the referenced
-///         parent attestation is a valid, non-revoked, non-expired KYA-Identity.
+/// @author KYA Protocol
+/// @notice Resolver for KYA-Capability attestations that validates parent identity references
+/// @dev Implements SchemaResolver to enforce capability→identity linking.
+///      Key invariants:
+///      - Every capability must reference a valid KYA-Identity via refUID
+///      - Parent identity must use the correct schema (identitySchemaUID)
+///      - Parent identity must not be revoked
+///      - Parent identity must not be expired
+///      This is a view-only resolver (no state modifications in onAttest)
 contract KYACapabilityResolver is SchemaResolver {
+    /// @notice The schema UID that parent identity attestations must match
+    /// @dev Set at deployment and cannot be changed (immutable)
     bytes32 public immutable identitySchemaUID;
 
+    /// @notice Thrown when refUID is zero or parent schema doesn't match identity schema
     error InvalidParentIdentity();
+
+    /// @notice Thrown when the parent identity attestation has been revoked
     error ParentIdentityRevoked();
+
+    /// @notice Thrown when the parent identity attestation has expired
     error ParentIdentityExpired();
 
+    /// @notice Initializes the resolver with EAS address and identity schema reference
+    /// @param eas The EAS contract address this resolver integrates with
+    /// @param _identitySchemaUID The schema UID that valid parent identities must have
     constructor(
         IEAS eas,
         bytes32 _identitySchemaUID
     ) SchemaResolver(eas) {
         identitySchemaUID = _identitySchemaUID;
     }
 
+    /// @notice Validates a capability attestation references a valid parent identity
+    /// @dev Called by EAS during attestation creation. This is a view function
+    ///      (no state modifications). Validation order:
+    ///      1. Require non-zero refUID (must reference parent)
+    ///      2. Fetch parent attestation from EAS
+    ///      3. Validate parent uses identity schema
+    ///      4. Validate parent is not revoked
+    ///      5. Validate parent is not expired
+    /// @param attestation The capability attestation being created
+    /// @return True if attestation should be accepted, reverts otherwise
     function onAttest(
         Attestation calldata attestation,
         uint256 /* value */
@@ -54,6 +81,10 @@ contract KYACapabilityResolver is SchemaResolver {
         return true;
     }
 
+    /// @notice Handles capability attestation revocation
+    /// @dev Always returns true - no additional validation needed for revocation.
+    ///      Capabilities can be freely revoked by their attesters.
+    /// @return True to allow the revocation to proceed
     function onRevoke(
         Attestation calldata,
         uint256 /* value */

packages/contracts/contracts/KYAIdentityResolver.sol

@@ -5,30 +5,87 @@ import {SchemaResolver} from "@ethereum-attestation-service/eas-contracts/contra
 import {IEAS, Attestation} from "@ethereum-attestation-service/eas-contracts/contracts/IEAS.sol";
 
 /// @title KYAIdentityResolver
-/// @notice Resolver for KYA-Identity attestations. Enforces one identity per agent
-///         address and validates owner is non-zero. Supports optional attester whitelist.
+/// @author KYA Protocol
+/// @notice Resolver for KYA-Identity attestations that enforces identity registration rules
+/// @dev Implements SchemaResolver to validate attestations during creation and revocation.
+///      Key invariants:
+///      - One identity per agent address (prevents duplicate registrations)
+///      - Non-zero owner and agent addresses required
+///      - Optional attester whitelist for permissioned mode
+///      - 2-step admin transfer to prevent accidental lockout
 contract KYAIdentityResolver is SchemaResolver {
+    /// @notice Maps agent addresses to their identity attestation UIDs
+    /// @dev Zero value indicates no identity registered for that agent
     mapping(address => bytes32) public agentToIdentity;
+
+    /// @notice Maps addresses to their attester authorization status
+    /// @dev Only checked when whitelistEnabled is true
     mapping(address => bool) public authorizedAttesters;
+
+    /// @notice Current admin address with privileged access
     address public admin;
+
+    /// @notice Pending admin for 2-step transfer process
     address public pendingAdmin;
+
+    /// @notice Whether attester whitelist is enforced
+    /// @dev When false, any address can create attestations (permissionless mode)
     bool public whitelistEnabled;
 
+    /// @notice Emitted when a new agent identity is registered
+    /// @param agent The agent address that was registered
+    /// @param uid The attestation UID for the identity
     event IdentityRegistered(address indexed agent, bytes32 uid);
+
+    /// @notice Emitted when an agent identity is revoked
+    /// @param agent The agent address that was revoked
+    /// @param uid The attestation UID that was revoked
     event IdentityRevoked(address indexed agent, bytes32 uid);
+
+    /// @notice Emitted when an attester is added to the whitelist
+    /// @param attester The address added as authorized attester
     event AttesterAdded(address indexed attester);
+
+    /// @notice Emitted when an attester is removed from the whitelist
+    /// @param attester The address removed from authorized attesters
     event AttesterRemoved(address indexed attester);
+
+    /// @notice Emitted when whitelist enforcement is toggled
+    /// @param enabled The new whitelist state
     event WhitelistToggled(bool enabled);
+
+    /// @notice Emitted when admin transfer is initiated
+    /// @param currentAdmin The current admin initiating the transfer
+    /// @param pendingAdmin The proposed new admin
     event AdminTransferStarted(address indexed currentAdmin, address indexed pendingAdmin);
+
+    /// @notice Emitted when admin transfer is completed
+    /// @param previousAdmin The outgoing admin
+    /// @param newAdmin The new admin who accepted the transfer
     event AdminTransferred(address indexed previousAdmin, address indexed newAdmin);
 
+    /// @notice Thrown when a non-whitelisted attester tries to create attestation
     error UnauthorizedAttester();
+
+    /// @notice Thrown when trying to register an identity for an already-registered agent
     error AgentAlreadyRegistered();
+
+    /// @notice Thrown when owner address is zero
     error InvalidOwnerAddress();
+
+    /// @notice Thrown when agent address is zero
     error InvalidAgentAddress();
+
+    /// @notice Thrown when caller is not the admin
     error OnlyAdmin();
+
+    /// @notice Thrown when caller is not the pending admin
     error OnlyPendingAdmin();
 
+    /// @notice Initializes the resolver with EAS address and admin configuration
+    /// @param eas The EAS contract address this resolver integrates with
+    /// @param _admin The initial admin address for privileged operations
+    /// @param _whitelistEnabled Whether to enforce attester whitelist from deployment
     constructor(
         IEAS eas,
         address _admin,
@@ -38,11 +95,21 @@ contract KYAIdentityResolver is SchemaResolver {
         whitelistEnabled = _whitelistEnabled;
     }
 
+    /// @dev Restricts function access to the current admin
     modifier onlyAdmin() {
         if (msg.sender != admin) revert OnlyAdmin();
         _;
     }
 
+    /// @notice Validates and registers a new agent identity attestation
+    /// @dev Called by EAS during attestation creation. Validation order:
+    ///      1. Check attester whitelist (if enabled)
+    ///      2. Validate agent address is non-zero
+    ///      3. Validate owner address is non-zero
+    ///      4. Ensure agent doesn't already have an identity
+    ///      5. Record agent→UID mapping and emit event
+    /// @param attestation The attestation being created, containing encoded identity data
+    /// @return True if attestation should be accepted, reverts otherwise
     function onAttest(
         Attestation calldata attestation,
         uint256 /* value */
@@ -86,6 +153,11 @@ contract KYAIdentityResolver is SchemaResolver {
         return true;
     }
 
+    /// @notice Cleans up state when an identity attestation is revoked
+    /// @dev Called by EAS during attestation revocation. Clears the agent→UID mapping
+    ///      to allow the agent address to register a new identity if needed.
+    /// @param attestation The attestation being revoked
+    /// @return True to allow the revocation to proceed
     function onRevoke(
         Attestation calldata attestation,
         uint256 /* value */
@@ -104,26 +176,43 @@ contract KYAIdentityResolver is SchemaResolver {
         return true;
     }
 
+    /// @notice Adds an address to the authorized attesters whitelist
+    /// @dev Only callable by admin. Has no effect if whitelist is disabled.
+    /// @param attester The address to authorize as an attester
     function addAuthorizedAttester(address attester) external onlyAdmin {
         authorizedAttesters[attester] = true;
         emit AttesterAdded(attester);
     }
 
+    /// @notice Removes an address from the authorized attesters whitelist
+    /// @dev Only callable by admin. Does not affect existing attestations.
+    /// @param attester The address to remove from authorized attesters
     function removeAuthorizedAttester(address attester) external onlyAdmin {
         authorizedAttesters[attester] = false;
         emit AttesterRemoved(attester);
     }
 
+    /// @notice Toggles the attester whitelist enforcement
+    /// @dev Only callable by admin. When disabled, any address can create attestations.
+    ///      WARNING: Disabling whitelist enables permissionless mode - use with caution.
+    /// @param enabled True to enforce whitelist, false for permissionless mode
     function setWhitelistEnabled(bool enabled) external onlyAdmin {
         whitelistEnabled = enabled;
         emit WhitelistToggled(enabled);
     }
 
+    /// @notice Initiates a 2-step admin transfer
+    /// @dev Only callable by current admin. The new admin must call acceptAdmin() to complete.
+    ///      Calling this again with a different address overwrites the pending admin.
+    /// @param newAdmin The address to transfer admin rights to
     function transferAdmin(address newAdmin) external onlyAdmin {
         pendingAdmin = newAdmin;
         emit AdminTransferStarted(admin, newAdmin);
     }
 
+    /// @notice Completes the 2-step admin transfer
+    /// @dev Only callable by the pending admin set via transferAdmin().
+    ///      Resets pendingAdmin to zero after successful transfer.
     function acceptAdmin() external {
         if (msg.sender != pendingAdmin) revert OnlyPendingAdmin();
         emit AdminTransferred(admin, pendingAdmin);

packages/contracts/hardhat.config.ts

@@ -1,7 +1,13 @@
 import { HardhatUserConfig } from "hardhat/config";
 import "@nomicfoundation/hardhat-toolbox";
+import "hardhat-gas-reporter";
 import "dotenv/config";
 
+// Handle private key with or without 0x prefix, trim whitespace
+// Only use if it's exactly 64 hex characters (32 bytes)
+const rawKey = process.env.DEPLOYER_PRIVATE_KEY?.trim().replace(/^0x/, "") || "";
+const privateKey = rawKey.length === 64 && /^[0-9a-fA-F]+$/.test(rawKey) ? rawKey : "";
+
 const config: HardhatUserConfig = {
   solidity: {
     compilers: [
@@ -25,11 +31,19 @@ const config: HardhatUserConfig = {
     baseSepolia: {
       url: process.env.BASE_SEPOLIA_RPC_URL || "https://sepolia.base.org",
       chainId: 84532,
-      accounts: process.env.DEPLOYER_PRIVATE_KEY
-        ? [process.env.DEPLOYER_PRIVATE_KEY]
-        : [],
+      accounts: privateKey ? [privateKey] : [],
     },
   },
+  gasReporter: {
+    enabled: process.env.REPORT_GAS === "true",
+    currency: "USD",
+    L2: "base",
+    L2Etherscan: process.env.BASESCAN_API_KEY,
+    coinmarketcap: process.env.COINMARKETCAP_API_KEY,
+    reportFormat: "terminal",
+    showMethodSig: true,
+    showTimeSpent: true,
+  },
 };
 
 export default config;

packages/contracts/package.json

@@ -13,6 +13,7 @@
     "@nomicfoundation/hardhat-toolbox": "^5.0.0",
     "dotenv": "^16.4.0",
     "hardhat": "^2.22.0",
+    "hardhat-gas-reporter": "^1.0.10",
     "ts-node": "^10.9.0",
     "typescript": "^5.4.0"
   },