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. - 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.