@pear-protocol/symmio-client 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# @pear-protocol/symmio-client
+
+Pear Protocol's standalone SDK for **Symmio** — account management via MultiAccount, trading, deposits/withdrawals, batch operations, ClearingHouse, and administrative actions.
+
+> Package rename: this SDK now publishes as `@pear-protocol/symmio-client`.
+
+## Installation
+
+```bash
+npm install @pear-protocol/symmio-client viem
+```
+
+`viem` is a peer dependency and must be installed alongside `@pear-protocol/symmio-client`.
+
+## Quick Start
+
+```typescript
+import { SymmioSDK } from '@pear-protocol/symmio-client';
+import { createPublicClient, createWalletClient, http, custom } from 'viem';
+import { arbitrum } from 'viem/chains';
+
+// Set up viem clients
+const publicClient = createPublicClient({
+  chain: arbitrum,
+  transport: http(),
+});
+
+const walletClient = createWalletClient({
+  chain: arbitrum,
+  transport: custom(window.ethereum),
+});
+
+// Initialize the Symmio client SDK
+const sdk = new SymmioSDK({
+  chainId: 42161,
+  publicClient,
+  walletClient,
+});
+```
+
+## Core Actions
+
+### Account Management
+
+```typescript
+// Create an account
+const hash = await sdk.account.addAccount('Trading Account');
+
+// Edit account name
+await sdk.account.editName(accountAddress, 'New Name');
+
+// Get all accounts for a user
+const accounts = await sdk.account.getAll(userAddress);
+
+// Get account count
+const count = await sdk.account.getCount(userAddress);
+```
+
+### Token Approval
+
+```typescript
+// Approve the MultiAccount contract to spend your USDC
+await sdk.approval.approveCollateral(amount);
+
+// Check approval state
+import { ApprovalState } from '@pear-protocol/symmio-client';
+const state = await sdk.approval.getState(tokenAddr, owner, spender, amount);
+```
+
+### Deposits
+
+```typescript
+// Standard deposit
+await sdk.deposit.standard({
+  account: '0x...',
+  amount: 100_000_000n, // 100 USDC (6 decimals)
+});
+
+// Deposit and allocate in a single transaction
+await sdk.deposit.depositAndAllocate({
+  account: '0x...',
+  amount: 100_000_000n,
+});
+```
+
+### Withdrawals
+
+```typescript
+// Withdraw from an account
+await sdk.withdraw.withdraw({
+  account: '0x...',
+  amount: 50_000_000n,
+});
+```
+
+### Allocate / Deallocate
+
+```typescript
+// Allocate collateral to trading
+await sdk.collateral.allocate(subAccount, { amount: 50_000_000n });
+
+// Deallocate with Muon signature
+const deallocSig = await sdk.getDeallocateSig(subAccount);
+await sdk.collateral.deallocate(subAccount, {
+  amount: 25_000_000n,
+  upnlSig: deallocSig,
+});
+
+// Internal transfer between accounts
+await sdk.collateral.internalTransfer(subAccount, {
+  recipient: otherAccount,
+  amount: 10_000_000n,
+});
+```
+
+### Trading
+
+```typescript
+import { PositionType, OrderType, MARKET_ORDER_DEADLINE } from '@pear-protocol/symmio-client';
+
+// Get Muon signature for opening a position
+const quoteSig = await sdk.getQuoteSig(subAccount, symbolId);
+
+// Open a position
+await sdk.trade.sendQuote(subAccount, {
+  partyBsWhiteList: ['0x...'],
+  symbolId: 1,
+  positionType: PositionType.LONG,
+  orderType: OrderType.MARKET,
+  price: 50000_000000000000000000n,
+  quantity: 1_000000000000000000n,
+  cva: ...,
+  lf: ...,
+  partyAmm: ...,
+  partyBmm: ...,
+  maxFundingRate: ...,
+  deadline: BigInt(Math.floor(Date.now() / 1000)) + MARKET_ORDER_DEADLINE,
+  affiliate: '0x...',
+  upnlSig: quoteSig,
+});
+
+// Batch open multiple positions with one Muon sig
+const batchSig = await sdk.getBatchSig(subAccount, [1, 2, 3]);
+await sdk.trade.batchSendQuote(subAccount, {
+  quotes: [quote1, quote2, quote3],
+  upnlSig: batchSig,
+});
+
+// Close a position
+await sdk.trade.closePosition(subAccount, {
+  quoteId: 1n,
+  closePrice: price,
+  quantityToClose: quantity,
+  orderType: OrderType.MARKET,
+  deadline: BigInt(Math.floor(Date.now() / 1000)) + MARKET_ORDER_DEADLINE,
+});
+
+// Cancel operations
+await sdk.trade.cancelQuote(subAccount, quoteId);
+await sdk.trade.cancelCloseRequest(subAccount, quoteId);
+```
+
+### Delegation
+
+```typescript
+// Delegate access to trading selectors
+await sdk.delegation.delegateAccess({
+  account: subAccount,
+  delegate: delegateAddress,
+  selectors: ALL_TRADING_SELECTORS,
+});
+
+// Propose to revoke access (starts cooldown)
+await sdk.delegation.proposeRevoke({
+  account: subAccount,
+  delegate: delegateAddress,
+  selectors: ALL_TRADING_SELECTORS,
+});
+
+// Revoke access (after cooldown)
+await sdk.delegation.revokeAccess({
+  account: subAccount,
+  delegate: delegateAddress,
+  selectors: ALL_TRADING_SELECTORS,
+});
+```
+
+### Terms of Service
+
+```typescript
+// Sign and store terms on-chain
+const sig = await sdk.signature.signTerms();
+await sdk.signature.storeSignature(sig);
+
+// Check if user has signed
+const hasSigned = await sdk.signature.hasSigned(userAddress);
+```
+
+## Direct Action Modules
+
+For advanced usage, all action modules are exported individually:
+
+```typescript
+import {
+  accountActions,
+  depositActions,
+  withdrawActions,
+  allocateActions,
+  tradeActions,
+  closeActions,
+  cancelActions,
+  approvalActions,
+  delegationActions,
+  signatureActions,
+  adminActions,
+} from '@pear-protocol/symmio-client';
+
+// Use prepare* functions for framework integration (wagmi, ethers, etc.)
+const prepared = tradeActions.prepareSendQuote(
+  multiAccount,
+  account,
+  subAccount,
+  params
+);
+// prepared.config contains { account, to, data, value }
+```
+
+## Utilities
+
+```typescript
+import { toWei, fromWei, formatPrice, applySlippage } from '@pear-protocol/symmio-client';
+
+const amount = toWei('100', 6);         // 100000000n
+const display = fromWei(100000000n, 6);  // "100"
+const slipped = applySlippage(price, 1.0, true); // +1% for longs
+```
+
+## Architecture
+
+```
+@pear-protocol/symmio-client
+├── client.ts          → SymmioSDK class (main entry point)
+├── actions/           → All on-chain transaction builders + executors
+│   ├── account.ts     → Account management (MultiAccount)
+│   ├── deposit.ts     → Standard deposits
+│   ├── withdraw.ts    → Withdrawals
+│   ├── allocate.ts    → Allocate, deallocate, internal transfer
+│   ├── trade.ts       → Open positions, batch, pair trades
+│   ├── close.ts       → Close, batch close, ADL close
+│   ├── cancel.ts      → Cancel quotes and close requests
+│   ├── approval.ts    → ERC-20 token approvals
+│   ├── delegation.ts  → Delegation and access management
+│   ├── signature.ts   → Terms of service signing & storage
+│   └── admin.ts       → Role admin
+├── abis/              → Contract ABIs
+├── clients/           → External service clients (Muon)
+├── constants/         → Addresses, chains, selectors, defaults
+├── types/             → Full TypeScript type system
+└── utils/             → Encoding, gas, validation, formatting
+```
+
+## Releases
+
+This package uses Changesets for versioning and npm publishing.
+
+```bash
+# create a release note for your change
+npm run changeset
+
+# apply pending version bumps and refresh package-lock.json
+npm run version-packages
+
+# publish the package to npm
+npm run release
+```
+
+The GitHub Actions release workflow expects an `NPM_TOKEN` repository secret with publish access to `@pear-protocol/symmio-client`.
+
+## License
+
+MIT