@0xslots/sdk 0.5.0 → 0.7.0

package/README.md

@@ -1,199 +1,76 @@
 # @0xslots/sdk
 
-Type-safe SDK for querying 0xSlots subgraph data with full TypeScript support.
+Unified SDK for the 0xSlots protocol — subgraph reads + on-chain writes with ERC-20 approval handling and EIP-5792 atomic batch support.
 
-## Features
-
-- 🔒 **Fully typed** - Generated from GraphQL schema with complete type safety
-- 🚀 **Chain support** - Easy chain selection (Base Sepolia, more coming)
-- 📦 **Tree-shakeable** - ESM exports with optimized bundle size
-- 🎯 **Easy to use** - Simple, intuitive API
-
-## Installation
+## Install
 
 ```bash
-npm install @0xslots/sdk
-# or
-pnpm add @0xslots/sdk
-# or
-yarn add @0xslots/sdk
-```
-
-## Quick Start
-
-```typescript
-import { createSlotsClient, SlotsChain } from '@0xslots/sdk';
-
-// Create a client for Base Sepolia
-const client = createSlotsClient({
-  chainId: SlotsChain.BASE_SEPOLIA,
-});
-
-// Query the hub
-const hub = await client.getHub({
-  id: '0x268cfaB9ddDdF6A326458Ae79d55592516f382eF',
-});
-
-console.log('Hub slot price:', hub.hub?.slotPrice);
+pnpm add @0xslots/sdk viem
 ```
 
-## Usage Examples
+## Usage
 
-### Query Lands
+### Read-only (subgraph)
 
-```typescript
-// Get all lands
-const { lands } = await client.getLands({
-  first: 10,
-  orderBy: 'createdAt',
-  orderDirection: 'desc',
-});
+```ts
+import { createSlotsClient, SlotsChain } from "@0xslots/sdk";
 
-// Get lands by owner
-const { lands: myLands } = await client.getLandsByOwner({
-  owner: '0x...',
-  first: 100,
-});
+const client = createSlotsClient({ chainId: SlotsChain.BASE_SEPOLIA });
 
-// Get a specific land with slots
-const { land } = await client.getLand({
-  id: '0x...',
-});
+const { slots } = await client.getSlots({ first: 10 });
+const { slot } = await client.getSlot({ id: "0x..." });
 ```
 
-### Query Slots
-
-```typescript
-// Get all active slots
-const { slots } = await client.getSlots({
-  where: { active: true },
-  first: 50,
-  orderBy: 'price',
-  orderDirection: 'asc',
-});
-
-// Get available (vacant) slots
-const { slots: available } = await client.getAvailableSlots({
-  first: 20,
-});
-
-// Get slots owned by an address
-const { slots: mySlots } = await client.getSlotsByOccupant({
-  occupant: '0x...',
-});
+### Read + Write
 
-// Get slot details with history
-const { slot } = await client.getSlot({
-  id: '0x...-0',
-});
-
-console.log('Price history:', slot?.priceHistory);
-console.log('Tax updates:', slot?.taxUpdates);
-```
+```ts
+import { createSlotsClient, SlotsChain } from "@0xslots/sdk";
 
-### Query Events
-
-```typescript
-// Get recent slot purchases
-const { slotPurchases } = await client.getSlotPurchases({
-  first: 50,
-  orderBy: 'timestamp',
-  orderDirection: 'desc',
-});
-
-// Get land creation events
-const { landOpenedEvents } = await client.getLandOpenedEvents({
-  first: 10,
-  orderBy: 'timestamp',
-  orderDirection: 'desc',
-});
-
-// Get flow changes (Superfluid streams)
-const { flowChanges } = await client.getFlowChanges({
-  where: { from: '0x...' },
-  first: 100,
-});
-```
-
-### Advanced Usage
-
-```typescript
-// Use custom subgraph URL
 const client = createSlotsClient({
   chainId: SlotsChain.BASE_SEPOLIA,
-  subgraphUrl: 'https://your-custom-endpoint.com/graphql',
+  factoryAddress: "0x...",
+  publicClient, // viem PublicClient
+  walletClient, // viem WalletClient
 });
 
-// Access the underlying SDK for more control
-const sdk = client.getSdk();
+// Buy handles ERC-20 approval automatically
+await client.buy({ slot: "0x...", depositAmount: 1000000n, selfAssessedPrice: 5000000n });
 
-// Access the GraphQL client directly
-const graphqlClient = client.getClient();
+await client.topUp("0x...", 500000n);
+await client.release("0x...");
+await client.collect("0x...");
 ```
 
