@ottochain/sdk 0.2.0

package/dist/metakit/sign.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Signing Functions
+ *
+ * ECDSA signing using secp256k1 curve via dag4js.
+ * Implements the Constellation signature protocol.
+ */
+import { SignatureProof } from './types.js';
+/**
+ * Sign data using the regular Constellation protocol (non-DataUpdate)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. SHA-256 hash the canonical JSON string
+ * 3. Sign using dag4.keyStore.sign
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof with public key ID and signature
+ *
+ * @example
+ * ```typescript
+ * const proof = await sign({ action: 'test' }, privateKeyHex);
+ * console.log(proof.id);        // public key (128 chars)
+ * console.log(proof.signature); // DER signature
+ * ```
+ */
+export declare function sign<T>(data: T, privateKey: string): Promise<SignatureProof>;
+/**
+ * Sign data as a DataUpdate (with Constellation prefix)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. Base64 encode the canonical JSON
+ * 3. Sign using dag4.keyStore.dataSign (adds Constellation prefix internally)
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof
+ */
+export declare function signDataUpdate<T>(data: T, privateKey: string): Promise<SignatureProof>;
+/**
+ * Sign a pre-computed SHA-256 hash
+ *
+ * This is the low-level signing function. Use `sign()` or `signDataUpdate()`
+ * for most use cases.
+ *
+ * Protocol (performed by dag4.keyStore.sign):
+ * 1. Treat hashHex as UTF-8 bytes (64 ASCII characters = 64 bytes)
+ * 2. SHA-512 hash those bytes (produces 64 bytes)
+ * 3. Truncate to first 32 bytes (for secp256k1 curve order)
+ * 4. Sign with ECDSA secp256k1
+ * 5. Return DER-encoded signature
+ *
+ * @param hashHex - SHA-256 hash as 64-character hex string
+ * @param privateKey - Private key in hex format (64 characters)
+ * @returns DER-encoded signature in hex format
+ *
+ * @example
+ * ```typescript
+ * // Compute your own hash
+ * const hashHex = sha256(myData);
+ * const signature = await signHash(hashHex, privateKey);
+ * ```
+ */
+export declare function signHash(hashHex: string, privateKey: string): Promise<string>;

