Sam/docs #400

samholmes · 2025-08-21T20:09:31Z

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

Yes
No

Dependencies

none

Description

none

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1211105048261470

paullinator · 2025-08-21T20:43:10Z

docs/guides/adding-new-exchange.md

+```typescript
+async fetchSwapQuote(request: EdgeSwapRequest): Promise<EdgeSwapQuote> {
+  // 1. Validate supported currencies
+  const { fromCurrencyCode, toCurrencyCode } = request


Use pluginId,tokenId not currencyCode

paullinator · 2025-08-21T20:43:49Z

docs/guides/adding-new-exchange.md

+  if (lt(quote.fromAmount, MIN_AMOUNT)) {
+    throw new SwapBelowLimitError(swapInfo, MIN_AMOUNT)
+  }
+


The below and above limit errors should come from the API call, not hard coded.

paullinator · 2025-08-21T20:44:11Z

docs/guides/adding-new-exchange.md

+    throw new SwapBelowLimitError(swapInfo, MIN_AMOUNT)
+  }
+
+  // 5. Return EdgeSwapQuote


Also validate region and supported assets. All should be validated via API response.

API should return all errors in an array and errors should be surfaced with this priority.

region restriction

asset support

min/max amount

paullinator · 2025-08-21T20:47:20Z

docs/guides/adding-new-exchange.md

+```typescript
+const currencyMap: StringMap = {
+  USDT: "USDT20", // Your API code
+  BTC: "BTC",


NO. do not even mention allowing currency codes. all plugins should use pluginId, tokenId. show example of a hard coded mapping of partner chain identifiers to edge pluginIds.

Note, partners will also be required to support EVM chainIds so include an example of how to find the Edge pluginId based on an EVM chain id.

paullinator · 2025-08-21T20:47:59Z

docs/patterns/swap-plugin-architecture.md

+### Currency Code Validation
+
+```typescript
+// Check supported currencies


Use pluginId, tokenId. do not even mention currency codes

paullinator · 2025-08-21T20:49:55Z

docs/references/api-deprecations.md

+
+This document tracks deprecated APIs in edge-core-js that are still used in the codebase. These should be migrated when possible.
+
+## Deprecated APIs Currently in Use


Use of currencyCode is deprecated as well

paullinator · 2025-08-21T20:51:30Z

docs/patterns/swap-plugin-architecture.md

+  request.fromWallet.currencyInfo.defaultSettings?.otherSettings?.chainId;
+
+// Convert tokenId to contract address
+const contractAddress = request.fromTokenId; // tokenId IS the contract address for EVM


Not always, provide a helper function for converstion to/from based on pluginId type. evm vs cosmos vs tron, etc.

paullinator · 2025-08-21T20:52:05Z

docs/patterns/swap-plugin-architecture.md

+
+// For XRP, XLM, etc.
+if (tag != null) {
+  spendInfo.spendTargets[0].uniqueIdentifier = tag;


I think the convention is now .memos[]

paullinator · 2025-08-21T20:52:47Z

docs/patterns/swap-plugin-architecture.md

+
+// Insufficient liquidity
+if (response.error === "INSUFFICIENT_LIQUIDITY") {
+  throw new InsufficientLiquidityError(swapInfo, {


Hallucination?

paullinator · 2025-08-21T20:53:34Z

docs/patterns/swap-plugin-architecture.md

+  expirationDate?: Date; // Required for fixed quotes
+
+  // For fixed quotes
+  guaranteedAmount?: string; // The guaranteed output amount


Hallucination?

docs/patterns/swap-plugin-architecture.md

- Create AGENTS.md with build commands and code style guidelines - Add TypeScript style guide covering imports, types, and conventions - Document swap plugin architecture patterns and best practices - Capture critical business rules for DEX wallet requirements - Create step-by-step guide for adding new exchanges - Track deprecated APIs that need migration - Reference Edge company-wide conventions - Update README with quick links to key documentation This documentation provides a knowledge base for both human developers and AI coding assistants working on the edge-exchange-plugins project.

- Document DEBUG_EXCHANGE env setting in edge-react-gui - Present debug server as recommended development approach - Clarify difference between debug server and direct linking methods - Update debugging tips to emphasize hot-reload benefits

- Document chain support mapping and parameter access patterns - Emphasize critical fee estimation via transaction creation - Add destination tag/memo handling requirements - Clarify fixed vs variable quote specifications - Document reverse quote implementation - Expand error handling requirements with specific examples - Add tokenId to contract address mapping explanation - Include best practices for all new requirements

- Remove incorrect usage of deprecated defaultSettings for chain ID - Clarify that pluginId uniquely identifies the network - Update type annotations to use proper Edge types (EdgeTokenId) - Explain that tokenId is null for native/mainnet tokens - Document EdgeCurrencyWallet structure with currencyInfo/currencyConfig - Emphasize pluginId as the primary chain identifier

- Remove EVM-specific references for tokenId - Clarify tokenId applies to any chain with tokens - Explain tokenId format varies by chain type - Use more generic language (native currency vs tokens)

- Add comprehensive plugin system fundamentals section - Document how plugins attach to edge-core-js via factory pattern - Explain EdgeCorePluginOptions and plugin lifecycle - Correct API usage based on actual Edge types: - Fix currency code access (must be derived from wallet/tokenId) - Update to use networkFees array instead of networkFee - Correct memo API to use memos array - Fix EdgeSwapQuote interface properties - Add getCurrencyCode helper function example - Clarify factory function signatures and registration

- Update fetchSwapQuote to use pluginId/tokenId → symbol mapping - Add comprehensive mapping examples for chains and tokens - Include EVM chain ID mapping for exchanges that need it - Emphasize API-driven validation over hardcoded values - Fix duplicate section in prerequisites - Update error handling to reference assets instead of currencies

- Add comprehensive error handling section with priority order - Show API-driven validation instead of hardcoded values - Document error priority: region → asset support → limits - Update quote request pattern to use API validation - Replace currency validation with asset validation via API

- Add explicit section on API-driven validation - Show BAD vs GOOD examples of hardcoded vs API validation - Update best practices to prioritize API validation - Clarify what exchange APIs should return - Reinforce no hardcoded limits or asset lists

- Replace currency code helpers with exchange symbol mapping - Update error throwing examples to use request object - Fix deprecated currencyCode field in networkFee - Ensure consistent use of pluginId/tokenId terminology

- Remove fictional apiResponse properties that don't exist - Add real examples from SideShift, ChangeNow, and LetsExchange - Emphasize that each exchange has unique API response formats - Show actual error handling patterns from existing plugins - Update testing guide to reflect API-specific validation Addresses PR feedback about 'hallucination' in documentation

paullinator · 2025-08-26T23:39:22Z

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

+
+### DEX Same-Wallet Requirement
+
+- DEX swaps happen in a single transaction on-chain


This is not true. Most DEXs can have different source and dest addresses. Only the XRP DEX and the Fantom/Sonic bridge require this

paullinator · 2025-08-26T23:40:11Z

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

+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`)


