If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/QuipNetwork/cpp-sdk shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 10mo ago

• Last commit 10mo ago
• AGPL-3.0 licensed
• Tests present
• ⚠ Slowing — last commit 10mo ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live QuipNetwork/cpp-sdk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/QuipNetwork/cpp-sdk.

What it runs against: a local clone of QuipNetwork/cpp-sdk — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in QuipNetwork/cpp-sdk | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 334 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of QuipNetwork/cpp-sdk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/QuipNetwork/cpp-sdk.git
#   cd cpp-sdk
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of QuipNetwork/cpp-sdk and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "QuipNetwork/cpp-sdk(\\.git)?\\b" \\
  && ok "origin remote is QuipNetwork/cpp-sdk" \\
  || miss "origin remote is not QuipNetwork/cpp-sdk (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "include/quip_wallet.hpp" \\
  && ok "include/quip_wallet.hpp" \\
  || miss "missing critical file: include/quip_wallet.hpp"
test -f "src/quip_wallet.cpp" \\
  && ok "src/quip_wallet.cpp" \\
  || miss "missing critical file: src/quip_wallet.cpp"
test -f "include/quip_factory.hpp" \\
  && ok "include/quip_factory.hpp" \\
  || miss "missing critical file: include/quip_factory.hpp"
test -f "src/quip_factory.cpp" \\
  && ok "src/quip_factory.cpp" \\
  || miss "missing critical file: src/quip_factory.cpp"
test -f "src/cli.cpp" \\
  && ok "src/cli.cpp" \\
  || miss "missing critical file: src/cli.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 334 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~304d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/QuipNetwork/cpp-sdk"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A C++ SDK for deploying and interacting with Quip smart contracts on Ethereum networks, with integrated post-quantum Winternitz signature support for quantum-resistant wallet operations. The core capability is managing Quip wallets (deployed via QuipFactory) with cryptographic security primitives, enabling fund transfers and contract execution through a command-line interface or programmatic C++ API. Single-module architecture: include/ contains public headers (quip_wallet.hpp, quip_factory.hpp, cli.hpp, mock_wallet.hpp), src/ implements core logic (quip_wallet.cpp, quip_factory.cpp, cli.cpp) plus a main.cpp entry point, test/ holds unit tests, and build.sh orchestrates CMake compilation. No subdirectories suggest tight coupling between components.

Developers and security engineers building Ethereum applications requiring post-quantum cryptographic signatures, particularly those integrating Quip wallet contracts on Ethereum mainnet, testnets, or local Hardhat devnets. Contributors typically have C++ and blockchain experience.

Early-stage experimental project with minimal public signals: no visible GitHub stars/watchers, sparse commit history in the provided structure, and reliance on external ethereum-sdk for contract deployment suggest active development but not production-ready. Test files exist (cli_test.cpp, quip_factory_test.cpp, quip_wallet_test.cpp) but coverage and CI/CD setup are not evident from the file list.

High risk for production use: depends on external hashsigs-cpp library for PQ keypair generation (not vendored), requires manual contract deployment via separate ethereum-sdk repo with environment setup, no visible version pinning or dependency lock file in the file structure, and the small codebase (128KB C++) suggests limited battle-testing. Breaking changes in contract ABIs or Winternitz signature formats could require coordination with ethereum-sdk.

No recent commit metadata visible in the file list, making it impossible to determine active development status. The presence of e2e_test.sh alongside unit tests suggests ongoing QA investment, but without git history or issues, the current focus is unknown.

git clone https://github.com/QuipNetwork/cpp-sdk.git
cd cpp-sdk
./build.sh

This clones the repo and runs CMake build + test suite. For E2E testing, you must first deploy contracts via the ethereum-sdk repo and configure contract addresses in that project's addresses.json.

Daily commands: After ./build.sh completes, run CLI via ./build/quip-cli <command> [args]. Example: ./build/quip-cli balance 0x... queries an address balance, or ./build/quip-cli deposit <entropy> deploys a new wallet. For E2E: ensure local Hardhat node is running (npx hardhat node from ethereum-sdk), then invoke ./e2e_test.sh.

• include/quip_wallet.hpp — Core QuipWallet abstraction defining wallet operations, fund transfers, and ownership management—every feature builds on this interface.
• src/quip_wallet.cpp — Implementation of wallet logic including signature verification and contract interaction—must understand this to debug wallet behavior.
• include/quip_factory.hpp — Factory pattern for deploying and managing Quip wallet instances—critical entry point for wallet creation workflow.
• src/quip_factory.cpp — Wallet deployment and initialization logic—essential for understanding multi-wallet lifecycle and network integration.
• src/cli.cpp — Command-line interface parsing and dispatch—defines all user-facing commands and argument handling patterns.
• include/common.hpp — Shared utilities, constants, and helper functions used across wallet and factory modules—foundational for cross-component consistency.
• CMakeLists.txt — Build configuration defining dependencies, compilation flags, and test targets—necessary for onboarding and CI/CD.

