From f780c718488fcc19e034fdfd9fef32b3a3548d69 Mon Sep 17 00:00:00 2001 From: Henry Palacios Date: Mon, 4 May 2026 13:49:30 -0300 Subject: [PATCH 1/2] docs: move package docs to per-package READMEs Each published package now has its own README.md at the package root so it surfaces on npmjs.com and renders inline when browsing the package folder on GitHub. Removes the duplicated docs/packages/ folder and updates the root README cross-references. --- README.md | 8 ++-- docs/packages/protocol-core.md | 40 ------------------ docs/packages/sdk.md | 39 ------------------ packages/protocol-core/README.md | 64 +++++++++++++++++++++++++++++ packages/sdk/README.md | 70 ++++++++++++++++++++++++++++++++ 5 files changed, 138 insertions(+), 83 deletions(-) delete mode 100644 docs/packages/protocol-core.md delete mode 100644 docs/packages/sdk.md create mode 100644 packages/protocol-core/README.md create mode 100644 packages/sdk/README.md diff --git a/README.md b/README.md index f5d3805..e76d364 100755 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Overview • - Packages • + Packages • Flows • Diagrams • Glossary • @@ -24,8 +24,8 @@ Consumers pick metadata only, or the full trading toolkit on top of it. | Package | Role | Status | |---|---|---| -| [`@quickswap-defi/protocol-core`](docs/packages/protocol-core.md) | Chain configs, protocol versions, fees, native + stablecoin metadata | Published | -| [`@quickswap-defi/sdk`](docs/packages/sdk.md) | V2 entities (`Token`, `Pair`, `Route`, `Trade`), fetcher, router | Published | +| [`@quickswap-defi/protocol-core`](packages/protocol-core/) | Chain configs, protocol versions, fees, native + stablecoin metadata | Published | +| [`@quickswap-defi/sdk`](packages/sdk/) | V2 entities (`Token`, `Pair`, `Route`, `Trade`), fetcher, router | Published | ## How It Works @@ -60,7 +60,7 @@ Documentation follows [Diátaxis](https://diataxis.fr/) — each doc stays in it | Doc | Type | Description | |-----|------|-------------| | [Overview](docs/overview.md) | Explanation | What the SDK is and why the split exists | -| [Packages](docs/packages/) | Reference | Per-package role, exports, dependencies | +| [Packages](#packages) | Reference | Per-package READMEs (also published to npm) | | [Flows](docs/flows/) | Explanation | Trade execution and chain onboarding | | [Diagrams](docs/diagrams/) | Reference | C4 + sequence mermaid sources | | [Glossary](docs/glossary.md) | Reference | Domain terms | diff --git a/docs/packages/protocol-core.md b/docs/packages/protocol-core.md deleted file mode 100644 index 53c222b..0000000 --- a/docs/packages/protocol-core.md +++ /dev/null @@ -1,40 +0,0 @@ -# protocol-core — Reference - -## Role - -Pure protocol metadata for QuickSwap. Exposes the chain registry, protocol version helpers, fee -constants, and token primitives (natives, stablecoins). No on-chain calls, no math libraries. - -## Package - -`@quickswap-defi/protocol-core` — published with provenance. - -## Public exports - -- **Registry**: `CHAIN_REGISTRY`, `CHAIN_ID`, `getChain`, `getChainOrThrow`, `getSupportedChainIds` -- **Per-chain configs**: `POLYGON`, `BASE`, `MANTRA`, `MANTA`, `SONEIUM`, `SOMNIA`, `IMX`, `XLAYER`, `ZKEVM`, `DOGECHAIN`, `ETHEREUM` -- **Types**: `ChainConfig`, `ChainProtocolEntry`, `ProtocolVersion`, `SchemaVariant`, `TokenInfo`; constants `PROTOCOL_VERSIONS`, `SCHEMA_VARIANTS` -- **Protocol helpers**: `getSchemaVariant`, `getSupportedVersions`, `getProtocolVersionLabel` -- **Fees**: `V2_FEE_BPS`, `V2_FEE_RATE`, `computeV2Fee` -- **Tokens**: `getNativeToken`, `getWrappedNative`, `getStablecoins`, `getStablecoinAddresses`, `isStablecoin` - -## Inputs - -- A `chainId: number` for any lookup helper. - -## Outputs - -- Frozen `ChainConfig` objects, version labels, fee values, token metadata. - -## Depends on - -- None at runtime. TypeScript-only package. - -## Consumed by - -- `@quickswap-defi/sdk` (sibling package). -- External consumers (frontends, indexers) that need protocol metadata without trading logic. - -## Status - -Published. Source of truth for QuickSwap chain configuration. diff --git a/docs/packages/sdk.md b/docs/packages/sdk.md deleted file mode 100644 index cd8e32b..0000000 --- a/docs/packages/sdk.md +++ /dev/null @@ -1,39 +0,0 @@ -# sdk — Reference - -## Role - -Uniswap V2-fork trading SDK for QuickSwap. Provides the entity model (`Token`, `Pair`, `Route`, -`Trade`), fraction-based pricing math, an on-chain reserve fetcher, and router helpers for -building swap calldata. - -## Package - -`@quickswap-defi/sdk` — published with provenance. - -## Public exports - -- **Entities**: `Token`, `Currency`, `Pair`, `Route`, `Trade` -- **Fractions**: `Fraction`, `Percent`, `Price`, `CurrencyAmount`, `TokenAmount` -- **Constants**: `ChainId`, `TradeType`, `Rounding`, `FACTORY_ADDRESS`, `INIT_CODE_HASH`, `MINIMUM_LIQUIDITY`, `BigintIsh`, `JSBI` -- **Fetcher / Router / Errors**: on-chain reads, swap calldata builders, typed error classes - -## Inputs - -- `Token` definitions (chain id, address, decimals). -- An ethers v5 provider for on-chain fetcher calls. -- Trade parameters (input/output amounts, slippage, deadline). - -## Outputs - -- `Trade` instances with execution params, derived bounds, and price impact. -- Router calldata ready to be sent to the V2 router contract. - -## Depends on - -- `@quickswap-defi/protocol-core` (sibling package). -- `jsbi`, `big.js`, `decimal.js-light`, `tiny-invariant`, `tiny-warning`, `toformat`. -- ethers v5 (`@ethersproject/*`) — peer dependencies. - -## Status - -Published. Tested with Vitest in `packages/sdk/test/`. diff --git a/packages/protocol-core/README.md b/packages/protocol-core/README.md new file mode 100644 index 0000000..c05ad7a --- /dev/null +++ b/packages/protocol-core/README.md @@ -0,0 +1,64 @@ +# @quickswap-defi/protocol-core + +> Pure protocol metadata for QuickSwap — chain registry, protocol versions, fees, native and stablecoin token info. No on-chain calls, no math libraries. + +Part of the [QuickSwap-sdk monorepo](https://github.com/QuickSwap/QuickSwap-sdk). + +## Install + +```bash +pnpm add @quickswap-defi/protocol-core +``` + +## Quickstart + +```ts +import { + getChainOrThrow, + getSupportedChainIds, + computeV2Fee, + getStablecoins, + getNativeToken, +} from '@quickswap-defi/protocol-core' + +const polygon = getChainOrThrow(137) +const chains = getSupportedChainIds() +const native = getNativeToken(137) +const stables = getStablecoins(137) + +const feeAmount = computeV2Fee(1_000_000n) // V2 swap fee in raw units +``` + +## Public API + +- **Registry** — `CHAIN_REGISTRY`, `CHAIN_ID`, `getChain`, `getChainOrThrow`, `getSupportedChainIds` +- **Per-chain configs** — `POLYGON`, `BASE`, `MANTRA`, `MANTA`, `SONEIUM`, `SOMNIA`, `IMX`, `XLAYER`, `ZKEVM`, `DOGECHAIN`, `ETHEREUM` +- **Types** — `ChainConfig`, `ChainProtocolEntry`, `ProtocolVersion`, `SchemaVariant`, `TokenInfo` +- **Constants** — `PROTOCOL_VERSIONS`, `SCHEMA_VARIANTS` +- **Protocol helpers** — `getSchemaVariant`, `getSupportedVersions`, `getProtocolVersionLabel` +- **Fees** — `V2_FEE_BPS`, `V2_FEE_RATE`, `computeV2Fee` +- **Tokens** — `getNativeToken`, `getWrappedNative`, `getStablecoins`, `getStablecoinAddresses`, `isStablecoin` + +## Runtime dependencies + +None. TypeScript-only package. + +## Consumed by + +- [`@quickswap-defi/sdk`](../sdk/) — sibling package that builds the trading layer on top. +- External consumers (frontends, indexers, analytics) that need protocol metadata without trading logic. + +## Status + +Published with provenance. + +## Documentation + +- [Monorepo overview](../../docs/overview.md) +- [Glossary](../../docs/glossary.md) +- [Chain onboarding flow](../../docs/flows/chain-onboarding.md) +- [ADR 001 — protocol-core split](../../docs/adr/001-protocol-core-split.md) + +## License + +MIT. diff --git a/packages/sdk/README.md b/packages/sdk/README.md new file mode 100644 index 0000000..129174e --- /dev/null +++ b/packages/sdk/README.md @@ -0,0 +1,70 @@ +# @quickswap-defi/sdk + +> Uniswap V2-fork trading SDK for QuickSwap — `Token`, `Pair`, `Route`, `Trade` entities, fraction-based pricing math, on-chain reserve fetcher, and router calldata helpers. + +Part of the [QuickSwap-sdk monorepo](https://github.com/QuickSwap/QuickSwap-sdk). + +## Install + +```bash +pnpm add @quickswap-defi/sdk @quickswap-defi/protocol-core +pnpm add @ethersproject/address @ethersproject/contracts @ethersproject/providers \ + @ethersproject/networks @ethersproject/solidity +``` + +`ethers v5` packages are peer dependencies. + +## Quickstart + +```ts +import { + ChainId, + Token, + Fetcher, + Route, + Trade, + TokenAmount, + TradeType, + Percent, +} from '@quickswap-defi/sdk' + +const USDC = new Token(ChainId.MATIC, '0x2791...', 6, 'USDC', 'USD Coin') +const WMATIC = new Token(ChainId.MATIC, '0x0d50...', 18, 'WMATIC', 'Wrapped Matic') + +const pair = await Fetcher.fetchPairData(USDC, WMATIC, provider) +const route = new Route([pair], WMATIC) +const trade = new Trade(route, new TokenAmount(WMATIC, '1000000000000000000'), TradeType.EXACT_INPUT) + +const slippage = new Percent('50', '10000') // 0.5% +const minOut = trade.minimumAmountOut(slippage) +``` + +## Public API + +- **Entities** — `Token`, `Currency`, `Pair`, `Route`, `Trade` +- **Fractions** — `Fraction`, `Percent`, `Price`, `CurrencyAmount`, `TokenAmount` +- **Constants** — `ChainId`, `TradeType`, `Rounding`, `FACTORY_ADDRESS`, `INIT_CODE_HASH`, `MINIMUM_LIQUIDITY`, `JSBI` +- **Fetcher** — on-chain reserve reads via ethers provider +- **Router** — swap calldata builders +- **Errors** — typed error classes for invariant violations + +## Dependencies + +- [`@quickswap-defi/protocol-core`](../protocol-core/) — sibling, chain registry and protocol metadata. +- `jsbi`, `big.js`, `decimal.js-light`, `tiny-invariant`, `tiny-warning`, `toformat`. +- `@ethersproject/*` v5 — peer dependencies. + +## Status + +Published with provenance. + +## Documentation + +- [Monorepo overview](../../docs/overview.md) +- [Glossary](../../docs/glossary.md) +- [Trade execution flow](../../docs/flows/trade-execution.md) +- [ADRs](../../docs/adr/) + +## License + +MIT. From 52c73c525a882d11e3600279aa0537bb4557fbab Mon Sep 17 00:00:00 2001 From: Henry Palacios Date: Mon, 4 May 2026 13:53:29 -0300 Subject: [PATCH 2/2] docs: remove .github/README.md so root README is the repo README GitHub's README discovery picks .github/README.md over the root README.md. Removing the .github stub so the repo home page renders the canonical landing at the root. --- .github/README.md | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 .github/README.md diff --git a/.github/README.md b/.github/README.md deleted file mode 100644 index cd4f4d7..0000000 --- a/.github/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# GitHub Workflows - -## Workflows - -### ci.yml -- Runs on PRs and pushes to `main` -- Tests, linting, security scans -- Dependency review on PRs - -### publish.yml -- Runs on push to `main` (automatic) -- Manual trigger available via workflow_dispatch -- Publishes to npm with provenance - -## Setup Required - -1. **NPM_TOKEN**: Create an Automation token on npmjs.com and add it to repository secrets -2. **Branch Protection**: Enable on `main` branch to require PR reviews - -## Publishing - -Update version in `package.json`, merge to `main`, and publish happens automatically. -