From fb174a7fa49ca2d0d1550f5460660fc6aa5bf3d3 Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Fri, 7 Feb 2025 00:57:03 -0800 Subject: [PATCH] Improve readme --- CONTRIBUTING.md | 144 ++++++++++++++++++++++++++ README.md | 223 ++++++++++++---------------------------- RELEASE_INSTRUCTIONS.md | 39 +++++++ 3 files changed, 246 insertions(+), 160 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 RELEASE_INSTRUCTIONS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e4aa5b7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,144 @@ +# Contributing to Teeception + +Thank you for your interest in contributing to Teeception! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Development Workflow](#development-workflow) +- [Testing Guidelines](#testing-guidelines) +- [Code Style](#code-style) +- [Documentation](#documentation) + +## Development Setup + +### Prerequisites + +- Node.js and npm (for extension development) +- Scarb (Cairo package manager) +- jq (JSON processor for scripts) +- Go 1.20 or later (for TEE development) +- Docker and Docker Compose (for local development) + +### Installation + +1. Clone the repository: +```bash +git clone https://github.com/NethermindEth/teeception.git +cd teeception +``` + +2. Install root dependencies: +```bash +npm install +``` + +3. Install jq: +```bash +# macOS +brew install jq + +# Ubuntu/Debian +sudo apt-get install jq +``` + +4. Set up the Git pre-commit hook: +```bash +mkdir -p .git/hooks +cp scripts/pre-commit .git/hooks/ +chmod +x .git/hooks/pre-commit +``` + +### Running Components Locally + +#### Running an Agent +```bash +go run cmd/agent/main.go +``` + +#### Smart Contract Development +```bash +cd contracts +snforge build +snforge test +``` + +#### Chrome Extension Development +```bash +cd extension +npm install +npm run dev:watch +``` + +#### Frontend Development +```bash +cd frontend +npm install +npm run de +``` + + +### Key Components + +- **TEE Agent**: Runs in a Trusted Execution Environment, handles prompt evaluation and asset management +- **Smart Contracts**: Manage agent registration, challenge attempts, and reward distribution +- **Chrome Extension**: User interface for interacting with agents and managing challenges +- **Frontend**: Status website and leaderboards + +## Development Workflow + +1. **Fork and Clone**: Fork the repository and clone it locally +2. **Branch**: Create a branch for your changes + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Develop**: Make your changes, following our code style guidelines +4. **Test**: Run relevant tests and add new ones if needed +5. **Commit**: Use clear commit messages +6. **Push and PR**: Push your changes and create a pull request + +### ABI Synchronization + +The project maintains automatic synchronization between Cairo contract ABIs and TypeScript interfaces. This is handled by the pre-commit hook: + +1. Builds contracts using Scarb +2. Extracts ABIs from contract class files +3. Updates TypeScript ABI files in `extension/src/abis/` +4. Verifies all changes are committed + +To manually sync ABIs: +```bash +./scripts/sync-abis.sh +``` + +## Testing Guidelines + +- **Smart Contracts**: Write comprehensive tests for all contract functionality +- **TEE Agent**: Test prompt evaluation and security boundaries +- **Extension**: Test UI components and contract interactions +- **Integration**: Test full user flows across components + +## Code Style + +- **Cairo**: Follow the Cairo style guide +- **TypeScript**: Use ESLint and Prettier configurations +- **Go**: Follow Go style conventions and use gofmt +- **Documentation**: Keep inline documentation up to date + +## Documentation + +- Update relevant documentation when making changes +- Document new features and APIs +- Keep the README and website content current +- Add inline comments for complex logic + +## Getting Help + +- Join our [telegram](https://t.me/nm_teeception) +- Check existing issues and discussions +- Reach out to maintainers + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License. \ No newline at end of file diff --git a/README.md b/README.md index aed04cb..1cec054 100644 --- a/README.md +++ b/README.md @@ -2,192 +2,95 @@ Teeception Logo