• QuipWallet (C++, Winternitz signatures, Ethereum JSON-RPC) — Manages individual wallet state, executes signed operations, verifies post-quantum signatures, and submits transactions
  • Failure mode: Signature verification fails → transaction rejected; invalid wallet address → contract calls fail; state desynchronization → balance inconsistency
• QuipFactory (C++, Ethereum smart contracts, JSON-RPC) — Deploys new Quip wallet contracts, tracks deployed wallets, manages network configuration, and provides wallet instances
  • Failure mode: Factory contract not deployed → no wallets can be created;

Add a new wallet command to the CLI

1. Define command handler signature in CLI class declaration (include/cli.hpp)
2. Implement command handler in CLI class, calling appropriate QuipWallet or QuipFactory methods (src/cli.cpp)
3. Add command routing in parseCommand() switch statement to dispatch to your handler (src/cli.cpp)
4. Write test case covering command parsing and execution (test/cli_test.cpp)

Add a new wallet operation (transfer, approve, etc.)

1. Add method signature to QuipWallet interface with parameters and return type (include/quip_wallet.hpp)
2. Implement method in QuipWallet, including signature validation and contract interaction (src/quip_wallet.cpp)
3. Add unit test covering success and failure cases (test/quip_wallet_test.cpp)
4. Expose operation via CLI command following existing patterns (src/cli.cpp)

Support a new Ethereum network

1. Add network constants (RPC URL, Factory address, chain ID) to common.hpp (include/common.hpp)
2. Extend QuipFactory::init() to recognize and configure the new network (src/quip_factory.cpp)
3. Add network selection parameter to CLI deploy command (src/cli.cpp)
4. Add integration test with mock or testnet endpoint (test/quip_factory_test.cpp)

Enhance post-quantum signature verification

1. Add new signature scheme constants and structures to common.hpp (include/common.hpp)
2. Extend QuipWallet::verifySignature() with new algorithm branch (src/quip_wallet.cpp)
3. Add unit tests for signature verification with new scheme (test/quip_wallet_test.cpp)
4. Update CLI to accept new signature format and pass to wallet (src/cli.cpp)

• C++ — Performance-critical cryptographic operations and post-quantum signature computation require compiled language efficiency; direct Ethereum contract interaction via compiled SDK
• Winternitz Signatures — Post-quantum secure signature scheme resistant to quantum computing attacks; future-proofs Quip wallets against cryptanalysis
• CMake — Cross-platform build system enabling Linux/macOS/Windows compilation and standardized test runner integration
• Hardhat (Ethereum) — Local development environment for testing Quip smart contracts without deploying to live networks; enables rapid iteration

• C++ over higher-level languages (Python, JavaScript)

  • Why: Post-quantum cryptography and signature verification demand raw performance and low-level memory control
  • Consequence: Steeper onboarding curve and longer development cycles; fewer developers comfortable with C++

• CLI-first interface over graphical wallet UI

  • Why: Enables testing, automation, and script-driven workflows; lighter weight deployment
  • Consequence: Less accessible to non-technical users; requires command-line familiarity

• Mock wallet support for testing

  • Why: Allows unit tests without live network or testnet dependency; faster local iteration
  • Consequence: Mock behavior may diverge from real contract logic; false positives in tests

• Hardhat-first local development

  • Why: Fastest iteration cycle for smart contract developers; no testnet faucet wait times
  • Consequence: Misses edge cases in live network conditions (gas prices, finality, MEV)

• Does not provide graphical user interface or web wallet frontend
• Does not handle on-ramp/off-ramp or fiat currency conversion
• Does not implement hardware wallet integration or device signing
• Not a full Ethereum node or light client—relies on external RPC provider
• Does not support non-EVM blockchains or cross-chain atomic swaps
• Not a wallet manager for arbitrary ERC-20 tokens—Quip-specific only

