@ainize/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Network (Common Computer Inc.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# ainize-core — shared ground
+
+The types, rules and signatures every other [Ainize](https://github.com/ainblockchain/ainize) package
+agrees on. It depends on nothing in this organisation; everything else depends on it.
+
+- **Domain types** — patches, anchors, benchmarks, catalogue entries, billing, subscription terms
+- **Identity and signing** — key handling, `signMessage` / `verifyMessage`, the teaching-key header
+  (`teachAuthMessage`, `teachAuthHeaderFor`) that the CLI, the MCP server and the browser all produce
+- **Lineage** — the parent/child rules a derived patch must satisfy, and the pre-state hash the trainer
+  and the node compute independently and compare
+- **Ledger** — local and on-chain (AIN) record writers, and the x402 payment envelope
+- **Config** — the node config schema, defaults and env overlay (`AINIZE_*`)
+
+```bash
+npm install && npm run build && npm test
+```
+
+Nothing here opens a socket, a database or a model. If a helper needs a request object or a replay
+cache it belongs in [ainize-node](https://github.com/ainblockchain/ainize-node) instead — that split is
+what lets a CLI talk to a remote node without installing a server.

package/dist/ain-ledger.d.ts

@@ -0,0 +1,191 @@
+import type { Ledger, LedgerEvents, LedgerInfo, RecordBody, SubscriptionRecord, SupersedeRecord } from './ledger.js';
+import type { Attestation, BranchInfo, Challenge, Dispute, LedgerRecord, PatchAnchor, PeerInfo, RecordKind, Settlement } from './types.js';
+import type { Identity } from './identity.js';
+/** Genesis account of the 1-node local dev chain (blockchain-configs/1-node) — public test key, dev only. */
+export declare const LOCAL_GENESIS: {
+    address: string;
+    privateKey: string;
+};
+/** Fund an address from the local dev chain's genesis account. Refuses non-local providers. */
+export declare function fundFromGenesis(providerUrl: string, to: string, amount: number): Promise<{
+    tx_hash: string;
+    balance: number;
+}>;
+/** Quick reachability probe for an AIN node. */
+export declare function ainReachable(providerUrl: string, timeoutMs?: number): Promise<boolean>;
+export interface AinLedgerOptions {
+    providerUrl: string;
+    eventHandlerUrl?: string | null;
+    chainId: number;
+    appName?: string;
+    gasPrice?: number;
+}
+/**
+ * AIN state values cannot hold JS arrays (only objects/primitives) and empty objects are pruned.
+ * toAin(): arrays → {"0":…,"1":…}; empty arrays/objects → null (key omitted); undefined → omitted.
+ * fromAin(): objects whose keys are exactly 0..n-1 → arrays. Our record schemas never use such keys otherwise.
+ */
+export declare function toAin(v: unknown): unknown;
+export declare function fromAin(v: unknown): unknown;
+/**
+ * Restore array fields that `toAin()` dropped because they were empty. Every record kind is handled with an explicit
+ * per-field line below (a generic field list cannot tell an anchor's `parents` from a branch's `patch_ids`).
+ */
+export declare function withEmptyArrays<T>(body: T): T;
+/**
+ * Rebuild ledger records from the decoded /apps/knowledge/market subtree (pure; used by refresh() and unit tests).
+ * Records are sorted oldest → newest by `ts`. Supersede and subscription values written before `created_at`
+ * existed carry no timestamp of their own: a supersede is dated right after the newest attestation (or the
+ * anchor) of the *new* patch — it is written the moment that patch reaches quorum — and authored by that
+ * patch's author; a subscription is dated right after its branch was created.
+ */
+export declare function recordsFromMarketState(market: any): LedgerRecord[];
+export declare class AinLedger implements Ledger {
+    private readonly opts;
+    private readonly identity;
+    private readonly events;
+    private readonly pollMs;
+    readonly kind: "ain";
+    readonly ain: any;
+    private cache;
+    private lastPoll;
+    private pollTimer;
+    constructor(opts: AinLedgerOptions, identity: Identity, events?: LedgerEvents, pollMs?: number);
+    get address(): string;
+    init(): Promise<void>;
+    close(): Promise<void>;
+    info(): Promise<LedgerInfo>;
+    private tx;
+    private set;
+    /**
+     * What this node's chain writes have actually cost (finding 366).
+     *
+     * The publish form gives no pricing guidance and the default price is 0.1, while the product's own estimate is
+     * ~0.19 AIN of gas around a 0.1 AIN purchase at `min_gas_price 500` — so on a real network the default price
+     * makes every sale a loss. Nothing here is estimated: `gas_cost_total` comes back on every write this node
+     * makes, and this is the average of the ones it has seen. The dev chain sends `gas_price 0`, so it measures 0
+     * and the warning correctly says nothing.
+     */
+    private gas;
+    gasStats(): {
+        writes: number;
+        total: number;
+        avg: number;
+    } | null;
+    private noteGas;
+    private static assertOk;
+    getValue(ref: string): Promise<any>;
+    /** AIN balance; an address the chain has never seen has no account yet (getBalance → null) and counts as 0. */
+    balance(address?: string): Promise<number>;
+    /**
+     * Send AIN. With `key`, the transfer is written at /transfer/$from/$to/$key instead of a random push id, which is
+     * how an x402 payment is bound to the quote it answers: the seller recomputes the key from (resource, nonce) and
+     * refuses a transfer that carries any other one (finding 344). Without `key` this is ain-js's own push behaviour,
+     * used by the royalty payouts, which answer no quote.
+     */
+    transfer(to: string, value: number, key?: string): Promise<{
+        tx_hash: string;
+        key: string;
+    }>;
+    /**
+     * Several transfers in ONE transaction (finding 366).
+     *
+     * A sale with three ancestors wrote three separate transfers, each paying its own gas — the product's own
+     * estimate is ~0.19 AIN of gas around a 0.1 AIN purchase at `min_gas_price 500`, so a family of three
+     * multiplied the loss by three. One `SET` with an op_list per payee costs one write.
+     */
+    transferMany(items: {
+        to: string;
+        value: number;
+        key: string;
+    }[]): Promise<{
+        tx_hash: string;
+    }>;
+    /** The chain's own minimum gas price, straight from `/blockchain_params` — measured, never assumed (finding 366). */
+    minGasPrice(): Promise<number | null>;
+    /** Verify an AIN transfer by tx hash: returns {from,to,value} if finalized/executed. */
+    verifyTransfer(txHash: string): Promise<{
+        from: string;
+        to: string;
+        value: number;
+        key: string;
+    } | null>;
+    /** Total AIN staked on the knowledge app (state/bandwidth budget is proportional to app stake). */
+    appStake(): Promise<number>;
+    /** Stake AIN on the knowledge app from this identity (apps on the free tier are capped at ~100 KB of state). */
+    stakeApp(amount: number): Promise<string>;
+    /**
+     * One-time app setup (run by the first node = app admin): ain-js setupApp() + market rules + app stake.
+     * Idempotent: if the app exists and we are not admin, only the stake top-up (if we can afford it) is attempted.
+     */
+    setupApp(opts?: {
+        stake?: number;
+    }): Promise<{
+        created: boolean;
+        tx?: string;
+        admin?: string;
+        staked?: number;
+    }>;
+    private setMarketRules;
+    /** The write rules this build sets, and the ones `verify()` holds the chain to. One table, so they cannot drift. */
+    static marketRules(): [string, string][];
+    append<T extends RecordBody>(kind: RecordKind, body: T): Promise<LedgerRecord<T>>;
+    /** Records are authoritative on-chain; peers don't push them to us. */
+    ingest(): Promise<boolean>;
+    /** Re-read the market subtree and rebuild the record cache. */
+    refresh(): Promise<void>;
+    list(opts?: {
+        since?: number;
+        kind?: RecordKind;
+        limit?: number;
+    }): Promise<LedgerRecord[]>;
+    get(hash: string): Promise<LedgerRecord<unknown> | null>;
+    hashes(since?: number): Promise<string[]>;
+    private byKind;
+    anchors(): Promise<LedgerRecord<PatchAnchor>[]>;
+    attestations(patchId?: string): Promise<LedgerRecord<Attestation>[]>;
+    settlements(patchId?: string): Promise<LedgerRecord<Settlement>[]>;
+    challenges(patchId?: string): Promise<LedgerRecord<Challenge>[]>;
+    disputes(patchId?: string): Promise<LedgerRecord<Dispute>[]>;
+    branches(): Promise<LedgerRecord<BranchInfo>[]>;
+    nodes(): Promise<LedgerRecord<PeerInfo>[]>;
+    supersedes(): Promise<LedgerRecord<SupersedeRecord>[]>;
+    subscriptions(): Promise<LedgerRecord<SubscriptionRecord>[]>;
+    /**
+     * What this node can actually check about the chain it trusts.
+     *
+     * Consensus guarantees that the records are the ones that were written. It guarantees nothing about WHO was
+     * allowed to write them: that is the rule engine, and the rules can only be set by the app admin — the address
+     * that happened to run `chain setup` first. This used to read one rule and only ask whether it existed, so an
+     * admin who relaxed `attestations` to let anyone sign anyone's verdict, or `patches` to let anyone overwrite
+     * anyone's anchor, changed the meaning of every record on the chain and no node said a word.
+     *
+     * So the rules are compared with the ones this build expects, and a difference is an error naming both. It is
+     * not a defence — an admin can still change them — but it is the difference between a silent change and a
+     * visible one, which is the most a participant can have while one address owns the rule engine.
+     */
+    verify(): Promise<{
+        valid: boolean;
+        checked: number;
+        errors: string[];
+    }>;
+    /**
+     * Buyer-side access receipt, exactly where ain-js `knowledge.access()` / `hasAccess()` look:
+     * /apps/knowledge/access/$buyer/{owner}_{topicKey}_{entryId} (write rule: auth.addr === $buyer).
+     */
+    recordAccess(anchor: PatchAnchor & {
+        entry_id?: string;
+    }, amount: string, currency: string, txHash: string): Promise<string | null>;
+    /** Has `buyer` an on-chain access receipt for this patch (ain-js hasAccess semantics)? */
+    hasAccess(buyer: string, anchor: PatchAnchor & {
+        entry_id?: string;
+    }): Promise<boolean>;
+    /** Knowledge-graph view (nodes/edges) straight from ain-js. */
+    graph(): Promise<{
+        nodes: Record<string, any>;
+        edges: Record<string, Record<string, any>>;
+    }>;
+    /** Access receipts of a buyer (ain-js). */
+    receipts(buyer: string): Promise<Record<string, any> | null>;
+}
+//# sourceMappingURL=ain-ledger.d.ts.map

package/dist/ain-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ain-ledger.d.ts","sourceRoot":"","sources":["../src/ain-ledger.ts"],"names":[],"mappings":"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"}