@gala-chain/gswap-sdk 0.0.9 → 1.0.0-rc.3

package/README.md

@@ -1,50 +1,78 @@
 # gSwap SDK
 
-A TypeScript SDK for interacting with the gSwap decentralized exchange on GalaChain.
+`@gala-chain/gswap-sdk` is the TypeScript SDK for the current GalaChain DEX
+contract. Version 1.0 uses trading symbols for pool operations, signs writes
+with the signer supplied by the application, and submits them through the Chain
+Gateway. Swap requests are queued for later application.
 
-⚠️ Note that documented APIs for gSwap are undergoing finalization. As a result, this version of the SDK may be deprecated in the near future. Please be prepared to upgrade to a newer version when available.
-
-## Documentation
-
-Visit [the documentation](https://galachain.github.io/gswap-sdk/docs/intro) for detailed guides and API references.
-
-## Example SDK Usage
+## Install
 
 ```bash
 npm install @gala-chain/gswap-sdk
 ```
 
+## Quick start
+
 ```typescript
 import { GSwap, PrivateKeySigner } from '@gala-chain/gswap-sdk';
 
-const gSwap = new GSwap({
-  signer: new PrivateKeySigner('your-private-key'),
+const signer = new PrivateKeySigner(process.env.GALACHAIN_PRIVATE_KEY!);
+const gSwap = new GSwap({ signer, walletAddress: process.env.GALACHAIN_ADDRESS, env: 'stage' });
+const quote = await gSwap.quoting.quoteExactInput('GALA', 'GUSDC', '100');
+const tx = await gSwap.swaps.swap('GALA', 'GUSDC', quote.feeTier, {
+  exactIn: '100',
+  amountOutMinimum: quote.amountOut,
 });
-
-const USDC_SELLING_AMOUNT = 10; // Amount of USDC to sell
-
-// Quote how much $GALA you can get for 10 USDC
-const quote = await gSwap.quoting.quoteExactInput(
-  'GUSDC|Unit|none|none',
-  'GALA|Unit|none|none',
-  USDC_SELLING_AMOUNT,
-);
-
-console.log(`Best rate found on ${quote.feeTier} fee tier pool`);
-
-// Execute a swap using the best fee tier from the quote
-const result = await gSwap.swap(
-  'GUSDC|Unit|none|none',
-  'GALA|Unit|none|none',
-  quote.feeTier,
-  {
-    exactIn: USDC_SELLING_AMOUNT,
-    amountOutMinimum: quote.outTokenAmount.multipliedBy(0.95), // 5% slippage
-  },
-  'eth|123...abc', // your wallet address
-);
+console.log({ mode: tx.mode, uniqueKey: tx.uniqueKey, transactionId: tx.transactionId });
+const applied = await tx.confirm();
+console.log(applied.result);
 ```
 
-## Disclaimer
+The `env: 'stage'` preset targets the staging swap backend, and `prod` targets
+the production swap backend. All SDK traffic uses the swap backend. Use class keys such as `GALA|Unit|none|none` when a symbol is not
+available; the SDK resolves registered symbols and orders pool tokens for you.
+Every write returns a `SubmittedTransaction`. A swap acknowledgement has
+`mode === 'queued'`, `result === undefined`, and a durable `uniqueKey`; call
+`confirm()` to read its applied outcome, or `swaps.confirmSwap(uniqueKey)` to
+resolve it later from the persisted key alone. Liquidity writes continue to
+confirm by re-reading position state. A request `transactionId` may be `null` when the
+gateway does not provide one.
+
+## Hosts and environment presets
+
+The SDK has one network boundary: the swap backend. It does not call public
+GalaChain gateway hosts directly.
+
+| Preset  | `dexBackendBaseUrl`                            |
+| ------- | ---------------------------------------------- |
+| `stage` | `https://swap-backend.stage.defi.ovh.gala.com` |
+| `prod`  | `https://dex-backend-prod1.defi.gala.com`      |
+
+Use `dexBackendBaseUrl` for a test or private deployment override.
+
+## Signers and identity
+
+| Signer                | Scheme                                                                    | Identity resolved by the chain           |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
+| `PrivateKeySigner`    | GalaChain native signature                                                | Recovered from the private key           |
+| `GalaWalletSigner`    | Native `gala_signChainDto`, with personal-sign fallback for older wallets | Selected Ethereum account (`0x...` form) |
+| `BrowserWalletSigner` | EIP-1193 `personal_sign`                                                  | Selected Ethereum account (`0x...` form) |
+
+Native signing is the default for server keys and current Gala Wallets.
+Browser wallet personal-sign signs the bare serialized DTO (the wallet applies
+the EIP-191 header) and sends that header as the DTO's `prefix`, which is what
+the chain prepends when it recovers the signer. EIP-712 is
+not part of the v2 write protocol.
+
+## Documentation
+
+Read the [gSwap SDK documentation](https://galachain.github.io/gswap-sdk/docs/intro)
+for setup, quoting, trading, liquidity, signing, migration, and API reference
+guides. Working examples are in [`examples/cli`](./examples/cli) and
+[`examples/full_dex`](./examples/full_dex).
+
+## License
 
-This SDK is provided under the Apache License 2.0. Gala™, GalaChain™, and related marks are trademarks of Blockchain Game Partners Inc. No license to use these trademarks is granted under this license. This SDK is provided “AS IS” without warranties of any kind. Use it at your own risk. Gala Games does not endorse or guarantee any third-party use or implementation of this SDK.
+This SDK is provided under the Apache License 2.0. Gala™, GalaChain™, and
+related marks are trademarks of Blockchain Game Partners Inc. This software is
+provided “AS IS” without warranties of any kind.