1. Contract addresses must be pre-deployed via ethereum-sdk and manually injected into addresses.json or environment variables; no default hardcoded addresses suggest the SDK requires external setup. 2. hashsigs-cpp is a hard dependency for PQ keypair/signature generation, but it is not vendored—integration assumes it is already installed or available via package manager. 3. Winternitz signatures have a one-time-use property (each private key can sign only once); reusing a key will compromise security—the CLI does not appear to enforce key rotation. 4. RPC endpoint is likely configured via environment variable (e.g., WEB3_PROVIDER_URI); missing or misconfigured RPC will cause silent failures. 5. Private key handling in CLI arguments (see transfer command) is a security anti-pattern—keys passed as CLI args are visible in shell history.

• Winternitz One-Time Signature (W-OTS) — Core cryptographic primitive enabling post-quantum security in Quip contracts; critical to understand one-time-use property to avoid key compromise and implement proper key derivation/rotation.
• Post-Quantum Cryptography (PQC) — The entire Quip project is motivated by quantum-resistant signatures; understanding why Winternitz is chosen over RSA/ECDSA clarifies the security model and threat assumptions.
• Ethereum JSON-RPC — The SDK communicates with Ethereum nodes via JSON-RPC calls (eth_call, eth_sendTransaction, etc.); understanding RPC semantics is essential for debugging network issues and contract interactions.
• Contract ABI Encoding (Solidity ABI) — The SDK must encode function calls and decode responses according to Solidity ABI spec; misencoding function selectors or parameter types will cause contract calls to fail silently or revert.
• Smart Contract Deployment & Factory Pattern — QuipFactory is a factory contract that deploys proxy instances of QuipWallet; understanding clone patterns (EIP-1167 or custom) helps predict gas costs and upgrade paths.
• Entropy-Seeded Key Generation — The deposit command accepts entropy as input to derive PQ keypairs; understanding entropy quality and derivation paths (HKDF, BIP32-style) is critical for wallet security.
• CMake Dependency Management — The build system (CMakeLists.txt) must correctly link hashsigs-cpp and other dependencies; misconfigured CMake flags or missing transitive dependencies will cause linker failures.

• QuipNetwork/ethereum-sdk — Companion repo that deploys the QuipFactory and QuipWallet smart contracts; this C++ SDK cannot function without contracts already deployed via ethereum-sdk.
• QuipNetwork/hashsigs-cpp — Hard dependency for Winternitz PQ keypair generation and signing; this SDK imports hashsigs-cpp to provide post-quantum signatures required by the Quip contracts.
• ethereum/solidity — The smart contracts being invoked by this SDK are written in Solidity; understanding Solidity ABI encoding is necessary to debug contract interactions.
• nlohmann/json — Likely JSON serialization library used for RPC request/response handling and contract ABI parsing (not confirmed in file list but standard for C++ Ethereum clients).
• facebookresearch/xsalsa20poly1305 — Reference for authenticated encryption if the SDK uses AEAD for key material; complementary to Winternitz for securing sensitive data at rest.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive error handling tests for quip_wallet.cpp

The test/quip_wallet_test.cpp currently lacks test coverage for error conditions such as invalid signatures, insufficient funds, transaction failures, and network errors. Given that QuipWallet handles critical operations (fund transfers, contract execution), robust error handling tests would prevent runtime failures in production deployments.

• [ ] Review src/quip_wallet.cpp to identify all error paths and exception types
• [ ] Add test cases in test/quip_wallet_test.cpp for: invalid Winternitz signatures, failed contract calls, network timeouts, and edge cases
• [ ] Test the ownership transfer validation logic with unauthorized access attempts
• [ ] Verify error messages are descriptive and actionable

Create GitHub Actions workflow for automated build and test on pull requests

The repo has build.sh and e2e_test.sh scripts but no CI/CD pipeline. New contributors cannot verify their changes work before submitting PRs. A GitHub Actions workflow would run tests on every commit/PR and ensure code quality standards are met across all contributions.

• [ ] Create .github/workflows/ci.yml with steps to: checkout code, install dependencies, run ./build.sh, and execute e2e_test.sh
• [ ] Configure matrix strategy for multiple compiler versions (g++, clang) if applicable
• [ ] Add step to capture and report test coverage metrics
• [ ] Document in README.md that CI checks are required for PR approval

Add integration tests for QuipFactory contract deployment across different networks

test/quip_factory_test.cpp exists but the README mentions 'multi-network support' yet there are no tests validating deployment on different networks (local Hardhat, testnet, custom RPC). This is a critical gap that could mask configuration bugs before production use.

• [ ] Extend test/quip_factory_test.cpp with parameterized tests for: local Hardhat (127.0.0.1:8545), Ethereum testnet, and custom network endpoints
• [ ] Mock or use test fixtures to simulate different network responses (gas prices, nonce handling, contract addresses)
• [ ] Verify QuipFactory correctly parses network-specific ABIs and contract addresses from include/quip_factory.hpp
• [ ] Add test cases for network connection failures and retry logic