package/dist/metakit/sign.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Signing Functions
+ *
+ * ECDSA signing using secp256k1 curve via dag4js.
+ * Implements the Constellation signature protocol.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signHash = exports.signDataUpdate = exports.sign = void 0;
+const dag4_1 = require("@stardust-collective/dag4");
+const js_sha256_1 = require("js-sha256");
+const canonicalize_js_1 = require("./canonicalize.js");
+/**
+ * Sign data using the regular Constellation protocol (non-DataUpdate)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. SHA-256 hash the canonical JSON string
+ * 3. Sign using dag4.keyStore.sign
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof with public key ID and signature
+ *
+ * @example
+ * ```typescript
+ * const proof = await sign({ action: 'test' }, privateKeyHex);
+ * console.log(proof.id);        // public key (128 chars)
+ * console.log(proof.signature); // DER signature
+ * ```
+ */
+async function sign(data, privateKey) {
+    // Step 1: Canonicalize JSON (RFC 8785)
+    const canonicalJson = (0, canonicalize_js_1.canonicalize)(data);
+    // Step 2-3: UTF-8 encode and SHA-256 hash (sha256 handles UTF-8 encoding internally)
+    // Returns 64-character hex string
+    const hashHex = (0, js_sha256_1.sha256)(canonicalJson);
+    // Step 4-6: dag4.keyStore.sign internally:
+    //   4. Treats hashHex as UTF-8 bytes
+    //   5. SHA-512 hashes those bytes, truncates to 32 bytes
+    //   6. Signs with ECDSA secp256k1
+    const signature = await dag4_1.dag4.keyStore.sign(privateKey, hashHex);
+    // Get public key ID (without 04 prefix)
+    const publicKey = dag4_1.dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    const id = normalizePublicKeyId(publicKey);
+    return { id, signature };
+}
+exports.sign = sign;
+/**
+ * Sign data as a DataUpdate (with Constellation prefix)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. Base64 encode the canonical JSON
+ * 3. Sign using dag4.keyStore.dataSign (adds Constellation prefix internally)
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof
+ */
+async function signDataUpdate(data, privateKey) {
+    // Step 1: Canonicalize JSON
+    const canonicalJson = (0, canonicalize_js_1.canonicalize)(data);
+    // Step 2: Base64 encode for dataSign
+    const base64String = Buffer.from(canonicalJson, 'utf-8').toString('base64');
+    // Step 3: Sign using dag4's dataSign (handles Constellation prefix internally)
+    const signature = await dag4_1.dag4.keyStore.dataSign(privateKey, base64String);
+    // Get public key ID
+    const publicKey = dag4_1.dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    const id = normalizePublicKeyId(publicKey);
+    return { id, signature };
+}
+exports.signDataUpdate = signDataUpdate;
+/**
+ * Sign a pre-computed SHA-256 hash
+ *
+ * This is the low-level signing function. Use `sign()` or `signDataUpdate()`
+ * for most use cases.
+ *
+ * Protocol (performed by dag4.keyStore.sign):
+ * 1. Treat hashHex as UTF-8 bytes (64 ASCII characters = 64 bytes)
+ * 2. SHA-512 hash those bytes (produces 64 bytes)
+ * 3. Truncate to first 32 bytes (for secp256k1 curve order)
+ * 4. Sign with ECDSA secp256k1
+ * 5. Return DER-encoded signature
+ *
+ * @param hashHex - SHA-256 hash as 64-character hex string
+ * @param privateKey - Private key in hex format (64 characters)
+ * @returns DER-encoded signature in hex format
+ *
+ * @example
+ * ```typescript
+ * // Compute your own hash
+ * const hashHex = sha256(myData);
+ * const signature = await signHash(hashHex, privateKey);
+ * ```
+ */
+async function signHash(hashHex, privateKey) {
+    // dag4.keyStore.sign performs:
+    // 1. SHA-512 of hashHex (treating 64 hex chars as UTF-8 bytes)
+    // 2. Truncation to 32 bytes (handled internally by crypto library)
+    // 3. ECDSA signing with secp256k1
+    return dag4_1.dag4.keyStore.sign(privateKey, hashHex);
+}
+exports.signHash = signHash;
+/**
+ * Normalize public key to ID format (without 04 prefix, 128 chars)
+ */
+function normalizePublicKeyId(publicKey) {
+    // If 130 chars (with 04 prefix), remove prefix
+    if (publicKey.length === 130 && publicKey.startsWith('04')) {
+        return publicKey.substring(2);
+    }
+    // If 128 chars (without prefix), return as-is
+    if (publicKey.length === 128) {
+        return publicKey;
+    }
+    // Otherwise return as-is and let validation catch issues
+    return publicKey;
+}

package/dist/metakit/signed-object.d.ts

@@ -0,0 +1,66 @@
+/**
+ * High-Level Signed Object API
+ *
+ * Convenience functions for creating and managing signed objects.
+ */
+import { Signed, SigningOptions } from './types.js';
+/**
+ * Create a signed object with a single signature
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options
+ * @returns Signed object ready for submission
+ *
+ * @example
+ * ```typescript
+ * // Sign a regular data object
+ * const signed = await createSignedObject(myData, privateKey);
+ *
+ * // Sign as DataUpdate for L1 submission
+ * const signedUpdate = await createSignedObject(myData, privateKey, { isDataUpdate: true });
+ * ```
+ */
+export declare function createSignedObject<T>(value: T, privateKey: string, options?: SigningOptions): Promise<Signed<T>>;
+/**
+ * Add an additional signature to an existing signed object
+ *
+ * This allows building multi-signature objects where multiple parties
+ * need to sign the same data.
+ *
+ * @param signed - Existing signed object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options (must match original signing)
+ * @returns New signed object with additional proof
+ *
+ * @example
+ * ```typescript
+ * // First party signs
+ * let signed = await createSignedObject(data, party1Key);
+ *
+ * // Second party adds signature
+ * signed = await addSignature(signed, party2Key);
+ *
+ * // Now has 2 proofs
+ * console.log(signed.proofs.length); // 2
+ * ```
+ */
+export declare function addSignature<T>(signed: Signed<T>, privateKey: string, options?: SigningOptions): Promise<Signed<T>>;
+/**
+ * Create a signed object with multiple signatures at once
+ *
+ * Useful when you have access to multiple private keys and want
+ * to create a multi-sig object in one operation.
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKeys - Array of private keys in hex format
+ * @param options - Signing options
+ * @returns Signed object with multiple proofs
+ *
+ * @example
+ * ```typescript
+ * const signed = await batchSign(data, [key1, key2, key3]);
+ * console.log(signed.proofs.length); // 3
+ * ```
+ */
+export declare function batchSign<T>(value: T, privateKeys: string[], options?: SigningOptions): Promise<Signed<T>>;