-## Supported Chains
+## API
 
-| Chain | Chain ID | Status |
-|-------|----------|--------|
-| Base Sepolia | 84532 | ✅ Live |
+### Subgraph Queries
 
-More chains coming soon!
+`getSlots`, `getSlot`, `getSlotsByRecipient`, `getSlotsByOccupant`, `getFactory`, `getModules`, `getAccounts`, `getAccount`, `getSlotActivity`, `getRecentEvents`, `getBoughtEvents`, `getReleasedEvents`, `getLiquidatedEvents`, `getSettledEvents`, `getTaxCollectedEvents`, `getDepositedEvents`, `getWithdrawnEvents`, `getPriceUpdatedEvents`, `getMeta`
 
-## Type Safety
+### On-chain Reads
 
-All queries return fully typed responses:
+`getSlotInfo(slot)` — full slot state via RPC
 
-```typescript
-import type { GetSlotQuery, Slot } from '@0xslots/sdk';
-
-// Response types are automatically inferred
-const response: GetSlotQuery = await client.getSlot({ id: '0x...' });
-
-// Extract specific types
-const slot: Slot | null = response.slot;
-```
+### Writes (require `walletClient` + `publicClient`)
 
-## API Reference
+| Method | Description |
+|--------|-------------|
+| `createSlot(params)` | Deploy a new slot via factory |
+| `createSlots(params)` | Deploy multiple slots |
+| `buy(params)` | Buy or force-buy a slot (auto-approves ERC-20) |
+| `topUp(slot, amount)` | Add to deposit (auto-approves ERC-20) |
+| `withdraw(slot, amount)` | Withdraw from deposit |
+| `selfAssess(slot, price)` | Set self-assessed price |
+| `release(slot)` | Release slot, reclaim deposit |
+| `collect(slot)` | Flush accumulated tax to recipient |
+| `liquidate(slot)` | Liquidate insolvent slot |
+| `proposeTaxUpdate(slot, pct)` | Propose new tax rate (manager) |
+| `proposeModuleUpdate(slot, module)` | Propose new module (manager) |
+| `cancelPendingUpdates(slot)` | Cancel pending proposals (manager) |
+| `setLiquidationBounty(slot, bps)` | Set liquidation bounty (manager) |
+| `multicall(slot, calls)` | Batch multiple slot calls |
 
-### SlotsClient
-
-#### Hub Queries
-- `getHub(params)` - Get hub configuration
-- `getAllowedModules(params)` - Get allowed modules
-- `getAllowedCurrencies(params)` - Get allowed currencies
-
-#### Land Queries
-- `getLands(params)` - Get all lands with pagination
-- `getLand(params)` - Get a specific land by ID
-- `getLandsByOwner(params)` - Get lands owned by an address
-
-#### Slot Queries
-- `getSlots(params)` - Get all slots with filters
-- `getSlot(params)` - Get a specific slot with history
-- `getSlotsByOccupant(params)` - Get slots held by an address
-- `getAvailableSlots(params)` - Get vacant slots
-
-#### Event Queries
-- `getSlotPurchases(params)` - Get slot purchase events
-- `getLandOpenedEvents(params)` - Get land creation events
-- `getSlotCreatedEvents(params)` - Get slot creation events
-- `getFlowChanges(params)` - Get Superfluid flow changes
-
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Generate types from GraphQL schema
-pnpm codegen
-
-# Build the SDK
-pnpm build
-
-# Watch mode for development
-pnpm dev
-```
+ERC-20 approvals are handled automatically for `buy` and `topUp`. If the wallet supports EIP-5792 atomic batching, approve + action are sent as a single atomic call.
 
 ## License