@d9-network/spec 0.0.3 → 0.0.4

package/docs/TYPES.md

@@ -1,618 +0,0 @@
-# D9 Chain Types Documentation
-
-This document describes the type system used by the D9 blockchain, including common types, enums, and type utilities from the polkadot-api integration.
-
-## Table of Contents
-
-1. [Core Types](#core-types)
-2. [Account Types](#account-types)
-3. [Balance Types](#balance-types)
-4. [Governance Types](#governance-types)
-5. [Session Types](#session-types)
-6. [Contract Types](#contract-types)
-7. [Event Types](#event-types)
-8. [Error Types](#error-types)
-9. [Type Utilities](#type-utilities)
-
----
-
-## Core Types
-
-### Basic Types
-
-| Type | TypeScript | Description |
-|------|------------|-------------|
-| `SS58String` | `string` | SS58-encoded account address (prefix 9 for D9) |
-| `Binary` | `Uint8Array` | Variable-length binary data |
-| `FixedSizeBinary<N>` | `Uint8Array` | Fixed-length binary (N bytes) |
-| `Hash` / `H256` | `FixedSizeBinary<32>` | 256-bit hash |
-| `BlockNumber` | `number` | Block number (u32) |
-| `Balance` | `bigint` | Token balance (u128) |
-| `AccountId` | `SS58String` | Account identifier |
-| `Index` | `number` | Account nonce |
-
-### Timestamp
-
-```typescript
-// Milliseconds since Unix epoch
-type Moment = bigint;
-```
-
-### Weight
-
-```typescript
-type Weight = {
-  ref_time: bigint;    // Reference time
-  proof_size: bigint;  // Proof size
-};
-```
-
----
-
-## Account Types
-
-### AccountInfo
-
-Full account information stored in the System pallet.
-
-```typescript
-type AccountInfo = {
-  nonce: number;           // Transaction count
-  consumers: number;       // Consumer reference count
-  providers: number;       // Provider reference count
-  sufficients: number;     // Sufficient reference count
-  data: AccountData;       // Balance data
-};
-```
-
-### AccountData
-
-Account balance information.
-
-```typescript
-type AccountData = {
-  free: bigint;       // Free balance
-  reserved: bigint;   // Reserved balance
-  frozen: bigint;     // Frozen balance (max of misc_frozen and fee_frozen)
-  flags: bigint;      // Extra account flags
-};
-```
-
-### MultiAddress
-
-Multi-format address used in extrinsics.
-
-```typescript
-type MultiAddress = Enum<{
-  Id: SS58String;        // Raw account ID
-  Index: number;         // Account index
-  Raw: Binary;           // Raw bytes
-  Address32: FixedSizeBinary<32>;
-  Address20: FixedSizeBinary<20>;
-}>;
-```
-
----
-
-## Balance Types
-
-### BalanceLock
-
-Balance lock information.
-
-```typescript
-type BalanceLock = {
-  id: FixedSizeBinary<8>;  // Lock identifier
-  amount: bigint;           // Locked amount
-  reasons: BalancesTypesReasons;
-};
-
-type BalancesTypesReasons = Enum<{
-  Fee: undefined;
-  Misc: undefined;
-  All: undefined;
-}>;
-```
-
-### ReserveData
-
-Named reserve information.
-
-```typescript
-type ReserveData = {
-  id: FixedSizeBinary<8>;  // Reserve identifier
-  amount: bigint;           // Reserved amount
-};
-```
-
-### BalanceStatus
-
-Balance status for reserve repatriation.
-
-```typescript
-type BalanceStatus = Enum<{
-  Free: undefined;
-  Reserved: undefined;
-}>;
-```
-
----
-
-## Governance Types
-
-### Votes
-
-Voting information for a proposal.
-
-```typescript
-type Votes = {
-  index: number;           // Proposal index
-  threshold: number;       // Required votes
-  ayes: SS58String[];      // Accounts voting aye
-  nays: SS58String[];      // Accounts voting nay
-  end: number;             // End block number
-};
-```
-
-### Proposal (Treasury)
-
-Treasury spending proposal.
-
-```typescript
-type TreasuryProposal = {
-  proposer: SS58String;
-  value: bigint;
-  beneficiary: SS58String;
-  bond: bigint;
-};
-```
-
-### Phase
-
-Execution phase of the block.
-
-```typescript
-type Phase = Enum<{
-  ApplyExtrinsic: number;    // Extrinsic index
-  Finalization: undefined;
-  Initialization: undefined;
-}>;
-```
-
----
-
-## Session Types
-
-### SessionKeys
-
-Session keys for validators.
-
-```typescript
-type SessionKeys = {
-  aura: FixedSizeBinary<32>;       // Aura key
-  grandpa: FixedSizeBinary<32>;    // GRANDPA key
-  im_online: FixedSizeBinary<32>;  // ImOnline key
-  authority_discovery: FixedSizeBinary<32>;
-};
-```
-
-### ValidatorVoteStats
-
-Validator voting statistics.
-
-```typescript
-type ValidatorVoteStats = {
-  total_votes: bigint;
-  supporter_share: number;  // Percentage (0-100)
-};
-```
-
-### NodeMetadata
-
-Node/candidate metadata.
-
-```typescript
-type NodeMetadata = {
-  name: string;
-  sharing_percent: number;
-};
-```
-
----
-
-## Contract Types
-
-### ContractInfo
-
-Contract instance information.
-
-```typescript
-type ContractInfo = {
-  trie_id: Binary;         // Storage trie ID
-  code_hash: FixedSizeBinary<32>;
-  storage_bytes: number;
-  storage_items: number;
-  storage_byte_deposit: bigint;
-  storage_item_deposit: bigint;
-  storage_base_deposit: bigint;
-};
-```
-
-### InstrumentedCode
-
-Instrumented WASM code for execution.
-
-```typescript
-type InstrumentedCode = {
-  code: Binary;
-  initial: number;
-  maximum: number;
-};
-```
-
-### CodeOwnerInfo
-
-Code ownership information.
-
-```typescript
-type CodeOwnerInfo = {
-  owner: SS58String;
-  deposit: bigint;
-  refcount: bigint;
-};
-```
-
-### Determinism
-
-Code determinism mode.
-
-```typescript
-type Determinism = Enum<{
-  Enforced: undefined;
-  Relaxed: undefined;
-}>;
-```
-
----
-
-## Event Types
-
-### EventRecord
-
-Event record stored in blocks.
-
-```typescript
-type EventRecord = {
-  phase: Phase;
-  event: RuntimeEvent;  // The actual event
-  topics: FixedSizeBinary<32>[];
-};
-```
-
-### DispatchInfo
-
-Dispatch information for extrinsics.
-
-```typescript
-type DispatchInfo = {
-  weight: Weight;
-  class: DispatchClass;
-  pays_fee: Pays;
-};
-
-type DispatchClass = Enum<{
-  Normal: undefined;
-  Operational: undefined;
-  Mandatory: undefined;
-}>;
-
-type Pays = Enum<{
-  Yes: undefined;
-  No: undefined;
-}>;
-```
-
----
-
-## Error Types
-
-### DispatchError
-
-Top-level dispatch error type.
-
-```typescript
-type DispatchError = Enum<{
-  Other: undefined;
-  CannotLookup: undefined;
-  BadOrigin: undefined;
-  Module: ModuleError;
-  ConsumerRemaining: undefined;
-  NoProviders: undefined;
-  TooManyConsumers: undefined;
-  Token: TokenError;
-  Arithmetic: ArithmeticError;
-  Transactional: TransactionalError;
-  Exhausted: undefined;
-  Corruption: undefined;
-  Unavailable: undefined;
-}>;
-```
-
-### ModuleError
-
-Pallet-specific error.
-
-```typescript
-type ModuleError = {
-  index: number;     // Pallet index
-  error: FixedSizeBinary<4>;  // Error variant
-};
-```
-
-### ArithmeticError
-
-Arithmetic operation errors.
-
-```typescript
-type ArithmeticError = Enum<{
-  Underflow: undefined;
-  Overflow: undefined;
-  DivisionByZero: undefined;
-}>;
-```
-
-### TokenError
-
-Token-related errors.
-
-```typescript
-type TokenError = Enum<{
-  FundsUnavailable: undefined;
-  OnlyProvider: undefined;
-  BelowMinimum: undefined;
-  CannotCreate: undefined;
-  UnknownAsset: undefined;
-  Frozen: undefined;
-  Unsupported: undefined;
-  CannotCreateHold: undefined;
-  NotExpendable: undefined;
-}>;
-```
-
-### TransactionalError
-
-Transactional layer errors.
-
-```typescript
-type TransactionalError = Enum<{
-  LimitReached: undefined;
-  NoLayer: undefined;
-}>;
-```
-
----
-
-## Type Utilities
-
-### Enum<T>
-
-Rust-style enum type. Only one variant is active at a time.
-
-```typescript
-type MyEnum = Enum<{
-  VariantA: undefined;      // Unit variant
-  VariantB: number;         // Variant with data
-  VariantC: { foo: string }; // Struct variant
-}>;
-
-// Usage
-const value: MyEnum = { type: 'VariantB', value: 42 };
-```
-
-### ResultPayload<T, E>
-
-Rust Result type for fallible operations.
-
-```typescript
-type ResultPayload<T, E> =
-  | { success: true; value: T }
-  | { success: false; value: E };
-```
-
-### FixedSizeArray<N, T>
-
-Fixed-length array type.
-
-```typescript
-type FixedSizeArray<N extends number, T> = T[] & { length: N };
-
-// Example: 2-element tuple
-type Pair = FixedSizeArray<2, bigint>;  // [bigint, bigint]
-```
-
-### Anonymize<T>
-
-Type utility for normalizing complex types (used internally by polkadot-api).
-
-```typescript
-// Converts nested structures to plain objects
-// Handles FixedSizeBinary, Enum, and tuple types
-type Anonymize<T> = /* ... */;
-```
-
----
-
-## D9-Specific Types
-
-### VotingInterests
-
-User voting power in the D9NodeVoting pallet.
-
-```typescript
-type VotingInterests = {
-  total_votes: bigint;      // Total voting power
-  available_votes: bigint;  // Available to delegate
-};
-```
-
-### LockInfo (CouncilLock)
-
-Account lock information.
-
-```typescript
-type LockInfo = {
-  locked_at: number;    // Block number when locked
-  reason: string;       // Lock reason
-};
-```
-
-### Referendum
-
-Active referendum data.
-
-```typescript
-type Referendum = {
-  account: SS58String;
-  proposal_type: 'Lock' | 'Unlock';
-  votes_for: number;
-  votes_against: number;
-  end_block: number;
-};
-```
-
-### MultiSignatureAccount
-
-Multi-sig account information.
-
-```typescript
-type MultiSignatureAccount = {
-  signatories: SS58String[];
-  authors: SS58String[];
-  min_approvals: number;
-};
-```
-
-### PendingCall
-
-Pending multi-sig call.
-
-```typescript
-type PendingCall = {
-  call_id: FixedSizeBinary<32>;
-  author: SS58String;
-  call_data: Binary;
-  approvals: SS58String[];
-  created_at: number;
-};
-```
-
----
-
-## Exported Types from @d9-network/spec
-
-The SDK exports the following type utilities:
-
-```typescript
-import type {
-  D9,                  // Chain descriptor type
-  D9Queries,           // All query types
-  D9Calls,             // All extrinsic types
-  D9Events,            // All event types
-  D9Errors,            // All error types
-  D9Constants,         // All constant types
-  D9DispatchError,     // Dispatch error type
-  D9CallData,          // Call data type
-  D9WhitelistEntry,    // Whitelist entry type
-} from '@d9-network/spec';
-```
-
-### Query Types
-
-```typescript
-// Query a specific storage item
-type BalanceQuery = D9Queries['Balances']['Account'];
-// Returns: (key: SS58String) => Promise<AccountData>
-```
-
-### Call Types
-
-```typescript
-// Build a specific extrinsic
-type TransferCall = D9Calls['Balances']['transfer_keep_alive'];
-// Parameters: { dest: MultiAddress, value: bigint }
-```
-
-### Event Types
-
-```typescript
-// Handle a specific event
-type TransferEvent = D9Events['Balances']['Transfer'];
-// Data: { from: SS58String, to: SS58String, amount: bigint }
-```
-
----
-
-## Contract Result Types
-
-### Contract Call Result
-
-```typescript
-type ContractCallResult<T, E> = ResultPayload<
-  ResultPayload<T, E>,  // Contract result
-  { CouldNotReadInput: undefined }  // Decode error
->;
-```
-
-### Common Contract Errors
-
-```typescript
-// PSP22 Token Errors
-type PSP22Error = Enum<{
-  Custom: string;
-  InsufficientBalance: undefined;
-  InsufficientAllowance: undefined;
-  ZeroRecipientAddress: undefined;
-  ZeroSenderAddress: undefined;
-  SafeTransferCheckFailed: string;
-}>;
-
-// Cross-contract call errors
-type InkEnvError = Enum<{
-  SomeEnvironmentError: undefined;
-  CalledContractTrapped: undefined;
-  CalledContractReverted: undefined;
-  NotCallable: undefined;
-  SomeDecodeError: undefined;
-  // ... more variants
-}>;
-```
-
----
-
-## SS58 Address Format
-
-D9 uses SS58 prefix `9` for addresses.
-
-```typescript
-// Example D9 address
-const address: SS58String = "9aBC123...xyz";
-
-// Converting from raw public key
-import { encodeAddress } from '@polkadot/util-crypto';
-const ss58Address = encodeAddress(publicKey, 9);
-```
-
-### Address Validation
-
-```typescript
-import { isAddress } from '@polkadot/util-crypto';
-
-// Check if valid SS58 address with prefix 9
-const isValidD9Address = (addr: string) => {
-  try {
-    return isAddress(addr) && decodeAddress(addr);
-  } catch {
-    return false;
-  }
-};
-```

package/scripts/papi-add-ink.ts

@@ -1,104 +0,0 @@
-#!/usr/bin/env bun
-
-import { Glob } from "bun";
-
-/**
- * Script to add all JSON files from assets/ABIs directory using papi ink add
- */
-
-const SCRIPT_DIR = import.meta.dir!;
-const SDK_DIR = `${SCRIPT_DIR}/..`;
-
-/**
- * Convert filename to camelCase key
- * Examples:
- * - "d9-usdt.json" -> "d9Usdt"
- * - "burn-manager.json" -> "burnManager"
- * - "cross_chain_transfer.json" -> "crossChainTransfer"
- * - "node_reward.json" -> "nodeReward"
- */
-function toCamelCase(filename: string): string {
-  // Remove .json extension
-  const name = filename.replace(/\.json$/, "");
-  
-  // Split by hyphens, underscores, or camelCase boundaries
-  const parts = name.split(/[-_]/);
-  
-  // Convert to camelCase
-  return parts
-    .map((part, index) => {
-      if (index === 0) {
-        // Keep first part as-is (could be lowercase or have numbers)
-        return part;
-      }
-      // Capitalize first letter of subsequent parts
-      return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
-    })
-    .join("");
-}
-
-async function main() {
-  try {
-    // Use Bun Glob to find all JSON files in assets/ABIs directory
-    const glob = new Glob("assets/ABIs/*.json");
-    const jsonFiles: string[] = [];
-
-    for await (const file of glob.scan({
-      cwd: SDK_DIR,
-    })) {
-      jsonFiles.push(file);
-    }
-
-    if (jsonFiles.length === 0) {
-      console.log("No JSON files found in assets/ABIs directory");
-      return;
-    }
-
-    console.log(`Found ${jsonFiles.length} JSON file(s) to process:\n`);
-    jsonFiles.forEach((file: string) => console.log(`  - ${file}`));
-    console.log();
-
-    // Process each JSON file
-    for (const file of jsonFiles) {
-      const fileName = file.split("/").pop() || file;
-      const camelKey = toCamelCase(fileName);
-      console.log(`Processing: ${fileName} (key: ${camelKey})`);
-
-      try {
-        // Execute papi ink add command with -k parameter using Bun.$ from SDK directory
-        const result = await Bun.$`bun papi ink add ${file} -k ${camelKey} --skip-codegen`.cwd(SDK_DIR);
-
-        if (result.exitCode === 0) {
-          console.log(`✓ Successfully added: ${fileName}`);
-          const output = result.stdout.toString().trim();
-          if (output) {
-            console.log(`  ${output}`);
-          }
-          console.log();
-        } else {
-          console.error(`✗ Failed to add: ${fileName}`);
-          const errorOutput = result.stderr.toString().trim();
-          if (errorOutput) {
-            console.error(`  ${errorOutput}`);
-          }
-          const stdoutOutput = result.stdout.toString().trim();
-          if (stdoutOutput) {
-            console.error(`  ${stdoutOutput}`);
-          }
-          console.log();
-        }
-      } catch (error) {
-        console.error(`✗ Error processing ${fileName}:`, error);
-        console.log();
-      }
-    }
-
-    Bun.$`bun papi`.cwd(SDK_DIR);
-    console.log("Done!");
-  } catch (error) {
-    console.error("Error processing files:", error);
-    process.exit(1);
-  }
-}
-
-main();