Sam/docs

AGENTS.md

@@ -0,0 +1,44 @@
+# Agent Guidelines for edge-exchange-plugins
+
+## Build/Test/Lint Commands
+
+- **Test**: `npm test` (single test: `npm test -- test/path/to/file.test.ts`)
+- **Lint**: `npm run lint` (auto-fix: `npm run fix`)
+- **Type check**: `npm run types`
+- **Build**: `npm run prepare` (runs clean, compile, types, and webpack)
+- **Verify all**: `npm run verify` (build + lint + types + test)
+
+## Code Style Guidelines
+
+- **TypeScript**: Strict mode enabled, use type imports (`import type { ... }`)
+- **Imports**: Sort with `simple-import-sort`, no default exports
+- **Formatting**: 2-space indentation, semicolons required, trailing commas
+- **Naming**: camelCase for variables/functions, PascalCase for types/interfaces
+- **Files**: Use `.ts` extension, organize by feature in `src/swap/`
+- **Async**: Always use async/await over promises, handle errors with try/catch
+- **Exports**: Named exports only, group related functionality
+- **Dependencies**: Use `cleaners` for runtime validation, `biggystring` for numbers
+- **Constants**: UPPER_SNAKE_CASE for true constants, extract magic numbers
+- **Error handling**: Throw specific Edge error types (e.g., SwapCurrencyError)
+
+## Documentation Index
+
+### Setup & Configuration
+
+- `README.md` - **When to read**: Initial setup, installation, adding exchanges
+  - **Summary**: Setup instructions, development guide, PR requirements
+
+### Detailed Documentation
+
+- `docs/conventions/edge-company-conventions.md` - **When to read**: Starting development
+  - **Summary**: Company-wide Edge conventions, git workflow, PR rules
+- `docs/conventions/typescript-style-guide.md` - **When to read**: Writing new code
+  - **Summary**: Import rules, type safety, error handling, naming conventions
+- `docs/patterns/swap-plugin-architecture.md` - **When to read**: Creating new plugins
+  - **Summary**: Plugin structure, categories, common patterns, best practices
+- `docs/business-rules/wallet-validation-rules.md` - **When to read**: Implementing DEX plugins
+  - **Summary**: Critical wallet requirements for DEX/DeFi integrations
+- `docs/guides/adding-new-exchange.md` - **When to read**: Adding exchange support
+  - **Summary**: Step-by-step guide for new exchange integration
+- `docs/references/api-deprecations.md` - **When to read**: Seeing deprecation warnings
+  - **Summary**: Deprecated APIs, migration paths, impact assessment

README.md