There is a new swap error specifically for this. See SwapAddressError in fantomSonicUpgrade.ts

paullinator requested changes Aug 21, 2025

View reviewed changes

cursor bot reviewed Aug 22, 2025

View reviewed changes

docs/patterns/swap-plugin-architecture.md Show resolved Hide resolved

samholmes added 11 commits August 26, 2025 16:33

fix: Make tokenId documentation chain-agnostic

040b93b

- Remove EVM-specific references for tokenId - Clarify tokenId applies to any chain with tokens - Explain tokenId format varies by chain type - Use more generic language (native currency vs tokens)

refactor: Remove remaining currency code references

b2bd543

- Replace currency code helpers with exchange symbol mapping - Update error throwing examples to use request object - Fix deprecated currencyCode field in networkFee - Ensure consistent use of pluginId/tokenId terminology

paullinator force-pushed the sam/docs branch from ce06179 to 9d78e15 Compare August 26, 2025 23:33

paullinator requested changes Aug 26, 2025

View reviewed changes


		This document tracks deprecated APIs in edge-core-js that are still used in the codebase. These should be migrated when possible.

		## Deprecated APIs Currently in Use


		### DEX Same-Wallet Requirement

		- DEX swaps happen in a single transaction on-chain

Sam/docs #400

Are you sure you want to change the base?

Sam/docs #400

Uh oh!

Conversation

samholmes commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CHANGELOG

Dependencies

Description

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

samholmes commented Aug 21, 2025 •

edited

Loading