@ottochain/sdk 0.2.0

package/dist/esm/validation.js

@@ -0,0 +1,301 @@
+/**
+ * Input Validation with Zod Schemas
+ *
+ * Provides runtime validation for SDK types using Zod.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import { ValidationError } from './errors.js';
+// ============================================================================
+// Primitive Schemas
+// ============================================================================
+/**
+ * Schema for a hex string of specific length
+ */
+const hexString = (length) => {
+    let schema = z.string().regex(/^[0-9a-fA-F]+$/, 'Must be a valid hex string');
+    if (length !== undefined) {
+        schema = schema.length(length, `Must be exactly ${length} characters`);
+    }
+    return schema;
+};
+/**
+ * Schema for a DAG address
+ */
+export const DagAddressSchema = z
+    .string()
+    .regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
+// ============================================================================
+// Core Type Schemas
+// ============================================================================
+/**
+ * Schema for a private key (64-character hex string)
+ */
+export const PrivateKeySchema = hexString(64).describe('Private key in hex format (64 characters)');
+/**
+ * Schema for a public key (128 or 130 character hex string)
+ */
+export const PublicKeySchema = z
+    .string()
+    .regex(/^(04)?[0-9a-fA-F]{128}$/, 'Must be a valid public key (128 or 130 hex chars)')
+    .describe('Public key in hex format (with optional 04 prefix)');
+/**
+ * Schema for a KeyPair
+ */
+export const KeyPairSchema = z.object({
+    /** Private key in hex format */
+    privateKey: PrivateKeySchema,
+    /** Public key in hex format (uncompressed, with 04 prefix) */
+    publicKey: PublicKeySchema,
+    /** DAG address derived from the public key */
+    address: DagAddressSchema,
+});
+/**
+ * Schema for a SignatureProof
+ */
+export const SignatureProofSchema = z.object({
+    /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
+    id: hexString(128),
+    /** DER-encoded ECDSA signature in hex format */
+    signature: hexString(),
+});
+/**
+ * Schema for a Signed object (generic)
+ */
+export const SignedSchema = (valueSchema) => z.object({
+    value: valueSchema,
+    proofs: z.array(SignatureProofSchema).min(1, 'At least one proof is required'),
+});
+// ============================================================================
+// Transaction Schemas
+// ============================================================================
+/**
+ * Schema for TransactionReference
+ */
+export const TransactionReferenceSchema = z.object({
+    ordinal: z.number().int().min(0),
+    hash: z.string().min(1),
+});
+/**
+ * Schema for CurrencyTransactionValue
+ */
+export const CurrencyTransactionValueSchema = z.object({
+    source: DagAddressSchema,
+    destination: DagAddressSchema,
+    amount: z.number().int().positive('Amount must be positive'),
+    fee: z.number().int().min(0).default(0),
+});
+/**
+ * Schema for CurrencyTransaction
+ */
+export const CurrencyTransactionSchema = z.object({
+    value: CurrencyTransactionValueSchema,
+    parent: TransactionReferenceSchema,
+});
+/**
+ * Schema for TransferParams
+ */
+export const TransferParamsSchema = z.object({
+    from: DagAddressSchema,
+    to: DagAddressSchema,
+    amount: z.number().positive('Amount must be positive'),
+    fee: z.number().min(0).optional().default(0),
+});
+// ============================================================================
+// Identity Schemas
+// ============================================================================
+/**
+ * Schema for AgentIdentity registration
+ */
+export const AgentIdentityRegistrationSchema = z.object({
+    /** Public key in hex format */
+    publicKey: PublicKeySchema,
+    /** Display name for the agent */
+    displayName: z.string().min(1).max(64),
+    /** Initial reputation (default: 10) */
+    reputation: z.number().int().min(0).optional().default(10),
+});
+/**
+ * Schema for PlatformLink
+ */
+export const PlatformLinkSchema = z.object({
+    platform: z.enum(['DISCORD', 'TELEGRAM', 'TWITTER', 'GITHUB', 'CUSTOM']),
+    platformUserId: z.string().min(1),
+    platformUsername: z.string().min(1),
+    verified: z.boolean().optional().default(false),
+});
+// ============================================================================
+// Contract Schemas
+// ============================================================================
+/**
+ * Schema for contract terms (flexible structure)
+ */
+export const ContractTermsSchema = z.record(z.unknown());
+/**
+ * Schema for ProposeContractRequest
+ */
+export const ProposeContractRequestSchema = z.object({
+    /** Proposer's DAG address */
+    proposer: DagAddressSchema,
+    /** Counterparty's DAG address */
+    counterparty: DagAddressSchema,
+    /** Contract terms */
+    terms: ContractTermsSchema,
+    /** Human-readable description */
+    description: z.string().min(1).max(1000),
+});
+/**
+ * Schema for AcceptContractRequest
+ */
+export const AcceptContractRequestSchema = z.object({
+    /** Contract ID to accept */
+    contractId: z.string().min(1),
+    /** Acceptor's DAG address */
+    acceptor: DagAddressSchema,
+});
+/**
+ * Schema for CompleteContractRequest
+ */
+export const CompleteContractRequestSchema = z.object({
+    /** Contract ID to complete */
+    contractId: z.string().min(1),
+    /** Completer's DAG address */
+    completer: DagAddressSchema,
+    /** Proof of completion */
+    proof: z.string().min(1),
+});
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate data against a Zod schema
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @param fieldName - Optional field name for error context
+ * @returns Validated and typed data
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = validate(KeyPairSchema, inputData, 'keyPair');
+ * // keyPair is now typed as ValidatedKeyPair
+ * ```
+ */
+export function validate(schema, data, fieldName) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues;
+        const firstIssue = issues[0];
+        // Build a helpful error message
+        const path = firstIssue.path.length > 0 ? firstIssue.path.join('.') : fieldName || 'input';
+        const message = `Validation failed for '${path}': ${firstIssue.message}`;
+        throw new ValidationError(message, {
+            field: path,
+            value: data,
+            details: {
+                issues: issues.map((issue) => ({
+                    path: issue.path.join('.'),
+                    message: issue.message,
+                    code: issue.code,
+                })),
+            },
+        });
+    }
+    return result.data;
+}
+/**
+ * Validate a private key
+ *
+ * @param privateKey - Private key to validate
+ * @returns Validated private key
+ * @throws {ValidationError} If validation fails
+ */
+export function validatePrivateKey(privateKey) {
+    return validate(PrivateKeySchema, privateKey, 'privateKey');
+}
+/**
+ * Validate a public key
+ *
+ * @param publicKey - Public key to validate
+ * @returns Validated public key
+ * @throws {ValidationError} If validation fails
+ */
+export function validatePublicKey(publicKey) {
+    return validate(PublicKeySchema, publicKey, 'publicKey');
+}
+/**
+ * Validate a DAG address
+ *
+ * @param address - Address to validate
+ * @returns Validated address
+ * @throws {ValidationError} If validation fails
+ */
+export function validateAddress(address) {
+    return validate(DagAddressSchema, address, 'address');
+}
+/**
+ * Validate a KeyPair
+ *
+ * @param keyPair - KeyPair to validate
+ * @returns Validated KeyPair
+ * @throws {ValidationError} If validation fails
+ */
+export function validateKeyPair(keyPair) {
+    return validate(KeyPairSchema, keyPair, 'keyPair');
+}
+/**
+ * Safe validation that returns a result object instead of throwing
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Object with success status and data or error
+ *
+ * @example
+ * ```typescript
+ * const result = safeParse(KeyPairSchema, inputData);
+ * if (result.success) {
+ *   console.log(result.data.address);
+ * } else {
+ *   console.log(result.error.message);
+ * }
+ * ```
+ */
+export function safeParse(schema, data) {
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const issues = result.error.issues;
+    const firstIssue = issues[0];
+    const path = firstIssue.path.length > 0 ? firstIssue.path.join('.') : 'input';
+    const message = `Validation failed for '${path}': ${firstIssue.message}`;
+    return {
+        success: false,
+        error: new ValidationError(message, {
+            field: path,
+            value: data,
+            details: {
+                issues: issues.map((issue) => ({
+                    path: issue.path.join('.'),
+                    message: issue.message,
+                    code: issue.code,
+                })),
+            },
+        }),
+    };
+}
+/**
+ * Assert that a condition is true, throwing ValidationError if not
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if condition is false
+ * @param field - Optional field name for context
+ * @throws {ValidationError} If condition is false
+ */
+export function assert(condition, message, field) {
+    if (!condition) {
+        throw new ValidationError(message, { field });
+    }
+}

package/dist/generated/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated Protobuf Types
+ *
+ * Auto-generated from proto/ definitions.
+ * DO NOT EDIT - regenerate with `npm run generate`
+ *
+ * @packageDocumentation
+ */
+export * from './ottochain/v1/common_pb.js';
+export * from './ottochain/v1/fiber_pb.js';
+export * from './ottochain/v1/messages_pb.js';
+export * from './ottochain/v1/records_pb.js';
+export * from './ottochain/apps/identity/v1/agent_pb.js';
+export * from './ottochain/apps/identity/v1/attestation_pb.js';
+export * from './ottochain/apps/contracts/v1/contract_pb.js';

package/dist/generated/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Generated Protobuf Types
+ *
+ * Auto-generated from proto/ definitions.
+ * DO NOT EDIT - regenerate with `npm run generate`
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Core types
+__exportStar(require("./ottochain/v1/common_pb.js"), exports);
+__exportStar(require("./ottochain/v1/fiber_pb.js"), exports);
+__exportStar(require("./ottochain/v1/messages_pb.js"), exports);
+__exportStar(require("./ottochain/v1/records_pb.js"), exports);
+// App: Identity
+__exportStar(require("./ottochain/apps/identity/v1/agent_pb.js"), exports);
+__exportStar(require("./ottochain/apps/identity/v1/attestation_pb.js"), exports);
+// App: Contracts
+__exportStar(require("./ottochain/apps/contracts/v1/contract_pb.js"), exports);

package/dist/generated/ottochain/apps/contracts/v1/contract_pb.d.ts

@@ -0,0 +1,274 @@
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import type { Address } from "../../../v1/common_pb.js";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { JsonObject, Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file ottochain/apps/contracts/v1/contract.proto.
+ */
+export declare const file_ottochain_apps_contracts_v1_contract: GenFile;
+/**
+ * Contract between two agents
+ *
+ * @generated from message ottochain.apps.contracts.v1.Contract
+ */
+export type Contract = Message<"ottochain.apps.contracts.v1.Contract"> & {
+    /**
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * Human-readable ID
+     *
+     * @generated from field: string contract_id = 2;
+     */
+    contractId: string;
+    /**
+     * @generated from field: ottochain.v1.Address proposer = 3;
+     */
+    proposer?: Address;
+    /**
+     * @generated from field: ottochain.v1.Address counterparty = 4;
+     */
+    counterparty?: Address;
+    /**
+     * @generated from field: ottochain.apps.contracts.v1.ContractState state = 5;
+     */
+    state: ContractState;
+    /**
+     * Flexible terms structure
+     *
+     * @generated from field: google.protobuf.Struct terms = 6;
+     */
+    terms?: JsonObject;
+    /**
+     * @generated from field: google.protobuf.Timestamp proposed_at = 7;
+     */
+    proposedAt?: Timestamp;
+    /**
+     * @generated from field: google.protobuf.Timestamp accepted_at = 8;
+     */
+    acceptedAt?: Timestamp;
+    /**
+     * @generated from field: google.protobuf.Timestamp completed_at = 9;
+     */
+    completedAt?: Timestamp;
+    /**
+     * Evidence of completion
+     *
+     * @generated from field: string completion_proof = 10;
+     */
+    completionProof: string;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.Contract.
+ * Use `create(ContractSchema)` to create a new message.
+ */
+export declare const ContractSchema: GenMessage<Contract>;
+/**
+ * Propose a new contract
+ *
+ * @generated from message ottochain.apps.contracts.v1.ProposeContractRequest
+ */
+export type ProposeContractRequest = Message<"ottochain.apps.contracts.v1.ProposeContractRequest"> & {
+    /**
+     * @generated from field: ottochain.v1.Address proposer = 1;
+     */
+    proposer?: Address;
+    /**
+     * @generated from field: ottochain.v1.Address counterparty = 2;
+     */
+    counterparty?: Address;
+    /**
+     * @generated from field: google.protobuf.Struct terms = 3;
+     */
+    terms?: JsonObject;
+    /**
+     * @generated from field: string description = 4;
+     */
+    description: string;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.ProposeContractRequest.
+ * Use `create(ProposeContractRequestSchema)` to create a new message.
+ */
+export declare const ProposeContractRequestSchema: GenMessage<ProposeContractRequest>;
+/**
+ * Accept a proposed contract
+ *
+ * @generated from message ottochain.apps.contracts.v1.AcceptContractRequest
+ */
+export type AcceptContractRequest = Message<"ottochain.apps.contracts.v1.AcceptContractRequest"> & {
+    /**
+     * @generated from field: string contract_id = 1;
+     */
+    contractId: string;
+    /**
+     * @generated from field: ottochain.v1.Address acceptor = 2;
+     */
+    acceptor?: Address;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.AcceptContractRequest.
+ * Use `create(AcceptContractRequestSchema)` to create a new message.
+ */
+export declare const AcceptContractRequestSchema: GenMessage<AcceptContractRequest>;
+/**
+ * Complete a contract with proof
+ *
+ * @generated from message ottochain.apps.contracts.v1.CompleteContractRequest
+ */
+export type CompleteContractRequest = Message<"ottochain.apps.contracts.v1.CompleteContractRequest"> & {
+    /**
+     * @generated from field: string contract_id = 1;
+     */
+    contractId: string;
+    /**
+     * @generated from field: ottochain.v1.Address completer = 2;
+     */
+    completer?: Address;
+    /**
+     * @generated from field: string proof = 3;
+     */
+    proof: string;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.CompleteContractRequest.
+ * Use `create(CompleteContractRequestSchema)` to create a new message.
+ */
+export declare const CompleteContractRequestSchema: GenMessage<CompleteContractRequest>;
+/**
+ * Reject a proposed contract
+ *
+ * @generated from message ottochain.apps.contracts.v1.RejectContractRequest
+ */
+export type RejectContractRequest = Message<"ottochain.apps.contracts.v1.RejectContractRequest"> & {
+    /**
+     * @generated from field: string contract_id = 1;
+     */
+    contractId: string;
+    /**
+     * @generated from field: ottochain.v1.Address rejector = 2;
+     */
+    rejector?: Address;
+    /**
+     * @generated from field: string reason = 3;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.RejectContractRequest.
+ * Use `create(RejectContractRequestSchema)` to create a new message.
+ */
+export declare const RejectContractRequestSchema: GenMessage<RejectContractRequest>;
+/**
+ * Dispute a contract
+ *
+ * @generated from message ottochain.apps.contracts.v1.DisputeContractRequest
+ */
+export type DisputeContractRequest = Message<"ottochain.apps.contracts.v1.DisputeContractRequest"> & {
+    /**
+     * @generated from field: string contract_id = 1;
+     */
+    contractId: string;
+    /**
+     * @generated from field: ottochain.v1.Address disputant = 2;
+     */
+    disputant?: Address;
+    /**
+     * @generated from field: string evidence = 3;
+     */
+    evidence: string;
+    /**
+     * @generated from field: string reason = 4;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.DisputeContractRequest.
+ * Use `create(DisputeContractRequestSchema)` to create a new message.
+ */
+export declare const DisputeContractRequestSchema: GenMessage<DisputeContractRequest>;
+/**
+ * Contract state machine definition
+ *
+ * Valid transitions:
+ *   PROPOSED -> ACTIVE (accept)
+ *   PROPOSED -> REJECTED (reject)
+ *   PROPOSED -> CANCELLED (cancel)
+ *   ACTIVE -> COMPLETED (complete)
+ *   ACTIVE -> DISPUTED (dispute)
+ *   DISPUTED -> COMPLETED (resolve_for_completer)
+ *   DISPUTED -> REJECTED (resolve_for_disputant)
+ *
+ * @generated from message ottochain.apps.contracts.v1.ContractDefinition
+ */
+export type ContractDefinition = Message<"ottochain.apps.contracts.v1.ContractDefinition"> & {
+    /**
+     * Both parties must sign completion
+     *
+     * @generated from field: bool require_both_signatures = 1;
+     */
+    requireBothSignatures: boolean;
+    /**
+     * How long after completion disputes allowed
+     *
+     * @generated from field: int32 dispute_window_epochs = 2;
+     */
+    disputeWindowEpochs: number;
+};
+/**
+ * Describes the message ottochain.apps.contracts.v1.ContractDefinition.
+ * Use `create(ContractDefinitionSchema)` to create a new message.
+ */
+export declare const ContractDefinitionSchema: GenMessage<ContractDefinition>;
+/**
+ * Contract lifecycle states
+ *
+ * @generated from enum ottochain.apps.contracts.v1.ContractState
+ */
+export declare enum ContractState {
+    /**
+     * @generated from enum value: CONTRACT_STATE_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * Awaiting counterparty acceptance
+     *
+     * @generated from enum value: CONTRACT_STATE_PROPOSED = 1;
+     */
+    PROPOSED = 1,
+    /**
+     * Both parties agreed, in progress
+     *
+     * @generated from enum value: CONTRACT_STATE_ACTIVE = 2;
+     */
+    ACTIVE = 2,
+    /**
+     * Successfully fulfilled (terminal)
+     *
+     * @generated from enum value: CONTRACT_STATE_COMPLETED = 3;
+     */
+    COMPLETED = 3,
+    /**
+     * Counterparty declined (terminal)
+     *
+     * @generated from enum value: CONTRACT_STATE_REJECTED = 4;
+     */
+    REJECTED = 4,
+    /**
+     * Under dispute resolution
+     *
+     * @generated from enum value: CONTRACT_STATE_DISPUTED = 5;
+     */
+    DISPUTED = 5,
+    /**
+     * Cancelled by proposer before acceptance (terminal)
+     *
+     * @generated from enum value: CONTRACT_STATE_CANCELLED = 6;
+     */
+    CANCELLED = 6
+}
+/**
+ * Describes the enum ottochain.apps.contracts.v1.ContractState.
+ */
+export declare const ContractStateSchema: GenEnum<ContractState>;