@@ -4,6 +4,14 @@ This library exports a collection of exchange-rate & swap plugins for use with [
 
 Please see [index.js](./src/index.js) for the list of plugins in this repo. These are compatible with edge-core-js v0.19.37 or later.
 
+## Quick Links
+
+- [Edge Company Conventions](https://github.com/EdgeApp/edge-conventions) - Company-wide development standards
+- [TypeScript Style Guide](docs/conventions/typescript-style-guide.md) - Project-specific code conventions
+- [Adding New Exchange Guide](docs/guides/adding-new-exchange.md) - Step-by-step integration guide
+- [Plugin Architecture](docs/patterns/swap-plugin-architecture.md) - Understanding plugin patterns
+- [Agent Guidelines](AGENTS.md) - For AI coding assistants
+
 ## Installing
 
 Fist, add this library to your project:
@@ -17,21 +25,21 @@ yarn add edge-exchange-plugins
 For Node.js, you should call `addEdgeCorePlugins` to register these plugins with edge-core-js:
 
 ```js
-const { addEdgeCorePlugins, lockEdgeCorePlugins } = require('edge-core-js')
-const plugins = require('edge-exchange-plugins')
+const { addEdgeCorePlugins, lockEdgeCorePlugins } = require("edge-core-js");
+const plugins = require("edge-exchange-plugins");
 
-addEdgeCorePlugins(plugins)
+addEdgeCorePlugins(plugins);
 
 // Once you are done adding plugins, call this:
-lockEdgeCorePlugins()
+lockEdgeCorePlugins();
 ```
 
 You can also add plugins individually if you want to be more picky:
 
 ```js
 addEdgeCorePlugins({
-  thorchain: plugins.thorchain
-})
+  thorchain: plugins.thorchain,
+});
 ```
 
 ### Browser
@@ -50,12 +58,12 @@ and then adjust your script URL to http://localhost:8083/edge-exchange-plugins.j
 This package will automatically install itself using React Native autolinking. To integrate the plugins with edge-core-js, add its URI to the context component:
 
 ```jsx
-import { pluginUri } from 'edge-exchange-plugins'
+import { pluginUri } from "edge-exchange-plugins";
 
 <MakeEdgeContext
   pluginUris={[pluginUri]}
   // Plus other props as required...
-/>
+/>;
 ```
 
 To debug this project, run `yarn start` to start a Webpack server, and then use `debugUri` instead of `pluginUri`.
@@ -90,7 +98,7 @@ Please be aware that when considering merging pull requests for additional excha
 
 - Accompanying PR submitted to `edge-reports` that fetches transaction data to your exchange that is credited to Edge users
 - Rebase of your branch upon this repo's `master` branch. For more info:
-https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
+  https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
 - Accompanying PR submitted to `edge-react-gui` that includes (but is not limited to) the following:
-    - Small 64x64 pixel square logos with a white background
-    - 600x210 pixel horizontal logo for your exchange, with **no** empty space around the logo (we will add this programatically within the app
+  - Small 64x64 pixel square logos with a white background
+  - 600x210 pixel horizontal logo for your exchange, with **no** empty space around the logo (we will add this programatically within the app

docs/business-rules/wallet-validation-rules.md

@@ -0,0 +1,84 @@
+# Wallet Validation Rules
+
+**Date**: 2025-08-20
+
+## Critical Business Rules
+
+### Same Wallet Requirements
+
+Several DEX plugins **must** use the same wallet for source and destination:
+
+1. **XRP DEX** (`src/swap/defi/xrpDex.ts`)
+
+   ```typescript
+   // Source and dest wallet must be the same
+   if (request.fromWallet !== request.toWallet) {
+     throw new Error("XRP DEX must use same wallet for source and destination");
+   }
+   ```
+
+2. **0x Gasless** (`src/swap/defi/0x/0xGasless.ts`)
+
+   ```typescript
+   // The fromWallet and toWallet must be of the same because the swap
+   ```
+
+3. **Fantom Sonic Upgrade** (`src/swap/defi/fantomSonicUpgrade.ts`)
+   ```typescript
+   if (fromAddress !== toAddress) {
+     throw new Error("From and to addresses must be the same");
+   }
+   ```
+
+### Chain Validation
+
+Uniswap V2-based plugins validate that both wallets are on the same chain:
+
+1. **TombSwap** (`src/swap/defi/uni-v2-based/plugins/tombSwap.ts`)
+2. **SpookySwap** (`src/swap/defi/uni-v2-based/plugins/spookySwap.ts`)
+   ```typescript
+   // Sanity check: Both wallets should be of the same chain.
+   ```
+
+## Rationale
+
+### DEX Same-Wallet Requirement
+
+- DEX swaps happen in a single transaction on-chain
+- The wallet executing the swap receives the output tokens
+- Cross-wallet swaps would require additional transfer transactions
+
+### Chain Validation
+
+- Prevents accidental cross-chain swap attempts
+- Ensures contract addresses are valid for the target chain
+- Protects users from losing funds due to chain mismatches
+
+## Implementation Guidelines
+
+When implementing a new DEX plugin:
+
+1. **Always validate wallet compatibility** early in `fetchSwapQuote`
+2. **Throw descriptive errors** that explain the limitation
+3. **Document the requirement** in the plugin's swapInfo
+
+Example validation:
+
+```typescript
+async fetchSwapQuote(request: EdgeSwapRequest): Promise<EdgeSwapQuote> {
+  // Validate same wallet requirement for DEX
+  if (request.fromWallet !== request.toWallet) {
+    throw new Error(`${swapInfo.displayName} requires same wallet for swap`)
+  }
+
+  // Continue with quote logic...
+}
+```
+
+## Exceptions
+
+Centralized exchange plugins (`/central/`) typically support cross-wallet swaps because:
+
+- They use deposit addresses
+- The exchange handles the actual swap
+- Funds can be sent to any destination address

docs/conventions/edge-company-conventions.md

@@ -0,0 +1,67 @@
+# Edge Company Conventions
+
+**Date**: 2025-08-20
+
+## Overview
+
+This document references the company-wide Edge development conventions that apply to all Edge projects, including edge-exchange-plugins.
+
+## Edge Conventions Repository
+
+The official Edge conventions are maintained at: https://github.com/EdgeApp/edge-conventions
+
+### Key Convention Categories
+
+1. **Code Conventions**
+
+   - [JavaScript Code Conventions](https://github.com/EdgeApp/edge-conventions/blob/master/code/javascriptCode.md)
+   - [JavaScript Project Setup](https://github.com/EdgeApp/edge-conventions/blob/master/code/javascriptSetup.md)
+   - [React Conventions](https://github.com/EdgeApp/edge-conventions/blob/master/code/react.md)
+   - [Redux Conventions](https://github.com/EdgeApp/edge-conventions/blob/master/code/redux.md)
+
+2. **Git Conventions**
+
+   - [Commit Rules](https://github.com/EdgeApp/edge-conventions/blob/master/git/commit.md)
+   - [Pull Request Rules](https://github.com/EdgeApp/edge-conventions/blob/master/git/pr.md)
+   - [Git "Future Commit" Workflow](https://github.com/EdgeApp/edge-conventions/blob/master/git/future-commit.md)
+
+3. **Documentation Standards**
+   - [Documentation Conventions](https://github.com/EdgeApp/edge-conventions/blob/master/docs.md)
+
+## How These Apply to edge-exchange-plugins
+
+### Code Standards
+
+While edge-exchange-plugins uses TypeScript (not plain JavaScript), many principles from the JavaScript conventions still apply:
+
+- Consistent formatting and style
+- Clear naming conventions
+- Proper error handling patterns
+
+### Git Workflow
+
+All Edge projects follow the same git conventions:
+
+- **Commit messages** should follow the Edge commit rules
+- **Pull requests** must meet the PR requirements
+- **Branching** follows the documented patterns
+
+### Additional Project-Specific Conventions
+
+This project extends the Edge conventions with TypeScript-specific rules documented in:
+
+- [TypeScript Style Guide](./typescript-style-guide.md) - Project-specific TypeScript conventions
+
+## Important Notes
+
+1. **Company conventions take precedence** - When in doubt, follow the Edge conventions
+2. **TypeScript additions** - This project adds TypeScript-specific rules on top of the base conventions
+3. **PR requirements** - All PRs must follow both Edge conventions and project-specific requirements
+
+## Quick Reference
+
+For edge-exchange-plugins developers:
+
+1. Read the [Edge conventions](https://github.com/EdgeApp/edge-conventions) first
+2. Then read our [TypeScript Style Guide](./typescript-style-guide.md) for project-specific rules
+3. Follow the [PR rules](https://github.com/EdgeApp/edge-conventions/blob/master/git/pr.md) when submitting changes