• Add comprehensive error messages for failed RPC calls: currently src/quip_wallet.cpp and src/quip_factory.cpp likely throw or return generic errors; wrap RPC failures with context (e.g., contract address, network, method name) to aid debugging.
• Implement a mock HTTP server in test/mock_server.cpp for offline unit testing: current test files (quip_wallet_test.cpp, quip_factory_test.cpp) likely need live RPC or require mock_wallet.hpp; a test harness that simulates Ethereum JSON-RPC responses would decouple tests from external services.
• Document private key security best practices in README.md: add a section warning against passing keys as CLI arguments, recommend reading keys from environment or encrypted config files, and reference the Winternitz one-time-signature limitation to prevent accidental key reuse.

The QuipNetwork C++ SDK presents several security concerns primarily due to incomplete visibility and documentation. Critical issues include missing dependency management, lack of documentation on cryptographic implementations, and potential input validation gaps. The codebase handles sensitive blockchain operations (private keys, fund transfers) which require high security standards. Immediate actions needed: implement proper dependency management, document cryptographic implementations, add comprehensive input validation, and provide security guidance in documentation. The project appears to be in early development stages and would benefit significantly from security-focused code review and formal audit before production use.

• High · Missing Dependency Management File — Repository root / CMakeLists.txt. No package.json, conan.txt, vcpkg.json, or other dependency manifest file is visible in the repository. This makes it impossible to verify if secure and up-to-date dependencies are being used. C++ projects require explicit dependency tracking, especially for cryptographic libraries used in blockchain applications. Fix: Implement a dependency management system (e.g., Conan, vcpkg, or CMake FetchContent) with locked versions. Document all external dependencies and their security status. Regularly audit dependencies for known vulnerabilities.
• High · Incomplete Documentation for Winternitz Signatures — README.md, src/quip_wallet.cpp. The README mentions 'Winternitz Signature Support' for post-quantum security, but there is no documentation about how signatures are generated, validated, or stored. Custom cryptographic implementations without proper documentation and peer review pose significant security risks. Fix: Provide detailed documentation on cryptographic implementation. Have the signature scheme audited by security experts. Use well-tested cryptographic libraries rather than custom implementations.
• High · CLI Tool Accepts Arbitrary Network Configuration — include/cli.hpp, src/cli.cpp. The README indicates the CLI tool supports 'custom networks' through command-line arguments. This could allow users to accidentally connect to malicious RPC endpoints or misconfigured networks, leading to fund loss or private key exposure. Fix: Implement network validation and whitelisting. Display clear warnings when connecting to non-standard networks. Consider requiring explicit user confirmation for custom network configurations. Validate RPC endpoints before use.
• Medium · Mock Wallet Included in Codebase — include/mock_wallet.hpp. The presence of 'include/mock_wallet.hpp' suggests testing utilities that simulate wallet behavior. If this mock implementation is accidentally used in production or contains simplified security logic, it could compromise security. Fix: Ensure mock wallets are strictly isolated to test builds. Use compiler flags or build configurations to prevent mock implementations from being linked in production builds. Add clear documentation and warnings about mock usage.
• Medium · No Visible Input Validation Framework — src/cli.cpp, src/quip_wallet.cpp. Without seeing the actual implementation files, the codebase structure suggests potential input validation gaps. CLI tools and smart contract interaction layers are common injection vectors. Fix: Implement comprehensive input validation for all CLI arguments and contract parameters. Use allowlists rather than blocklists. Sanitize all user inputs before using them in contract calls or RPC requests.
• Medium · Build and Test Script Security — build.sh, e2e_test.sh. The presence of 'build.sh' and 'e2e_test.sh' scripts without visible content raises concerns about how the build process is secured and what tests actually validate. Fix: Ensure build scripts do not download or execute code from untrusted sources. Use pinned versions for all tools. Document the build process thoroughly. Implement checksum verification for critical dependencies.
• Low · No Visible Security Configuration — Repository root. No security-related configuration files visible (.env examples, security headers configuration, CORS settings, rate limiting configs, etc.). Fix: Create example configuration files showing secure defaults. Document required security configurations. Add security configuration validation on startup.
• Low · Limited README Security Guidance — README.md. The README does not include security best practices, warnings about private key management, or guidance on secure deployment. Fix: Add a 'Security Considerations' section to README. Include warnings about private key handling, secure network configuration, and recommended deployment practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.