package/dist/metakit/signed-object.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * High-Level Signed Object API
+ *
+ * Convenience functions for creating and managing signed objects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchSign = exports.addSignature = exports.createSignedObject = void 0;
+const sign_js_1 = require("./sign.js");
+/**
+ * Create a signed object with a single signature
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options
+ * @returns Signed object ready for submission
+ *
+ * @example
+ * ```typescript
+ * // Sign a regular data object
+ * const signed = await createSignedObject(myData, privateKey);
+ *
+ * // Sign as DataUpdate for L1 submission
+ * const signedUpdate = await createSignedObject(myData, privateKey, { isDataUpdate: true });
+ * ```
+ */
+async function createSignedObject(value, privateKey, options = {}) {
+    const { isDataUpdate = false } = options;
+    const proof = isDataUpdate
+        ? await (0, sign_js_1.signDataUpdate)(value, privateKey)
+        : await (0, sign_js_1.sign)(value, privateKey);
+    return {
+        value,
+        proofs: [proof],
+    };
+}
+exports.createSignedObject = createSignedObject;
+/**
+ * Add an additional signature to an existing signed object
+ *
+ * This allows building multi-signature objects where multiple parties
+ * need to sign the same data.
+ *
+ * @param signed - Existing signed object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options (must match original signing)
+ * @returns New signed object with additional proof
+ *
+ * @example
+ * ```typescript
+ * // First party signs
+ * let signed = await createSignedObject(data, party1Key);
+ *
+ * // Second party adds signature
+ * signed = await addSignature(signed, party2Key);
+ *
+ * // Now has 2 proofs
+ * console.log(signed.proofs.length); // 2
+ * ```
+ */
+async function addSignature(signed, privateKey, options = {}) {
+    const { isDataUpdate = false } = options;
+    const newProof = isDataUpdate
+        ? await (0, sign_js_1.signDataUpdate)(signed.value, privateKey)
+        : await (0, sign_js_1.sign)(signed.value, privateKey);
+    return {
+        value: signed.value,
+        proofs: [...signed.proofs, newProof],
+    };
+}
+exports.addSignature = addSignature;
+/**
+ * Create a signed object with multiple signatures at once
+ *
+ * Useful when you have access to multiple private keys and want
+ * to create a multi-sig object in one operation.
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKeys - Array of private keys in hex format
+ * @param options - Signing options
+ * @returns Signed object with multiple proofs
+ *
+ * @example
+ * ```typescript
+ * const signed = await batchSign(data, [key1, key2, key3]);
+ * console.log(signed.proofs.length); // 3
+ * ```
+ */
+async function batchSign(value, privateKeys, options = {}) {
+    if (privateKeys.length === 0) {
+        throw new Error('At least one private key is required');
+    }
+    const { isDataUpdate = false } = options;
+    const proofs = await Promise.all(privateKeys.map((key) => (isDataUpdate ? (0, sign_js_1.signDataUpdate)(value, key) : (0, sign_js_1.sign)(value, key))));
+    return {
+        value,
+        proofs,
+    };
+}
+exports.batchSign = batchSign;