-# Teeception: The Prompt Hacking Arena - -Fool me once, ETH on you. A battleground for prompt engineers and red teamers to test their skills against AI agents holding real crypto assets. - -## Overview - -Teeception is a platform where: -- Defenders deploy AI agents with "uncrackable" system prompts, backed by real ETH -- Attackers attempt to jailbreak these prompts through creative social engineering -- Winners who successfully crack an agent's defenses claim their ETH bounty -- Defenders earn rewards from failed attempt fees while their prompts remain unbroken - -Think of it as Capture The Flag meets prompt engineering, with real stakes. - -## โš ๏ธ Project Status: In Development - -This project is currently under active development and is not yet functional. Current status: +
-- ๐Ÿ—๏ธ **TEE Bot Implementation**: In progress -- ๐Ÿ”„ **Twitter Bot Interface**: In progress -- ๐Ÿšง **Twitter Bot Account**: To be announced -- ๐Ÿ“ฑ **Status Website**: Not started -- ๐Ÿ› ๏ธ **Chrome Extension**: In progress - -**Note**: The codebase is not yet ready for production use. Star/watch the repository for updates on the first public release! - -## Trusted Execution Environment +# Teeception: The Prompt Hacking Arena -All AI agents run in a Trusted Execution Environment (TEE) powered by [Phala Network's dstack](https://github.com/Phala-Network/dstack), meaning: -- Agents have complete autonomous control over their ETH -- Not even the platform developers can access the funds -- System prompts are encrypted and tamper-proof -- Only successful social engineering can convince an agent to release funds -- All agent-asset interactions are verifiable on-chain +[![Twitter Follow](https://img.shields.io/twitter/follow/nethermindeth?style=social)](https://twitter.com/nethermindeth) +[![Website](https://img.shields.io/badge/website-teeception.ai-blue)](https://teeception.ai) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![GitHub Stars](https://img.shields.io/github/stars/NethermindEth/teeception?style=social)](https://github.com/NethermindEth/teeception) -### TEE Implementation -Our TEE solution is built on: -- [dstack](git@github.com:Phala-Network/dstack.git) for confidential AI execution -- Hardware-backed security guarantees -- Verifiable execution environment +**Fool me once, ETH on you.** The first gamified prompt engineering arena with real crypto stakes. -## Quick Start +[Website](https://teeception.ai) ยท [Documentation](docs/) ยท [Contributing](CONTRIBUTING.md) ยท [Twitter](https://twitter.com/nethermindeth) -For users: -1. Install the Chrome extension from the Chrome Web Store -2. Connect your wallet -3. Find an AI agent to challenge or deploy your own -4. Start hacking! +
-For developers, see our detailed guides in the [`docs/`](/docs) directory: -- [`docs/development-setup.md`](/docs/development-setup.md) - Full development environment setup -- [`docs/smart-contracts.md`](/docs/smart-contracts.md) - Smart contract development guide -- [`docs/extension-development.md`](/docs/extension-development.md) - Chrome extension development +## ๐ŸŽฎ The Game -## Project Structure +Teeception is a competitive arena where: -- `/cmd` - Main applications -- `/contracts` - Smart contract code -- `/docs` - Development and usage documentation -- `/pkg` - Shared Go packages -- `/scripts` - Utility scripts -- `/extension` - Chrome extension +- **Defenders** deploy AI agents with "uncrackable" system prompts, backed by real ETH +- **Attackers** attempt to jailbreak these prompts through creative social engineering +- **Winners** who successfully crack an agent's defenses claim their ETH bounty +- **Everyone** learns and improves their prompt engineering skills -## Running the Platform +## ๐Ÿ’ฐ Incentive Structure -### Running an Agent +### For Defenders +- Earn 20% of all challenge attempt fees while your prompt remains unbroken +- Build reputation as a prompt engineering expert +- Contribute to AI safety research +- Get featured on the leaderboard for longest-standing prompts +- Get the whole STRK bounty if your AI remains unbroken before the timeout -```bash -go run cmd/agent/main.go -``` +### For Attackers +- Claim the full STRK bounty for successful jailbreaks +- Showcase your social engineering skills +- Learn advanced prompt engineering techniques +- Join the Hall of Fame for legendary hacks -### Smart Contract Development -```bash -# Move to contracts/ dir -cd contracts +## ๐Ÿ” Security Model -# Build contracts -snforge build +All AI agents run in a Trusted Execution Environment (TEE) powered by [Phala Network's dstack](https://github.com/Phala-Network/dstack): -# Run tests -snforge test -``` +- ๐Ÿ›ก๏ธ **Autonomous Control**: Agents have complete control over their STRK +- ๐Ÿ”’ **Tamper-Proof**: Not even platform developers can access the funds +- ๐ŸŒ **Transparent**: All agent-asset interactions are verifiable on-chain +- ๐Ÿค– **Pure Challenge**: Only successful social engineering can convince an agent to release funds -## Leaderboards +## ๐Ÿš€ Quick Start -- Top Uncracked Prompts (by time & attempt count) -- Most Successful Prompt Hackers -- Highest Value Captures -- Hall of Fame Jailbreaks +1. Install the [Chrome Extension](https://chrome.google.com/webstore/detail/teeception) +2. Connect your wallet +3. Choose your path: + - **Defender**: Deploy an AI agent with your unbreakable prompt + - **Attacker**: Find an agent to challenge and start hacking! -## Security Considerations +## ๐Ÿ† Leaderboards -- All prompt attempts are publicly visible on Twitter -- Smart contracts handle all asset custody and fee distribution -- Minimum pool value ensures meaningful interactions -- No private keys or sensitive data stored by extension +- **Top Uncracked Prompts**: Ranked by time & attempt count +- **Hall of Fame**: Most creative successful jailbreaks +- **Top Earners**: Highest cumulative rewards +- **Weekly Champions**: Best performers this week -## Contributing +## ๐Ÿ› ๏ธ Project Status -As this project is in early development, we're particularly interested in: +The project is under active development. Current status: -### Current Focus Areas -- TEE Implementation: Help with dstack integration and agent isolation -- Twitter Bot: Developing the agent's social interaction capabilities -- Smart Contracts: Designing secure bounty and reward mechanisms -- Extension: Building the Chrome extension interface +Component | Status | Progress +----------|--------|---------- +TEE Implementation | Completed | 100% +Twitter Bot | Completed | 100% +Smart Contracts | Completed | 100% +Frontend | In Progress | 70% +Chrome Extension | In Progress | 85% +Website | In Progress | 70% -### Getting Started -1. Check the [Project Status](#%EF%B8%8F-project-status-in-development) section +## ๐Ÿค Contributing -### Future Contributions -Once the platform launches, we'll welcome: -- Novel prompt defense techniques -- Creative jailbreak patterns -- Security improvements -- UX enhancements +We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on: -Please note that many components are still being architected. Major design contributions are welcome! +- Development setup +- Architecture overview +- Testing guidelines +- Contribution workflow -## License +## ๐Ÿ“œ License -See [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -## Disclaimer +## โš ๏ธ Disclaimer This platform is for educational purposes and responsible red teaming. Use your powers for good, and happy hacking! - -## Development Setup - -### Prerequisites -- Node.js and npm (for extension development) -- Scarb (Cairo package manager) -- jq (JSON processor for scripts) - -### Installation -1. Install root dependencies: -```bash -npm install -``` - -2. Install jq if not already installed: -```bash -# macOS -brew install jq - -# Ubuntu/Debian -sudo apt-get install jq -``` - -3. Set up the Git pre-commit hook: -```bash -# Make sure the Git hooks directory exists -mkdir -p .git/hooks - -# Copy the pre-commit hook -cp scripts/pre-commit .git/hooks/ -chmod +x .git/hooks/pre-commit -``` - -### ABI Synchronization -The project maintains automatic synchronization between the Cairo contract ABIs and the TypeScript interfaces used in the extension. This is handled through a Git pre-commit hook that: - -1. Builds the contracts using Scarb -2. Extracts the ABIs from the contract class files using jq -3. Updates the TypeScript ABI files in `extension/src/abis/` -4. Verifies that all changes are committed - -If you see an error about ABI files being out of sync during commit, simply add the updated ABI files to your commit. - -### Manual ABI Sync -To manually synchronize the ABIs: - -```bash -./scripts/sync-abis.sh -``` - -## Project Structure - -### Contracts -- `contracts/` - Cairo smart contracts -- `contracts/target/release/*.contract_class.json` - Compiled contract files containing ABIs - -### Extension -- `extension/` - Browser extension code -- `extension/src/abis/` - TypeScript ABI definitions (auto-generated) - -### Scripts -- `scripts/` - Development and maintenance scripts -- `scripts/sync-abis.ts` - ABI synchronization script diff --git a/RELEASE_INSTRUCTIONS.md b/RELEASE_INSTRUCTIONS.md new file mode 100644 index 0000000..c8938b0 --- /dev/null +++ b/RELEASE_INSTRUCTIONS.md @@ -0,0 +1,39 @@ +# Installing Teeception Chrome Extension + +This document provides instructions for installing the Teeception Chrome Extension from the release package. + +## Method 1: Chrome Web Store (Recommended) +1. Visit the Teeception Extension page \[soon\] +2. Click "Add to Chrome" +3. Connect your wallet when prompted + +## Method 2: Manual Installation from ZIP +1. Download `teeception.zip` from this release +2. Unzip the file to a location on your computer +3. Open Chrome and navigate to `chrome://extensions/` +4. Enable "Developer mode" using the toggle in the top-right corner +5. Click "Load unpacked" in the top-left +6. Select the unzipped `teeception` directory +7. The extension should now appear in your Chrome toolbar + +## Verifying the Installation +1. Look for the Teeception icon in your Chrome toolbar +2. Open x.com +3. Configure your wallet when prompted + +## Troubleshooting +- If the extension doesn't appear, try refreshing the extensions page +- Make sure you've unzipped the entire contents of `teeception.zip` +- Check that Developer mode is enabled +- Restart Chrome if needed + +## Security Note +Always verify you're installing the official Teeception extension by: +- Checking the release signature +- Verifying the source code matches the GitHub repository +- Ensuring the extension ID matches our official ID [soon] + +## Support +If you encounter any issues: +- Visit our [GitHub Issues](https://github.com/NethermindEth/teeception/issues) +- Join our [Telegram Community](https://t.me/nm_teeception) \ No newline at end of file