@awarizon/core 2.0.0

package/README.md

@@ -0,0 +1,264 @@
+# @awarizon/core
+
+High-level SDK for building on the Awarizon blockchain. 10x faster than working with raw chain primitives.
+
+Wraps `@awarizon/sdk` with natural-language amounts, simple async/await, built-in key management, and human-readable errors.
+
+## Install
+
+```bash
+npm install @awarizon/core
+```
+
+## Quick Start
+
+```typescript
+import { createCore } from '@awarizon/core'
+
+const core = await createCore({ endpoint: 'ws://127.0.0.1:9944' })
+
+// Generate a wallet
+const wallet = core.keyring.generate()
+console.log(wallet.address)   // SS58 address
+console.log(wallet.mnemonic)  // 12-word phrase
+
+// Check balance
+const balance = await core.wallet.balance(wallet.address)
+console.log(balance.free)   // "0.0000 RIZ"
+
+// Send RIZ
+const signer = core.keyring.fromMnemonic(wallet.mnemonic)
+const tx = await core.wallet.send({ to: '5GrwvaEF...', amount: '10 RIZ', signer })
+console.log(tx.hash)
+
+await core.disconnect()
+```
+
+## Key Management
+
+```typescript
+import { AwarizonKeyring } from '@awarizon/core'
+
+const keyring = new AwarizonKeyring()
+await keyring.initialize()
+
+// Generate
+const wallet = keyring.generate()           // { mnemonic, address, publicKey }
+const wallet24 = keyring.generate(24)       // 24-word mnemonic
+
+// Import
+const pair = keyring.fromMnemonic('word1 word2 ... word12')
+
+// Derive child accounts (multi-account support)
+const account0 = keyring.derive(wallet.mnemonic, '//0')
+const account1 = keyring.derive(wallet.mnemonic, '//1')
+
+// Encrypt/decrypt for storage
+const encrypted = keyring.encrypt(pair, 'myPassword')  // JSON string
+const decrypted = keyring.decrypt(encrypted, 'myPassword')
+
+// Export/import Polkadot-compatible JSON backup
+const json = keyring.exportJson(pair, 'password')
+const restored = keyring.importJson(json, 'password')
+```
+
+## Wallet Operations
+
+```typescript
+// Balance
+const balance = await core.wallet.balance(address)
+// { free: "100.0000 RIZ", staked: "0.0000 RIZ", total: "100.0000 RIZ", freePlanck: 100000000000000n }
+
+// Send
+const tx = await core.wallet.send({ to: recipientAddress, amount: '10 RIZ', signer })
+// { hash: "0x...", blockNumber: 0, success: true }
+
+// Total issuance
+const supply = await core.wallet.totalIssuance()   // "1,000,000.0000 RIZ"
+```
+
+## Inbox
+
+```typescript
+// List inbox items
+const items = await core.inbox.list(address)
+// [{ recordId, campaignId, developer, category, status, rewardEligible, ... }]
+
+// Count
+const count = await core.inbox.count(address)
+
+// Engage with content
+const tx = await core.inbox.engage({
+  recordId: '0xabc...',
+  sessionSeconds: 300,   // optional, defaults to MIN_SESSION_SECONDS (120)
+  interactions: 10,      // optional, defaults to MIN_INTERACTIONS (5)
+  signer,
+})
+
+// Claim reward
+const reward = await core.inbox.claim({ recordId: '0xabc...', signer })
+console.log(reward.reward)   // "1.0000 RIZ"
+
+// Dismiss
+await core.inbox.dismiss({ recordId: '0xabc...', signer })
+```
+
+## Developer Tools
+
+```typescript
+// Register as developer
+await core.developer.register({ signer })
+
+// Stake RIZ
+await core.developer.stake({ amount: '10000 RIZ', signer })
+
+// Check status
+const status = await core.developer.status(address)
+// { registered: true, verified: false, stake: "10000.0000 RIZ", totalCampaigns: 0, ... }
+
+// Register app manifest
+const app = await core.apps.register({
+  manifestHash: '0xabc123...',   // 32-byte hex
+  category: 'Gaming',
+  metadataUri: 'ipfs://Qm...',
+  signer,
+})
+console.log(app.manifestHash)
+
+// List developer manifests
+const manifests = await core.apps.list(developerAddress)
+
+// Create campaign
+const campaign = await core.campaigns.create({
+  manifestHash: '0xabc123...',
+  targeting: {
+    categories: ['Gaming', 'DeFi'],
+    minBalance: '10 RIZ',
+    minWalletAge: 30,     // days
+  },
+  durationDays: 30,
+  maxDeliveries: 10000n,
+  signer,
+})
+console.log(campaign.campaignId)
+
+// Get campaign
+const c = await core.campaigns.get(campaignId)
+// { campaignId, status, maxDeliveries, currentDeliveries, ... }
+
+// Delivery status
+const ds = await core.campaigns.deliveryStatus(campaignId)
+// { current: 42, max: 10000, remaining: 9958, percentage: 0 }
+
+// Terminate
+await core.campaigns.terminate({ campaignId, signer })
+```
+
+## Assets
+
+```typescript
+// Create fungible token (pallet-assets)
+const asset = await core.assets.create({
+  id: 1,
+  admin: myAddress,
+  minBalance: 1n,
+  signer,
+})
+
+// Mint tokens
+await core.assets.mint({ assetId: 1, to: recipientAddress, amount: 1000n, signer })
+
+// Transfer
+await core.assets.transfer({ assetId: 1, to: recipientAddress, amount: 100n, signer })
+
+// Burn
+await core.assets.burn({ assetId: 1, who: myAddress, amount: 50n, signer })
+
+// Check balance
+const bal = await core.assets.balance({ assetId: 1, address: myAddress })
+// { assetId: 1, symbol: "1", balance: "950", balanceRaw: 950n }
+```
+
+## NFTs
+
+```typescript
+// Create collection (pallet-nfts)
+await core.nfts.createCollection({ collectionId: 1, admin: myAddress, signer })
+
+// Mint NFT
+await core.nfts.mint({ collection: 1, itemId: 0, owner: myAddress, signer })
+
+// Transfer
+await core.nfts.transfer({ collection: 1, item: 0, to: recipientAddress, signer })
+
+// Owner
+const owner = await core.nfts.ownerOf({ collection: 1, item: 0 })
+
+// List owned NFTs
+const nfts = await core.nfts.list(myAddress)
+// [{ collection: 1, item: 0, owner: "5G...", metadata: {} }]
+```
+
+## Validators
+
+```typescript
+// Register as validator
+await core.validators.register({
+  stake: '10000 RIZ',
+  regionCode: 1,
+  countryCode: 44,
+  signer,
+})
+
+// Delegate stake
+await core.validators.delegate({ to: validatorAddress, amount: '1000 RIZ', signer })
+
+// Undelegate
+await core.validators.undelegate({ from: validatorAddress, signer })
+
+// Performance info
+const info = await core.validators.performance(validatorAddress)
+// { selfStake, delegatedStake, totalStake, performanceScore, uptime, slashCount, isActive }
+
+// List all active validators
+const validators = await core.validators.list()
+```
+
+## Network
+
+```typescript
+const stats = await core.network.stats()
+// { totalWallets, totalDeliveries, activeCampaigns, totalStaked, currentEpoch, ... }
+
+const count = await core.network.validatorCount()
+const active = await core.network.activeValidators()   // string[] of SS58 addresses
+
+// Subscribe to new blocks
+const unsub = await core.network.subscribeBlocks((blockNumber, hash) => {
+  console.log(`Block #${blockNumber}: ${hash}`)
+})
+unsub()  // stop subscription
+```
+
+## Amount Format
+
+All public API inputs accept human-readable RIZ strings. All outputs return formatted strings.
+
+```typescript
+import { parseAmount, formatAmount, isValidAmount } from '@awarizon/core'
+
+// String → planck bigint (internal representation)
+parseAmount('10 RIZ')        // 10_000_000_000_000n
+parseAmount('0.5 RIZ')       // 500_000_000_000n
+parseAmount('10')            // 10_000_000_000_000n  (RIZ suffix optional)
+
+// planck bigint → display string
+formatAmount(10_000_000_000_000n)       // "10.0000 RIZ"
+formatAmount(10_000_000_000_000n, 2)    // "10.00 RIZ"
+
+// Validate
+isValidAmount('10 RIZ')    // true
+isValidAmount('abc')       // false
+```
+
+RIZ has 12 decimal places (`1 RIZ = 1_000_000_000_000 planck`). Never pass raw planck values to public API methods — always use `"10 RIZ"` strings.

package/dist/index.d.mts

@@ -0,0 +1,420 @@
+import { ApiPromise } from '@polkadot/api';
+import { KeyringPair } from '@polkadot/keyring/types';
+import { AppCategory, IdentityRecord, NameLookup, ChainType, LinkedAddress } from '@awarizon/sdk';
+export { ChainType, DEFAULT_ENDPOINT, IdentityRecord, LinkStatus, LinkedAddress, MAX_CAMPAIGN_DURATION_DAYS, MICRO_RIZ, MIN_CAMPAIGN_DURATION_DAYS, MIN_INTERACTIONS, MIN_SESSION_SECONDS, NameLookup, PLANCK, RIZ } from '@awarizon/sdk';
+
+interface TxResult {
+    hash: string;
+    blockNumber: number;
+    success: boolean;
+}
+interface Balance {
+    free: string;
+    staked: string;
+    reserved: string;
+    total: string;
+    freePlanck: bigint;
+}
+interface GeneratedWallet {
+    mnemonic: string;
+    address: string;
+    publicKey: string;
+}
+interface WalletAccount {
+    address: string;
+    publicKey: string;
+    name?: string;
+}
+interface InboxItem {
+    recordId: string;
+    campaignId: string;
+    developer: string;
+    manifestHash: string;
+    category: string;
+    status: 'Pending' | 'Delivered' | 'Dismissed' | 'Engaged';
+    deliveredAt: number;
+    engagedAt: number | null;
+    rewardClaimed: boolean;
+    rewardEligible: boolean;
+}
+interface ClaimResult extends TxResult {
+    reward: string;
+}
+interface DeveloperStatus {
+    registered: boolean;
+    verified: boolean;
+    stake: string;
+    totalCampaigns: number;
+    totalDeliveries: number;
+    violationCount: number;
+}
+interface AppManifest {
+    manifestHash: string;
+    developer: string;
+    category: string;
+    registeredAt: number;
+    metadataUri: string;
+}
+interface Campaign {
+    campaignId: string;
+    developer: string;
+    manifestHash: string;
+    status: 'Pending' | 'Active' | 'Expired' | 'Terminated';
+    createdAt: number;
+    expiresAt: number;
+    maxDeliveries: number;
+    currentDeliveries: number;
+    targetingDescription: string;
+}
+interface Asset {
+    id: number;
+    name: string;
+    symbol: string;
+    decimals: number;
+    supply: string;
+    owner: string;
+}
+interface AssetBalance {
+    assetId: number;
+    symbol: string;
+    balance: string;
+    balanceRaw: bigint;
+}
+interface NFTItem {
+    collection: number;
+    item: number;
+    owner: string;
+    metadata: Record<string, unknown>;
+}
+interface ValidatorInfo {
+    address: string;
+    selfStake: string;
+    delegatedStake: string;
+    totalStake: string;
+    performanceScore: number;
+    uptime: number;
+    slashCount: number;
+    isActive: boolean;
+}
+interface NetworkStats {
+    totalWallets: number;
+    totalDeliveries: number;
+    activeCampaigns: number;
+    totalStaked: string;
+    currentEpoch: number;
+    inboxReserve: string;
+    totalExtrinsics: number;
+    circulatingSupply: string;
+    nonCirculatingSupply: string;
+}
+interface TargetingOptions {
+    categories?: string[];
+    minBalance?: string;
+    maxBalance?: string;
+    minWalletAge?: number;
+    maxWalletAge?: number;
+    minActivity?: number;
+    maxActivity?: number;
+    regions?: number[];
+}
+
+declare class AwarizonKeyring {
+    private keyring;
+    constructor();
+    initialize(): Promise<void>;
+    generate(wordCount?: 12 | 24): GeneratedWallet;
+    validate(mnemonic: string): boolean;
+    fromMnemonic(mnemonic: string): KeyringPair;
+    derive(mnemonic: string, path: string): KeyringPair;
+    encrypt(pair: KeyringPair, password: string): string;
+    decrypt(encrypted: string, password: string): KeyringPair;
+    getAccount(pair: KeyringPair): WalletAccount;
+    exportJson(pair: KeyringPair, password: string): string;
+    importJson(json: string, password: string): KeyringPair;
+    toAddress(publicKey: string): string;
+}
+
+declare class NetworkModule {
+    private api;
+    constructor(api: ApiPromise);
+    stats(): Promise<NetworkStats>;
+    tokenStats(): Promise<{
+        totalIssuance: string;
+        engagementPool: string;
+    }>;
+    validatorCount(): Promise<number>;
+    activeValidators(): Promise<string[]>;
+    subscribeBlocks(callback: (blockNumber: number, hash: string) => void): Promise<() => void>;
+}
+
+declare class WalletModule {
+    private api;
+    constructor(api: ApiPromise);
+    balance(address: string): Promise<Balance>;
+    send(params: {
+        to: string;
+        amount: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    totalIssuance(): Promise<string>;
+}
+
+declare class InboxModule {
+    private api;
+    constructor(api: ApiPromise);
+    list(address: string): Promise<InboxItem[]>;
+    get(address: string, recordId: string): Promise<InboxItem | null>;
+    count(address: string): Promise<number>;
+    engage(params: {
+        recordId: string;
+        sessionSeconds?: number;
+        interactions?: number;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    claim(params: {
+        recordId: string;
+        signer: KeyringPair;
+    }): Promise<ClaimResult>;
+    dismiss(params: {
+        recordId: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+}
+
+declare class DeveloperModule {
+    private api;
+    constructor(api: ApiPromise);
+    register(params: {
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    stake(params: {
+        amount: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    status(address: string): Promise<DeveloperStatus | null>;
+}
+
+declare class AppsModule {
+    private api;
+    constructor(api: ApiPromise);
+    register(params: {
+        manifestHash: string;
+        category: AppCategory;
+        metadataUri: string;
+        signer: KeyringPair;
+    }): Promise<TxResult & {
+        manifestHash: string;
+    }>;
+    list(developerAddress: string): Promise<AppManifest[]>;
+}
+
+declare class CampaignsModule {
+    private api;
+    constructor(api: ApiPromise);
+    create(params: {
+        manifestHash: string;
+        targeting: TargetingOptions;
+        durationDays: number;
+        maxDeliveries: bigint;
+        signer: KeyringPair;
+    }): Promise<TxResult & {
+        campaignId: string;
+    }>;
+    get(campaignId: string): Promise<Campaign | null>;
+    terminate(params: {
+        campaignId: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    deliver(params: {
+        campaignId: string;
+        wallet: string;
+        recordId: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    deliveryStatus(campaignId: string): Promise<{
+        current: number;
+        max: number;
+        remaining: number;
+        percentage: number;
+    } | null>;
+    describeTargeting(opts: TargetingOptions): string;
+}
+
+declare class AssetsModule {
+    private api;
+    constructor(api: ApiPromise);
+    create(params: {
+        id: number;
+        admin: string;
+        minBalance: bigint;
+        signer: KeyringPair;
+    }): Promise<TxResult & {
+        assetId: number;
+    }>;
+    mint(params: {
+        assetId: number;
+        to: string;
+        amount: bigint;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    transfer(params: {
+        assetId: number;
+        to: string;
+        amount: bigint;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    burn(params: {
+        assetId: number;
+        who: string;
+        amount: bigint;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    balance(params: {
+        assetId: number;
+        address: string;
+    }): Promise<AssetBalance>;
+    metadata(assetId: number): Promise<{
+        name: string;
+        symbol: string;
+        decimals: number;
+    }>;
+    info(assetId: number): Promise<Asset | null>;
+}
+
+declare class NFTsModule {
+    private api;
+    constructor(api: ApiPromise);
+    createCollection(params: {
+        collectionId: number;
+        admin: string;
+        signer: KeyringPair;
+    }): Promise<TxResult & {
+        collectionId: number;
+    }>;
+    mint(params: {
+        collection: number;
+        itemId: number;
+        owner: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    transfer(params: {
+        collection: number;
+        item: number;
+        to: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    burn(params: {
+        collection: number;
+        item: number;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    ownerOf(params: {
+        collection: number;
+        item: number;
+    }): Promise<string | null>;
+    list(address: string): Promise<NFTItem[]>;
+}
+
+declare class ValidatorsModule {
+    private api;
+    constructor(api: ApiPromise);
+    register(params: {
+        stake: string;
+        regionCode: number;
+        countryCode: number;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    delegate(params: {
+        to: string;
+        amount: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    undelegate(params: {
+        from: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    performance(address: string): Promise<ValidatorInfo | null>;
+    list(): Promise<ValidatorInfo[]>;
+}
+
+declare class IdentityModule {
+    private api;
+    constructor(api: ApiPromise);
+    get(address: string): Promise<IdentityRecord | null>;
+    lookup(name: string): Promise<NameLookup | null>;
+    isAvailable(name: string): Promise<boolean>;
+    register(params: {
+        rizName?: string;
+        displayName?: string;
+        bio?: string;
+        avatarUri?: string;
+        website?: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    update(params: {
+        displayName?: string;
+        bio?: string;
+        avatarUri?: string;
+        website?: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    recalculateReputation(params: {
+        account: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+}
+
+declare class LinksModule {
+    private api;
+    constructor(api: ApiPromise);
+    buildEvmLinkMessage(awarizonAddress: string): string;
+    buildSolanaLinkMessage(awarizonAddress: string): string;
+    linkEvm(params: {
+        evmAddress: string;
+        signature: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    linkSolana(params: {
+        solanaPubkey: string;
+        signature: string;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    unlink(params: {
+        chain: ChainType;
+        signer: KeyringPair;
+    }): Promise<TxResult>;
+    list(address: string): Promise<LinkedAddress[]>;
+}
+
+interface CoreConfig {
+    endpoint: string;
+}
+declare class AwarizonCore {
+    private config;
+    private client;
+    private api;
+    readonly keyring: AwarizonKeyring;
+    network: NetworkModule;
+    wallet: WalletModule;
+    inbox: InboxModule;
+    developer: DeveloperModule;
+    apps: AppsModule;
+    campaigns: CampaignsModule;
+    assets: AssetsModule;
+    nfts: NFTsModule;
+    validators: ValidatorsModule;
+    identity: IdentityModule;
+    links: LinksModule;
+    constructor(config: CoreConfig);
+    connect(): Promise<this>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getApi(): ApiPromise;
+}
+declare function createCore(config: CoreConfig): Promise<AwarizonCore>;
+
+declare function parseAmount(input: string): bigint;
+declare function formatAmount(planck: bigint, decimals?: number): string;
+declare function isValidAmount(input: string): boolean;
+
+export { type AppManifest, type Asset, type AssetBalance, AwarizonCore, AwarizonKeyring, type Balance, type Campaign, type ClaimResult, type CoreConfig, type DeveloperStatus, type GeneratedWallet, type InboxItem, type NFTItem, type NetworkStats, type TargetingOptions, type TxResult, type ValidatorInfo, type WalletAccount, createCore, formatAmount, isValidAmount, parseAmount };