@r3e/neo-js-sdk 0.3.0

package/README.md

@@ -0,0 +1,117 @@
+# neo-js-sdk
+
+Neo N3 JavaScript/TypeScript SDK with a typed RPC client, core transaction primitives, and NEP-2 / NEP-6 wallet helpers.
+
+## What It Includes
+
+- Neo N3 network constants and native contract hash helpers
+- `H160` / `H256` hash wrappers
+- Binary serialization helpers
+- `PrivateKey`, `PublicKey`, `Witness`, `Signer`, `Tx`, `Header`, `Block`, `TrimmedBlock`
+- `ScriptBuilder`, `OpCode`, `CallFlags`
+- NEP-2 helpers and NEP-6 wallet/account models
+- Typed JSON-RPC coverage across core, state-service, and wallet-node methods with modeled outputs and object-based inputs
+- A single canonical `camelCase` API surface for JavaScript and TypeScript consumers
+
+## Install
+
+```bash
+npm install neo-js-sdk
+```
+
+## Verification
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+Optional live RPC smoke test against Neo testnet:
+
+```bash
+npm run test:integration
+```
+
+Override the default testnet endpoint if needed:
+
+```bash
+NEO_RPC_URL=https://your-rpc-node npm run test:integration
+```
+
+## Usage
+
+```ts
+import {
+  CallFlags,
+  InvokeParameters,
+  PrivateKey,
+  RpcClient,
+  ScriptBuilder,
+  Signer,
+  Tx,
+  WitnessScope,
+  gasContractHash,
+  testNetworkId
+} from "neo-js-sdk";
+
+const privateKey = new PrivateKey(
+  "f046222512e7258c62f56f5e9e624d08c8dc38f336a15f320b3501ec7e90d7c6"
+);
+
+const script = new ScriptBuilder()
+  .emitContractCall(gasContractHash(), "transfer", CallFlags.All, [
+    "from",
+    "to",
+    1
+  ])
+  .toBytes();
+
+const tx = new Tx({
+  nonce: 1,
+  systemFee: 1_0000000n,
+  networkFee: 1_0000000n,
+  validUntilBlock: 100,
+  script,
+  signers: [
+    new Signer({
+      account: privateKey.publicKey().getScriptHash(),
+      scopes: WitnessScope.CalledByEntry
+    })
+  ]
+});
+
+tx.witnesses = [privateKey.signWitness(tx.getSignData(testNetworkId()))];
+
+const client = new RpcClient("https://seed1t5.neo.org:20332");
+await client.sendRawTransaction({ tx });
+
+const invoke = await client.invokeFunction({
+  contractHash: gasContractHash(),
+  method: "balanceOf",
+  args: new InvokeParameters().addHash160(privateKey.publicKey().getScriptHash())
+});
+```
+
+## Wallet Helpers
+
+```ts
+import { Wallet } from "neo-js-sdk";
+
+const wallet = new Wallet({ name: "demo", passphrase: "secret" });
+const account = wallet.createAccount();
+
+wallet.writeToFile("./wallet.json");
+
+const reopened = Wallet.openNep6Wallet("./wallet.json");
+reopened.decrypt("secret");
+```
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run test:integration
+```

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+import { H160 } from "./core/hash.js";
+export declare const MAIN_NETWORK_ID = 860833102;
+export declare const TEST_NETWORK_ID = 894710606;
+export declare const ADDRESS_VERSION = 53;
+export declare const NEO_CONTRACT_HASH = "0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5";
+export declare const GAS_CONTRACT_HASH = "0xd2a4cff31913016155e38e474a2c06d08be276cf";
+export declare const STDLIB_CONTRACT_HASH = "0xacce6fd80d44e1796aa0c2c625e9e4e0ce39efc0";
+export declare const CRYPTOLIB_CONTRACT_HASH = "0x726cb6e0cd8628a1350a611384688911ab75f51b";
+export declare const LEDGER_CONTRACT_HASH = "0xda65b600f7124ce6c79950c1772a36403104f2be";
+export declare const ORACLE_CONTRACT_HASH = "0xfe924b7cfe89ddd271abaf7210a80a7e11178758";
+export declare const POLICY_CONTRACT_HASH = "0xcc5e4edd9f5f8dba8bb65734541df7a1c081c67b";
+export declare const NOTARY_CONTRACT_HASH = "0xc1e14f19c3e60d0b9244d06dd7ba9b113135ec3b";
+export declare const ROLE_MANAGEMENT_CONTRACT_HASH = "0x49cf4e5378ffcd4dec034fd98a174c5491e395e2";
+export declare function mainNetworkId(): number;
+export declare function testNetworkId(): number;
+export declare function addressVersion(): number;
+export declare const neoContractHash: () => H160;
+export declare const gasContractHash: () => H160;
+export declare const stdlibContractHash: () => H160;
+export declare const cryptolibContractHash: () => H160;
+export declare const ledgerContractHash: () => H160;
+export declare const oracleContractHash: () => H160;
+export declare const policyContractHash: () => H160;
+export declare const notaryContractHash: () => H160;
+export declare const roleManagementContractHash: () => H160;

package/dist/constants.js

@@ -0,0 +1,34 @@
+import { H160 } from "./core/hash.js";
+export const MAIN_NETWORK_ID = 860833102;
+export const TEST_NETWORK_ID = 894710606;
+export const ADDRESS_VERSION = 53;
+export const NEO_CONTRACT_HASH = "0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5";
+export const GAS_CONTRACT_HASH = "0xd2a4cff31913016155e38e474a2c06d08be276cf";
+export const STDLIB_CONTRACT_HASH = "0xacce6fd80d44e1796aa0c2c625e9e4e0ce39efc0";
+export const CRYPTOLIB_CONTRACT_HASH = "0x726cb6e0cd8628a1350a611384688911ab75f51b";
+export const LEDGER_CONTRACT_HASH = "0xda65b600f7124ce6c79950c1772a36403104f2be";
+export const ORACLE_CONTRACT_HASH = "0xfe924b7cfe89ddd271abaf7210a80a7e11178758";
+export const POLICY_CONTRACT_HASH = "0xcc5e4edd9f5f8dba8bb65734541df7a1c081c67b";
+export const NOTARY_CONTRACT_HASH = "0xc1e14f19c3e60d0b9244d06dd7ba9b113135ec3b";
+export const ROLE_MANAGEMENT_CONTRACT_HASH = "0x49cf4e5378ffcd4dec034fd98a174c5491e395e2";
+function hashFactory(value) {
+    return () => new H160(value);
+}
+export function mainNetworkId() {
+    return MAIN_NETWORK_ID;
+}
+export function testNetworkId() {
+    return TEST_NETWORK_ID;
+}
+export function addressVersion() {
+    return ADDRESS_VERSION;
+}
+export const neoContractHash = hashFactory(NEO_CONTRACT_HASH);
+export const gasContractHash = hashFactory(GAS_CONTRACT_HASH);
+export const stdlibContractHash = hashFactory(STDLIB_CONTRACT_HASH);
+export const cryptolibContractHash = hashFactory(CRYPTOLIB_CONTRACT_HASH);
+export const ledgerContractHash = hashFactory(LEDGER_CONTRACT_HASH);
+export const oracleContractHash = hashFactory(ORACLE_CONTRACT_HASH);
+export const policyContractHash = hashFactory(POLICY_CONTRACT_HASH);
+export const notaryContractHash = hashFactory(NOTARY_CONTRACT_HASH);
+export const roleManagementContractHash = hashFactory(ROLE_MANAGEMENT_CONTRACT_HASH);

package/dist/core/block.d.ts

@@ -0,0 +1,65 @@
+import { H160, H256 } from "./hash.js";
+import { BinaryReader, BinaryWriter } from "./serializing.js";
+import { Tx } from "./tx.js";
+import { Witness } from "./witness.js";
+export declare class Header {
+    readonly version: number;
+    readonly previousBlockHash: H256;
+    readonly merkleRoot: H256;
+    readonly unixMillis: bigint;
+    readonly nonce: number;
+    readonly index: number;
+    readonly primaryIndex: number;
+    readonly nextConsensus: H160;
+    readonly witness: Witness;
+    constructor({ version, previousBlockHash, merkleRoot, unixMillis, nonce, index, primaryIndex, nextConsensus, witness, }: {
+        version: number;
+        previousBlockHash: H256;
+        merkleRoot: H256;
+        unixMillis: bigint | number;
+        nonce: number;
+        index: number;
+        primaryIndex: number;
+        nextConsensus: H160;
+        witness: Witness;
+    });
+    get time(): bigint;
+    getSignData(networkId: number): Uint8Array;
+    marshalUnsignedTo(writer: BinaryWriter): void;
+    marshalTo(writer: BinaryWriter): void;
+    static unmarshalFrom(reader: BinaryReader): Header;
+    toBytes(): Uint8Array;
+    toJSON(): {
+        version: number;
+        previousblockhash: string;
+        merkleroot: string;
+        time: string;
+        nonce: number;
+        index: number;
+        primaryindex: number;
+        nextconsensus: string;
+        witness: ReturnType<Witness["toJSON"]>;
+    };
+}
+export declare class Block {
+    readonly header: Header;
+    readonly transactions: Tx[];
+    constructor(header: Header, transactions: Tx[]);
+    marshalTo(writer: BinaryWriter): void;
+    static unmarshalFrom(reader: BinaryReader): Block;
+    toBytes(): Uint8Array;
+    toJSON(): ReturnType<Header["toJSON"]> & {
+        tx: ReturnType<Tx["toJSON"]>[];
+    };
+}
+export declare class TrimmedBlock {
+    readonly header: Header;
+    readonly transactions: H256[];
+    constructor(header: Header, transactions: H256[]);
+    marshalTo(writer: BinaryWriter): void;
+    static unmarshalFrom(reader: BinaryReader): TrimmedBlock;
+    toBytes(): Uint8Array;
+    toJSON(): ReturnType<Header["toJSON"]> & {
+        tx: string[];
+    };
+}

package/dist/core/block.js

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+import { encodeUInt32LE } from "../internal/bytes.js";
+import { H160, H256 } from "./hash.js";
+import { BinaryWriter, serialize } from "./serializing.js";
+import { Tx } from "./tx.js";
+import { Witness } from "./witness.js";
+export class Header {
+    version;
+    previousBlockHash;
+    merkleRoot;
+    unixMillis;
+    nonce;
+    index;
+    primaryIndex;
+    nextConsensus;
+    witness;
+    constructor({ version, previousBlockHash, merkleRoot, unixMillis, nonce, index, primaryIndex, nextConsensus, witness, }) {
+        this.version = version;
+        this.previousBlockHash = previousBlockHash;
+        this.merkleRoot = merkleRoot;
+        this.unixMillis = BigInt(unixMillis);
+        this.nonce = nonce;
+        this.index = index;
+        this.primaryIndex = primaryIndex;
+        this.nextConsensus = nextConsensus;
+        this.witness = witness;
+    }
+    get time() {
+        return this.unixMillis;
+    }
+    getSignData(networkId) {
+        const writer = new BinaryWriter();
+        this.marshalUnsignedTo(writer);
+        const digest = createHash("sha256").update(writer.toBytes()).digest();
+        return new Uint8Array([...encodeUInt32LE(networkId), ...digest]);
+    }
+    marshalUnsignedTo(writer) {
+        writer.writeUInt32LE(this.version);
+        this.previousBlockHash.marshalTo(writer);
+        this.merkleRoot.marshalTo(writer);
+        writer.writeUInt64LE(this.unixMillis);
+        writer.writeUInt32LE(this.nonce);
+        writer.writeUInt32LE(this.index);
+        writer.writeUInt8(this.primaryIndex);
+        this.nextConsensus.marshalTo(writer);
+    }
+    marshalTo(writer) {
+        this.marshalUnsignedTo(writer);
+        this.witness.marshalTo(writer);
+    }
+    static unmarshalFrom(reader) {
+        return new Header({
+            version: reader.readUInt32LE(),
+            previousBlockHash: H256.unmarshalFrom(reader),
+            merkleRoot: H256.unmarshalFrom(reader),
+            unixMillis: reader.readUInt64LE(),
+            nonce: reader.readUInt32LE(),
+            index: reader.readUInt32LE(),
+            primaryIndex: reader.readUInt8(),
+            nextConsensus: H160.unmarshalFrom(reader),
+            witness: Witness.unmarshalFrom(reader),
+        });
+    }
+    toBytes() {
+        return serialize(this);
+    }
+    toJSON() {
+        return {
+            version: this.version,
+            previousblockhash: this.previousBlockHash.toString(),
+            merkleroot: this.merkleRoot.toString(),
+            time: this.unixMillis.toString(),
+            nonce: this.nonce,
+            index: this.index,
+            primaryindex: this.primaryIndex,
+            nextconsensus: this.nextConsensus.toString(),
+            witness: this.witness.toJSON(),
+        };
+    }
+}
+export class Block {
+    header;
+    transactions;
+    constructor(header, transactions) {
+        this.header = header;
+        this.transactions = transactions;
+    }
+    marshalTo(writer) {
+        this.header.marshalTo(writer);
+        writer.writeMultiple(this.transactions);
+    }
+    static unmarshalFrom(reader) {
+        return new Block(Header.unmarshalFrom(reader), reader.readMultiple(Tx));
+    }
+    toBytes() {
+        return serialize(this);
+    }
+    toJSON() {
+        return {
+            ...this.header.toJSON(),
+            tx: this.transactions.map((transaction) => transaction.toJSON()),
+        };
+    }
+}
+export class TrimmedBlock {
+    header;
+    transactions;
+    constructor(header, transactions) {
+        this.header = header;
+        this.transactions = transactions;
+    }
+    marshalTo(writer) {
+        this.header.marshalTo(writer);
+        writer.writeMultiple(this.transactions);
+    }
+    static unmarshalFrom(reader) {
+        return new TrimmedBlock(Header.unmarshalFrom(reader), reader.readMultiple(H256));
+    }
+    toBytes() {
+        return serialize(this);
+    }
+    toJSON() {
+        return {
+            ...this.header.toJSON(),
+            tx: this.transactions.map((transaction) => transaction.toString()),
+        };
+    }
+}

package/dist/core/hash.d.ts

@@ -0,0 +1,20 @@
+import { BytesLike } from "../internal/bytes.js";
+import { BinaryReader, BinaryWriter } from "./serializing.js";
+declare abstract class HashBase {
+    private readonly byteLength;
+    protected readonly data: Uint8Array;
+    protected constructor(byteLength: number, data: Uint8Array);
+    toBytes(): Uint8Array;
+    marshalTo(writer: BinaryWriter): void;
+    toString(): string;
+    equals(other: HashBase | string): boolean;
+}
+export declare class H160 extends HashBase {
+    constructor(value?: BytesLike | string);
+    static unmarshalFrom(reader: BinaryReader): H160;
+}
+export declare class H256 extends HashBase {
+    constructor(value?: BytesLike | string);
+    static unmarshalFrom(reader: BinaryReader): H256;
+}
+export {};

package/dist/core/hash.js

@@ -0,0 +1,51 @@
+import { bytesToHex, equalBytes, hexToBytes, reverseBytes, toUint8Array } from "../internal/bytes.js";
+class HashBase {
+    byteLength;
+    data;
+    constructor(byteLength, data) {
+        this.byteLength = byteLength;
+        this.data = data;
+        if (data.length !== byteLength) {
+            throw new Error(`Hash must be ${byteLength} bytes`);
+        }
+    }
+    toBytes() {
+        return this.data.slice();
+    }
+    marshalTo(writer) {
+        writer.write(this.data);
+    }
+    toString() {
+        return `0x${bytesToHex(reverseBytes(this.data))}`;
+    }
+    equals(other) {
+        const comparable = typeof other === "string" ? new this.constructor(other) : other;
+        return equalBytes(this.data, comparable.data);
+    }
+}
+export class H160 extends HashBase {
+    constructor(value) {
+        const data = typeof value === "string"
+            ? reverseBytes(hexToBytes(value))
+            : value === undefined
+                ? new Uint8Array(20)
+                : toUint8Array(value);
+        super(20, data);
+    }
+    static unmarshalFrom(reader) {
+        return new H160(reader.read(20));
+    }
+}
+export class H256 extends HashBase {
+    constructor(value) {
+        const data = typeof value === "string"
+            ? reverseBytes(hexToBytes(value))
+            : value === undefined
+                ? new Uint8Array(32)
+                : toUint8Array(value);
+        super(32, data);
+    }
+    static unmarshalFrom(reader) {
+        return new H256(reader.read(32));
+    }
+}

package/dist/core/keypair.d.ts

@@ -0,0 +1,24 @@
+import { H160 } from "./hash.js";
+import { BinaryReader, BinaryWriter } from "./serializing.js";
+import { Witness } from "./witness.js";
+export declare class PrivateKey {
+    private readonly hex;
+    constructor(value?: Uint8Array | string | bigint | number);
+    publicKey(): PublicKey;
+    sign(message: Uint8Array): Uint8Array;
+    signWitness(signData: Uint8Array): Witness;
+    toBytes(): Uint8Array;
+}
+export declare class PublicKey {
+    private readonly hex;
+    constructor(value: Uint8Array | string);
+    getScriptHash(): H160;
+    getAddress(addressVersion?: number): string;
+    getSignatureRedeemScript(): Uint8Array;
+    verify(message: Uint8Array, signature: Uint8Array): boolean;
+    toBytes(): Uint8Array;
+    marshalTo(writer: BinaryWriter): void;
+    static unmarshalFrom(reader: BinaryReader): PublicKey;
+    toString(): string;
+    equals(other: PublicKey | string): boolean;
+}

package/dist/core/keypair.js

@@ -0,0 +1,97 @@
+import { wallet } from "@cityofzion/neon-core";
+import { randomBytes } from "node:crypto";
+import { bytesToHex, equalBytes, hexToBytes, toUint8Array } from "../internal/bytes.js";
+import { H160 } from "./hash.js";
+import { ScriptBuilder } from "./script.js";
+import { Witness } from "./witness.js";
+function privateKeyToHex(value) {
+    if (typeof value === "string") {
+        const bytes = hexToBytes(value);
+        if (bytes.length !== 32) {
+            throw new Error("invalid secp256r1 private key");
+        }
+        return bytesToHex(bytes);
+    }
+    if (typeof value === "bigint" || typeof value === "number") {
+        let remaining = BigInt(value);
+        const bytes = new Uint8Array(32);
+        for (let index = 31; index >= 0; index -= 1) {
+            bytes[index] = Number(remaining & 0xffn);
+            remaining >>= 8n;
+        }
+        return bytesToHex(bytes);
+    }
+    if (value instanceof Uint8Array) {
+        if (value.length !== 32) {
+            throw new Error("invalid secp256r1 private key");
+        }
+        return bytesToHex(value);
+    }
+    return bytesToHex(randomBytes(32));
+}
+export class PrivateKey {
+    hex;
+    constructor(value) {
+        this.hex = privateKeyToHex(value);
+    }
+    publicKey() {
+        return new PublicKey(wallet.getPublicKeyFromPrivateKey(this.hex));
+    }
+    sign(message) {
+        return hexToBytes(wallet.sign(bytesToHex(message), this.hex));
+    }
+    signWitness(signData) {
+        const signature = this.sign(signData);
+        const invocation = new ScriptBuilder().emitPush(signature).toBytes();
+        const verification = this.publicKey().getSignatureRedeemScript();
+        return new Witness(invocation, verification);
+    }
+    toBytes() {
+        return hexToBytes(this.hex);
+    }
+}
+export class PublicKey {
+    hex;
+    constructor(value) {
+        const bytes = typeof value === "string" ? hexToBytes(value) : toUint8Array(value);
+        if (![33, 65].includes(bytes.length)) {
+            throw new Error("unsupported public key");
+        }
+        this.hex = bytesToHex(bytes);
+    }
+    getScriptHash() {
+        return new H160(`0x${wallet.getScriptHashFromPublicKey(this.hex)}`);
+    }
+    getAddress(addressVersion = 53) {
+        return wallet.getAddressFromScriptHash(wallet.getScriptHashFromPublicKey(this.hex), addressVersion);
+    }
+    getSignatureRedeemScript() {
+        return hexToBytes(wallet.getVerificationScriptFromPublicKey(this.hex));
+    }
+    verify(message, signature) {
+        return wallet.verify(bytesToHex(message), bytesToHex(signature), this.hex);
+    }
+    toBytes() {
+        return hexToBytes(this.hex);
+    }
+    marshalTo(writer) {
+        writer.write(this.toBytes());
+    }
+    static unmarshalFrom(reader) {
+        const prefix = reader.readUInt8();
+        if (prefix === 0x02 || prefix === 0x03) {
+            return new PublicKey(Uint8Array.of(prefix, ...reader.read(32)));
+        }
+        if (prefix === 0x04) {
+            return new PublicKey(Uint8Array.of(prefix, ...reader.read(64)));
+        }
+        throw new Error(`unexpected PublicKey prefix: ${prefix}`);
+    }
+    toString() {
+        return this.hex;
+    }
+    equals(other) {
+        const comparable = typeof other === "string" ? new PublicKey(other) : other;
+        return equalBytes(this.toBytes(), comparable.toBytes());
+    }
+}

package/dist/core/opcode.d.ts

@@ -0,0 +1,3 @@
+import { sc } from "@cityofzion/neon-core";
+export declare const OpCode: typeof sc.OpCode;
+export type OpCode = sc.OpCode;

package/dist/core/opcode.js

@@ -0,0 +1,2 @@
+import { sc } from "@cityofzion/neon-core";
+export const OpCode = sc.OpCode;

package/dist/core/script.d.ts

@@ -0,0 +1,25 @@
+import { H160 } from "./hash.js";
+import { OpCode } from "./opcode.js";
+export declare enum CallFlags {
+    NONE = 0,
+    ReadStates = 1,
+    WriteStates = 2,
+    AllowCall = 4,
+    AllowNotify = 8,
+    States = 3,
+    ReadOnly = 5,
+    All = 15
+}
+export declare function syscallCode(syscallName: string): number;
+export declare class ScriptBuilder {
+    private readonly script;
+    emit(opcode: OpCode, operand?: Uint8Array): this;
+    emitPush(item: unknown): this;
+    private emitPushInt;
+    private emitPushBytes;
+    private emitPushArray;
+    emitContractCall(contractHash: H160 | string, method: string, callFlags?: CallFlags, args?: unknown[]): this;
+    emitSyscall(syscall: number | string, args?: unknown[]): this;
+    toBytes(): Uint8Array;
+    toHex(): string;
+}