package/dist/metakit/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Core type definitions for the Ottochain SDK
+ */
+/**
+ * A signature proof containing the signer's public key ID and signature
+ */
+export interface SignatureProof {
+    /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
+    id: string;
+    /** DER-encoded ECDSA signature in hex format */
+    signature: string;
+}
+/**
+ * A signed object wrapping a value with one or more signature proofs
+ */
+export interface Signed<T> {
+    /** The signed value */
+    value: T;
+    /** Array of signature proofs */
+    proofs: SignatureProof[];
+}
+/**
+ * A key pair for signing operations
+ */
+export interface KeyPair {
+    /** Private key in hex format */
+    privateKey: string;
+    /** Public key in hex format (uncompressed, with 04 prefix) */
+    publicKey: string;
+    /** DAG address derived from the public key */
+    address: string;
+}
+/**
+ * A hash result containing both hex string and raw bytes
+ */
+export interface Hash {
+    /** SHA-256 hash as 64-character hex string */
+    value: string;
+    /** Raw 32-byte hash as Uint8Array */
+    bytes: Uint8Array;
+}
+/**
+ * Result of signature verification
+ */
+export interface VerificationResult {
+    /** Whether all signatures are valid */
+    isValid: boolean;
+    /** Proofs that passed verification */
+    validProofs: SignatureProof[];
+    /** Proofs that failed verification */
+    invalidProofs: SignatureProof[];
+}
+/**
+ * Options for signing operations
+ */
+export interface SigningOptions {
+    /** Whether to sign as a DataUpdate (with Constellation prefix) */
+    isDataUpdate?: boolean;
+}
+/**
+ * Supported signature algorithm
+ */
+export declare const ALGORITHM: "SECP256K1_RFC8785_V1";
+/**
+ * Constellation prefix for DataUpdate signing
+ */
+export declare const CONSTELLATION_PREFIX = "\u0019Constellation Signed Data:\n";

package/dist/metakit/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Core type definitions for the Ottochain SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSTELLATION_PREFIX = exports.ALGORITHM = void 0;
+/**
+ * Supported signature algorithm
+ */
+exports.ALGORITHM = 'SECP256K1_RFC8785_V1';
+/**
+ * Constellation prefix for DataUpdate signing
+ */
+exports.CONSTELLATION_PREFIX = '\x19Constellation Signed Data:\n';

package/dist/metakit/verify.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Signature Verification
+ *
+ * Verify ECDSA signatures using secp256k1 curve via dag4js.
+ */
+import { Signed, SignatureProof, VerificationResult } from './types.js';
+/**
+ * Verify a signed object
+ *
+ * @param signed - Signed object with value and proofs
+ * @param isDataUpdate - Whether the value was signed as a DataUpdate
+ * @returns VerificationResult with valid/invalid proof lists
+ *
+ * @example
+ * ```typescript
+ * const result = await verify(signedObject);
+ * if (result.isValid) {
+ *   console.log('All signatures valid');
+ * }
+ * ```
+ */
+export declare function verify<T>(signed: Signed<T>, isDataUpdate?: boolean): Promise<VerificationResult>;
+/**
+ * Verify a signature against a SHA-256 hash
+ *
+ * Protocol:
+ * 1. Treat hash hex as UTF-8 bytes (NOT hex decode)
+ * 2. SHA-512 hash
+ * 3. Truncate to 32 bytes (handled internally by dag4)
+ * 4. Verify ECDSA signature
+ *
+ * @param hashHex - SHA-256 hash as 64-character hex string
+ * @param signature - DER-encoded signature in hex format
+ * @param publicKeyId - Public key in hex (with or without 04 prefix)
+ * @returns true if signature is valid
+ */
+export declare function verifyHash(hashHex: string, signature: string, publicKeyId: string): Promise<boolean>;
+/**
+ * Verify a single signature proof against data
+ *
+ * @param data - The original data that was signed
+ * @param proof - The signature proof to verify
+ * @param isDataUpdate - Whether data was signed as DataUpdate
+ * @returns true if signature is valid
+ */
+export declare function verifySignature<T>(data: T, proof: SignatureProof, isDataUpdate?: boolean): Promise<boolean>;
+/**
+ * Normalize a DER-encoded signature to use low-S value.
+ *
+ * BIP 62/146 requires S values to be in the lower half of the curve order.
+ * Some signing implementations produce high-S signatures which are mathematically
+ * valid but rejected by strict verifiers. This normalizes high-S to low-S by
+ * computing S' = N - S where N is the curve order.
+ */
+export declare function normalizeSignatureToLowS(signatureHex: string): string;