@d9-network/spec 0.0.3 → 0.0.4

package/docs/CLAUDE.md

@@ -1,364 +0,0 @@
-# D9 Chain
-
-This directory contains comprehensive developer documentation for the D9 blockchain, auto-generated from the Polkadot-API type descriptors.
-
-## Overview
-
-D9 is a Substrate-based blockchain with custom pallets and ink! smart contracts designed for:
-
-- **Referral System** - Multi-level referral tracking and rewards
-- **Node Voting** - Validator candidate voting and delegation
-- **Mining Rewards** - Token burning and mining reward distribution
-- **Merchant System** - Green points and merchant-consumer interactions
-- **Multi-Signature** - Multi-sig account management
-- **Cross-Chain Bridge** - USDT transfers between D9 and TRON
-- **AMM Trading** - D9/USDT automated market maker
-
-## Documentation Files
-
-| File | Description |
-|------|-------------|
-| [PALLETS.md](./PALLETS.md) | All pallet definitions (storage, extrinsics, events, errors, constants) |
-| [CONTRACTS.md](./CONTRACTS.md) | All ink! smart contract interfaces (messages, storage, events) |
-| [TYPES.md](./TYPES.md) | Type system documentation (enums, structs, utilities) |
-
-## Quick Reference
-
-### Chain Configuration
-
-| Property | Value |
-|----------|-------|
-| SS58 Prefix | 9 |
-| Token Symbol | D9 |
-| Token Decimals | 12 |
-| Block Time | ~3 seconds |
-| Consensus | Aura + GRANDPA |
-
-### Key Pallets
-
-#### D9 Custom Pallets
-
-| Pallet | Purpose |
-|--------|---------|
-| `D9Referral` | Referral tree management |
-| `D9Treasury` | Treasury management |
-| `D9NodeVoting` | Validator voting system |
-| `D9NodeRewards` | Node reward distribution |
-| `CouncilLock` | Account locking governance |
-| `D9MultiSig` | Multi-signature accounts |
-
-#### Standard Pallets
-
-| Pallet | Purpose |
-|--------|---------|
-| `System` | Core runtime functionality |
-| `Balances` | Native token (D9) management |
-| `Assets` | Fungible asset management |
-| `Contracts` | ink! smart contracts |
-| `Session` | Validator session management |
-| `Grandpa` | Finality gadget |
-| `Collective` | Council governance |
-| `Treasury` | On-chain treasury |
-
-### Smart Contracts
-
-| Contract | Address Key | Purpose |
-|----------|-------------|---------|
-| `usdt` | USDT Token | PSP22 USDT stablecoin |
-| `burnManager` | Burn Manager | Central burn management |
-| `burnMining` | Burn Mining | Individual burn mining pools |
-| `miningPool` | Mining Pool | Reward pool management |
-| `nodeReward` | Node Reward | Validator reward distribution |
-| `merchantMining` | Merchant Mining | Merchant green points system |
-| `marketMaker` | AMM | D9/USDT trading pool |
-| `crossChainTransfer` | Cross-Chain | D9 <-> TRON bridge |
-
-## Usage with @d9-network/spec
-
-### Installation
-
-```bash
-bun add @d9-network/spec
-```
-
-### Creating a Client
-
-```typescript
-import { createD9SdkClient } from '@d9-network/spec';
-
-const client = await createD9SdkClient();
-```
-
-### Querying Storage
-
-```typescript
-// Get account balance
-const account = await client.query.Balances.Account.getValue(address);
-console.log('Free balance:', account.free);
-
-// Get all validators
-const validators = await client.query.Session.Validators.getValue();
-```
-
-### Submitting Extrinsics
-
-```typescript
-import { createD9SdkClient, wallet } from '@d9-network/spec';
-
-const client = await createD9SdkClient();
-const signer = wallet.fromMnemonic(mnemonic);
-
-// Transfer D9 tokens
-const tx = client.tx.Balances.transfer_keep_alive({
-  dest: recipientAddress,
-  value: 1000000000000n // 1 D9
-});
-
-const result = await tx.signAndSubmit(signer);
-```
-
-### Contract Interactions
-
-```typescript
-import { contracts } from '@d9-network/spec';
-
-// Get USDT contract descriptor
-const usdtDescriptor = contracts.usdt;
-
-// Create contract instance
-const usdtContract = client.getTypedContract(
-  usdtDescriptor,
-  USDT_CONTRACT_ADDRESS
-);
-
-// Query balance
-const balance = await usdtContract.query['PSP22::balance_of']({
-  owner: userAddress
-});
-
-// Transfer tokens
-const result = await usdtContract.call.transfer({
-  to: recipientAddress,
-  value: 1000000n,
-  _data: new Uint8Array()
-});
-```
-
-## Architecture
-
-### Pallet Relationships
-
-```
-┌─────────────────┐     ┌─────────────────┐
-│   D9Referral    │────▶│   D9NodeVoting  │
-│  (Referral Tree)│     │ (Vote Delegation)│
-└─────────────────┘     └────────┬────────┘
-                                 │
-                                 ▼
-┌─────────────────┐     ┌─────────────────┐
-│  D9NodeRewards  │◀────│    Session      │
-│ (Reward Distrib)│     │  (Validators)   │
-└─────────────────┘     └─────────────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Node Reward     │
-│  (Contract)     │
-└─────────────────┘
-```
-
-### Contract Relationships
-
-```
-                    ┌─────────────────┐
-                    │   Burn Manager  │
-                    │   (Central Hub) │
-                    └────────┬────────┘
-                             │
-           ┌─────────────────┼─────────────────┐
-           ▼                 ▼                 ▼
-    ┌────────────┐    ┌────────────┐    ┌────────────┐
-    │Burn Mining │    │Burn Mining │    │Burn Mining │
-    │  Pool 1    │    │  Pool 2    │    │  Pool N    │
-    └────────────┘    └────────────┘    └────────────┘
-           │                 │                 │
-           └─────────────────┼─────────────────┘
-                             ▼
-                    ┌─────────────────┐
-                    │   Mining Pool   │
-                    │ (Reward Source) │
-                    └────────┬────────┘
-                             │
-           ┌─────────────────┼─────────────────┐
-           ▼                 ▼                 ▼
-    ┌────────────┐    ┌────────────┐    ┌────────────┐
-    │ Node Reward│    │  Merchant  │    │Market Maker│
-    │            │    │  Mining    │    │   (AMM)    │
-    └────────────┘    └────────────┘    └────────────┘
-                             │                 │
-                             │                 │
-                             ▼                 ▼
-                    ┌─────────────────────────────────┐
-                    │         USDT Contract           │
-                    │         (PSP22 Token)           │
-                    └─────────────────────────────────┘
-                                     │
-                                     ▼
-                    ┌─────────────────────────────────┐
-                    │     Cross-Chain Transfer        │
-                    │      (D9 <-> TRON Bridge)       │
-                    └─────────────────────────────────┘
-```
-
-## Common Operations
-
-### Balance Operations
-
-```typescript
-// Check D9 balance
-const balance = await client.query.Balances.Account.getValue(address);
-
-// Transfer D9
-await client.tx.Balances.transfer_keep_alive({
-  dest: recipient,
-  value: amount
-}).signAndSubmit(signer);
-
-// Check USDT balance
-const usdtBalance = await usdtContract.query['PSP22::balance_of']({
-  owner: address
-});
-```
-
-### Voting Operations
-
-```typescript
-// Add voting power (by burning D9)
-await client.tx.D9NodeVoting.add_voting_interest({
-  amount: burnAmount
-}).signAndSubmit(signer);
-
-// Delegate votes to a candidate
-await client.tx.D9NodeVoting.delegate_votes({
-  delegations: [[candidateAddress, voteAmount]]
-}).signAndSubmit(signer);
-
-// Check voting interests
-const interests = await client.query.D9NodeVoting.UsersVotingInterests.getValue(address);
-```
-
-### Mining Operations
-
-```typescript
-// Execute a burn
-await burnManagerContract.call.burn({
-  burn_beneficiary: beneficiary,
-  burn_contract: burnMiningAddress
-}, { value: burnAmount });
-
-// Withdraw rewards
-await burnManagerContract.call.withdraw({
-  burn_contract: burnMiningAddress
-});
-
-// Get portfolio
-const portfolio = await burnManagerContract.query.get_portfolio({
-  account_id: address
-});
-```
-
-### AMM Operations
-
-```typescript
-// Get pool reserves
-const reserves = await ammContract.query.get_currency_reserves({});
-// Returns [d9_reserve, usdt_reserve]
-
-// Swap D9 for USDT
-await ammContract.call.get_usdt({}, { value: d9Amount });
-
-// Swap USDT for D9
-await ammContract.call.get_d9({ usdt: usdtAmount });
-
-// Add liquidity
-await ammContract.call.add_liquidity(
-  { usdt_liquidity: usdtAmount },
-  { value: d9Amount }
-);
-```
-
-## Error Handling
-
-### Dispatch Errors
-
-```typescript
-try {
-  await tx.signAndSubmit(signer);
-} catch (error) {
-  if (error.type === 'Module') {
-    // Pallet-specific error
-    const { index, error: errorData } = error.value;
-    // Decode using metadata
-  } else if (error.type === 'Token') {
-    // Token error (insufficient balance, etc.)
-  }
-}
-```
-
-### Contract Errors
-
-```typescript
-const result = await contract.query.someMethod({ param: value });
-
-if (!result.success) {
-  // SCALE decode error
-  console.error('Decode error:', result.value);
-} else if (!result.value.success) {
-  // Contract error
-  console.error('Contract error:', result.value.value);
-} else {
-  // Success
-  console.log('Result:', result.value.value);
-}
-```
-
-## Events Subscription
-
-```typescript
-// Subscribe to all events
-client.event.System.ExtrinsicSuccess.watch().subscribe(event => {
-  console.log('Extrinsic succeeded:', event);
-});
-
-// Subscribe to transfers
-client.event.Balances.Transfer.watch().subscribe(({ from, to, amount }) => {
-  console.log(`Transfer: ${from} -> ${to}: ${amount}`);
-});
-
-// Subscribe to contract events
-// Contract events are emitted via Contracts.ContractEmitted
-```
-
-## Type Generation
-
-The types in this documentation are generated from:
-
-- **Chain metadata**: `packages/spec/.papi/metadata/`
-- **Contract ABIs**: `packages/spec/assets/ABIs/`
-- **Descriptors**: `packages/spec/.papi/descriptors/`
-
-To regenerate types after chain or contract updates:
-
-```bash
-bun --filter=@d9-network/spec run build
-```
-
-This runs:
-1. `papi` - Generates Polkadot-API descriptors from chain metadata
-2. `tsdown` - Bundles TypeScript to CJS/ESM
-
-## Related Resources
-
-- [D9 Wallet App](../../../app/) - Mobile wallet using these types
-- [D9 Ink SDK](../../ink/) - ink! contract interaction utilities
-- [Polkadot-API Docs](https://papi.how/) - Underlying API documentation