@sly-rentals/core 0.1.0 → 1.1.0

package/README.md

@@ -1,205 +1,120 @@
 # @sly-rentals/core
 
-> Simplified TypeScript SDK for SRSLY
+> TypeScript SDK for the [`srsly`](https://github.com/wuwei-labs/srsly) rental program on Solana.
 
-**Status**: pre-1.0. Surface area is stable for the current instruction set but may grow as new program features ship.
+**Status**: pre-1.0. The instruction surface tracks the on-chain program; expect minor additions as new program features ship. See [`CHANGELOG.md`](./CHANGELOG.md) for release history.
 
-## What is this?
+## What it does
 
-This is a simplified TypeScript SDK for SRSLY. It's a thin convenience wrapper around Codama-generated TypeScript clients, focusing on simplicity and maintainability.
+Builds and serializes instruction byte buffers for the `srsly` rental program. Generated by [Codama](https://github.com/codama-idl/codama) from the Anchor IDL, with thin convenience wrappers around the most-used flows (creating contracts, accepting rentals, claiming payments, settling discounts).
 
-## Key Differences from `@sly-rentals/core`
+Dual-protocol exports — pick the entry point that matches your existing stack:
 
-### Simpler (80% less code)
-- **Old**: 4,000+ lines of custom abstractions
-- **New**: ~800 lines of thin wrappers
+| Import | Returns | When to use |
+| --- | --- | --- |
+| `@sly-rentals/core` | `@solana/kit` instructions | New code; ESM-first, smaller bundle |
+| `@sly-rentals/core/legacy` | `@solana/web3.js` `TransactionInstruction[]` | Existing wallet-adapter / web3.js stacks |
+| `@sly-rentals/core/audit` | Decoded events + history helpers | Indexers, dashboards, accounting flows |
+| `@sly-rentals/core/idl` | Raw Anchor IDL JSON | Custom client generation, tx decoders |
 
-### Clearer Purpose
-- **Old**: Framework with fluent APIs, factories, builders
-- **New**: Convenience wrapper around Codama
-
-### Easier Configuration
-- **Old**: Fluent selectors, chainable configs, network modules
-- **New**: Simple global config + optional overrides
-
-### Better Maintenance
-- **Old**: Complex abstractions break when Codama updates
-- **New**: Thin wrappers adapt easily to Codama changes
-
-## Installation
+## Install
 
 ```bash
 pnpm add @sly-rentals/core
 ```
 
-## Quick Start
+## Quick start (kit)
 
-### With @solana/kit (default)
+```ts
+import { setSdkConfig, createContract, acceptRental } from '@sly-rentals/core';
 
-```typescript
-import { setSdkConfig, createContract } from '@sly-rentals/core';
+setSdkConfig({ network: 'mainnet-beta' });
 
-// Set global config once
-setSdkConfig({ network: 'atlasnet' });
-
-// Create a contract - returns @solana/kit instruction
-const instruction = await createContract({
-  owner: walletAddress,  // string address
+// Owner: list a fleet for rent
+const create = await createContract({
+  owner: ownerSigner,
   fleet: fleetAddress,
   ownerProfile: profileAddress,
-  gameId: gameAddress,
-  rate: 100, // 100 ATLAS per payment
+  rate: 100,                  // 100 ATLAS per period
   durationMax: { days: 30 },
-  paymentsFreq: '@daily'
+  paymentsFreq: '@daily',
+});
+
+// Borrower: rent a listed fleet
+const accept = await acceptRental({
+  borrower: borrowerSigner,
+  contract: contractAddress,
+  duration: { days: 7 },
 });
 ```
 
-### With @solana/web3.js
+## Quick start (legacy / web3.js)
 
-```typescript
-import { PublicKey } from '@solana/web3.js';
-import { setSdkConfig, createContract } from '@sly-rentals/core';
+```ts
+import { createContract } from '@sly-rentals/core/legacy';
 
-// Set global config with PublicKey constructor
-setSdkConfig({
-  network: 'mainnet-beta',
-  PublicKey // Enable web3.js mode
-});
-
-// Create a contract - returns web3.js TransactionInstruction
-const instruction = await createContract({
-  owner: keypair,  // Accepts web3.js Keypair
-  fleet: fleetPubkey,  // Accepts web3.js PublicKey
+const instructions = await createContract({
+  owner: ownerKeypair,
+  fleet: fleetPubkey,
   ownerProfile: profilePubkey,
-  gameId: gamePubkey,
   rate: 100,
   durationMax: { days: 30 },
-  paymentsFreq: '@daily'
+  paymentsFreq: '@daily',
 });
 
-// instruction.keys[0].pubkey is a PublicKey instance
+transaction.add(...instructions);
 ```
 
 ## Configuration
 
-### Basic Configuration
+```ts
+import { setSdkConfig } from '@sly-rentals/core';
 
-```typescript
-import { setSdkConfig, getSdkConfig, clearSdkConfig } from '@sly-rentals/core';
-
-// Set global config
 setSdkConfig({
-  network: 'atlasnet' | 'mainnet-beta' | 'localnet',
-  rpcUrl: 'https://custom-rpc.com',  // Optional
-  programId: 'custom-program-id',     // Optional
-  commitment: 'confirmed',             // Optional
-  PublicKey: PublicKey                 // Optional for web3.js mode
-});
-
-// Get current config
-const config = getSdkConfig();
-
-// Clear config (reset to defaults)
-clearSdkConfig();
-
-// Override per-call
-const ix = await createContract(params, {
-  rpcUrl: 'https://temporary-rpc.com'
+  network: 'mainnet-beta',           // 'mainnet-beta' | 'atlasnet' | 'localnet'
+  rpcUrl: 'https://your-rpc.com',    // optional override
+  commitment: 'confirmed',           // optional
 });
 ```
 
-### Network Addresses
-
-The SDK provides centralized address management for different networks:
+Per-call overrides take precedence over global config:
 
-```typescript
-import { getAddresses, ATLASNET_ADDRESSES, MAINNET_ADDRESSES } from '@sly-rentals/core';
-
-// Get addresses for current network (from global config)
-const addresses = getAddresses();
-console.log(addresses.atlasMint);  // ATLAS token mint
-console.log(addresses.sage);       // SAGE program
-console.log(addresses.srsly);      // SRSLY program
-
-// Override for specific network
-const mainnetAddrs = getAddresses({ network: 'mainnet-beta' });
-
-// Custom SRSLY program
-const customAddrs = getAddresses({ programId: 'MyCustomSRSLY...' });
-console.log(customAddrs.srsly); // 'MyCustomSRSLY...'
-
-// Direct access to network addresses
-console.log(ATLASNET_ADDRESSES);  // All atlasnet addresses
-console.log(MAINNET_ADDRESSES);   // All mainnet addresses
+```ts
+const ix = await createContract(params, { rpcUrl: 'https://temporary-rpc.com' });
 ```
 
-**Available Networks:**
-- `'atlasnet'` - Star Atlas testnet (default)
-- `'mainnet-beta'` - Solana mainnet / Star Atlas production
-- `'localnet'` - Local development
-
-**Network Addresses:**
-- `srsly` - SRSLY rental program
-- `sage` - Star Atlas SAGE program
-- `atlasMint` - ATLAS token mint
-- `profileFaction` - Profile Faction program
-- `gameId` - Star Atlas game ID
-```
-
-## API Reference
-
-### Instructions
-
-- `createContract(params, config?)` - Create a rental contract
-- `closeContract(params, config?)` - Close a rental contract
-- `acceptRental(params, config?)` - Accept a rental
-- `cancelRental(params, config?)` - Cancel a rental
-- _(More to come)_
+## Parameters
 
-### Parameters
+Instruction params accept multiple forms — pick what your stack uses:
 
-All instruction params accept:
+- **Signers**: string addresses, `@solana/kit` signers, or `@solana/web3.js` `Keypair`
+- **Addresses**: strings or `PublicKey`
+- **Rates**: numbers (ATLAS) or `{ atlas: 1.5 }` / `{ stardust: 150_000_000 }`
+- **Durations**: `{ days: 7 }`, `{ hours: 24 }`, `{ weeks: 2 }`, etc.
+- **Schedules**: `'@hourly'`, `'@daily'`, `'@weekly'`, `'@monthly'`, or a cron expression
 
-- **Signers**: String addresses, web3.js Keypairs, or @solana/kit signers
-- **Addresses**: String addresses or web3.js PublicKeys
-- **Rates**: Numbers (ATLAS) or objects `{ atlas: 1.5 }` or `{ stardust: 150_000_000 }`
-- **Durations**: Objects `{ days: 7 }`, `{ hours: 24 }`, `{ weeks: 2 }`, etc.
-- **Schedules**: Strings `'@daily'`, `'@hourly'`, or cron expressions
+## Discount authorization
 
-### Return Types
+The SDK includes a server-side helper for affiliate discounts:
 
-- **Without PublicKey in config**: Returns @solana/kit instruction
-- **With PublicKey in config**: Returns web3.js TransactionInstruction
-
-### Discount Authorization
-
-The SDK provides a `createDiscount` helper for server-side discount authorization. This is useful when an affiliate wants to offer discounts to borrowers.
-
-#### Server-side
-
-```typescript
-import { setSdkConfig, createDiscount } from '@sly-rentals/core';
-
-// Can be set once globally (e.g., at app startup)
-setSdkConfig({ rpcUrl: 'https://your-rpc-url.com' });
+```ts
+// Server: sign a discount attestation
+import { createDiscount } from '@sly-rentals/core';
 
 const discountAuth = await createDiscount({
-  address: 'AFFILIATE_MEMBER_PDA',
-  discount: 10,                         // 10% discount
-  expirySlots: 1000,                    // ~6-7 minutes from now
+  address: affiliateMemberAddress,
+  discount: 10,                   // 10% off
+  expirySlots: 1000,              // ~6–7 minutes
   discountAuthority: serverKeypair,
 });
 
-// Already JSON-safe - return directly via API
-return discountAuth;
+return discountAuth;              // JSON-safe; return directly via your API
 ```
 
-#### Client-side
-
-```typescript
+```ts
+// Client: redeem at acceptRental
 import { acceptRental } from '@sly-rentals/core';
 
-// Pass directly from server response - no deserialization needed
 const ix = await acceptRental({
   borrower: wallet,
   contract: contractAddress,
@@ -209,27 +124,25 @@ const ix = await acceptRental({
 });
 ```
 
-## Development Status
+## Network addresses
 
-- ✅ Core config system
-- ✅ Centralized address management
-- ✅ Signer handling (web3.js + kit)
-- ✅ web3.js conversion
-- ✅ Parameter converters (amount, duration, schedule)
-- ✅ First instruction: `createContract`
-- 🚧 Additional contract instructions
-- 🚧 Rental instructions
-- 🚧 Other instructions
-- 🚧 Tests
+```ts
+import { getAddresses } from '@sly-rentals/core';
+
+const addrs = getAddresses();   // current network
+addrs.atlasMint;                // ATLAS token mint
+addrs.sage;                     // SAGE program
+addrs.srsly;                    // SRSLY program
+```
 
-## Migration from `@sly-rentals/core`
+## API reference
 
-Coming soon - see migration guide once this package reaches 1.0.0.
+Full TypeDoc reference for every exported function: <https://wuwei-labs.github.io/srsly/api/core/>.
 
-## Contributing
+## Repository
 
-This package is currently in beta. Please report issues on GitHub.
+Source, on-chain program, integration tests, and the playground UI live in the monorepo: <https://github.com/wuwei-labs/srsly>.
 
 ## License
 
-ISC
+[MIT](./LICENSE). The on-chain program (`srsly`) is AGPL-3.0-only; this SDK talks to it over RPC and is not a derivative work. See the workspace [`LICENSING.md`](https://github.com/wuwei-labs/srsly/blob/main/LICENSING.md) for the rationale.