@ottochain/sdk


TypeScript SDK for OttoChain metagraph on Constellation Network.

Features

- Transaction Signing — Sign and batch-sign metagraph transactions
- Key Management — Generate and manage DAG keypairs
- HTTP Client — Interact with metagraph L0/L1 APIs
- Type Definitions — Full TypeScript types for OttoChain domain model
- Input Validation — Runtime validation with Zod schemas
- Custom Errors — Structured error handling with error codes

Installation

``bash


From npm (when published)

npm install @ottochain/sdk

From GitHub (for development)

npm install github:ottobot-ai/ottochain-sdk#main
`

Quick Start

`typescript
import {
generateKeyPair,
createSignedObject,
DataL1Client
} from '@ottochain/sdk';

// Generate a new keypair
const keyPair = generateKeyPair();
console.log('Address:', keyPair.address);

// Create and sign a transaction
const payload = { action: 'RegisterAgent', data: { displayName: 'MyAgent' } };
const signed = await createSignedObject(payload, keyPair.privateKey, { isDataUpdate: true });

// Submit to network
const client = new DataL1Client('http://localhost:9300');
await client.postData(signed);
`

API Documentation

$3

`typescript
import {
generateKeyPair,
keyPairFromPrivateKey,
isValidPrivateKey,
isValidPublicKey,
getAddress
} from '@ottochain/sdk';

// Generate new keypair
const keyPair = generateKeyPair();
// { privateKey: '...', publicKey: '...', address: 'DAG...' }

// Import from existing private key
const imported = keyPairFromPrivateKey(privateKeyHex);

// Validation
if (isValidPrivateKey(key)) {
// Key is valid
}
`

$3

`typescript
import {
createSignedObject,
batchSign,
addSignature,
sign,
signDataUpdate
} from '@ottochain/sdk';

// Sign a single object
const signed = await createSignedObject(data, privateKey);

// Sign for DataUpdate (metagraph L1 submission)
const signedUpdate = await createSignedObject(data, privateKey, { isDataUpdate: true });

// Multi-party signing
const multiSig = await batchSign(data, [key1, key2, key3]);

// Add signature to existing signed object
const withMoreSigs = await addSignature(signed, anotherPrivateKey);
`

$3

`typescript
import { DataL1Client, CurrencyL1Client, HttpClient } from '@ottochain/sdk';

// Data L1 client (for metagraph state)
const dataClient = new DataL1Client('http://localhost:9300');
await dataClient.postData(signedTransaction);
const state = await dataClient.get('/state');

// Currency L1 client (for token transfers)
const currencyClient = new CurrencyL1Client('http://localhost:9200');
const balance = await currencyClient.getBalance(address);
const lastRef = await currencyClient.getLastReference(address);

// Generic HTTP client with custom timeout
const httpClient = new HttpClient('http://localhost:9000', 30000);
`

$3

The SDK uses Zod for runtime validation.

`typescript
import {
validate,
validatePrivateKey,
validateAddress,
safeParse,
KeyPairSchema,
ProposeContractRequestSchema
} from '@ottochain/sdk';

// Validate and throw on error
const validKey = validatePrivateKey(input);
const validAddress = validateAddress(input);

// Validate complex objects
const keyPair = validate(KeyPairSchema, inputData);
const request = validate(ProposeContractRequestSchema, requestData);

// Safe parsing (returns result object)
const result = safeParse(KeyPairSchema, input);
if (result.success) {
console.log(result.data.address);
} else {
console.log(result.error.message);
}
`

Available schemas:
- KeyPairSchema - Private/public key and address
- SignatureProofSchema - Signature proof format
- CurrencyTransactionSchema - Currency transfer transactions
- AgentIdentityRegistrationSchema - Agent registration
- ProposeContractRequestSchema - Contract proposals
- AcceptContractRequestSchema - Contract acceptance
- CompleteContractRequestSchema - Contract completion

Error Handling

The SDK provides custom error classes for structured error handling.

`typescript
import {
OttoChainError,
NetworkError,
ValidationError,
SigningError,
TransactionError,
ErrorCode,
isErrorCode
} from '@ottochain/sdk';

try {
await client.postData(signed);
} catch (error) {
if (error instanceof NetworkError) {
console.log('Network failed:', error.statusCode, error.message);
if (error.responseBody) {
console.log('Response:', error.responseBody);
}
} else if (error instanceof ValidationError) {
console.log('Invalid input:', error.field, error.message);
console.log('Details:', error.details);
} else if (error instanceof SigningError) {
console.log('Signing failed:', error.operation);
} else if (error instanceof TransactionError) {
console.log('Transaction failed:', error.rejectionReason);
}

// Check specific error codes
if (isErrorCode(error, ErrorCode.NETWORK_TIMEOUT)) {
// Implement retry logic
}
}
`

Error codes:
- NETWORK_ERROR - HTTP/connection failures
- NETWORK_TIMEOUT - Request timeout
- VALIDATION_ERROR - Input validation failed
- SIGNING_ERROR - Signature creation failed
- TRANSACTION_REJECTED - Transaction rejected by network
- TRANSACTION_NOT_FOUND - Transaction not found

Examples

See the examples/ directory for complete working examples:

| Example | Description |
|---------|-------------|
| agent-registration.ts | Register an agent identity |
| contract-flow.ts | Full contract lifecycle (propose → accept → complete) |
| batch-transactions.ts | Multi-party signing and batch operations |
| wallet-management.ts | Key generation, import, export, validation |
| query-state.ts | Query network state and handle errors |

Run an example:
`bash
npx ts-node examples/wallet-management.ts
`

Module Imports

`typescript
// Core SDK (signing, HTTP client, validation, errors)
import {
generateKeyPair,
batchSign,
HttpClient,
validate,
ValidationError
} from '@ottochain/sdk';

// Core types (fiber, state machine)
import { Fiber, StateMachineDefinition } from '@ottochain/sdk/core';

// Agent Identity application
import { AgentState, AttestationType, AgentIdentity } from '@ottochain/sdk/apps/identity';

// Contracts application
import { ContractState, Contract } from '@ottochain/sdk/apps/contracts';
`

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run tests with coverage

npm run test:coverage

Lint

npm run lint

Generate documentation

npm run docs

Generate protobuf types

npm run generate
`

Project Structure

`
ottochain-sdk/
├── proto/ # Protobuf definitions (source of truth)
│ └── ottochain/
│ ├── v1/ # Core metagraph types
│ │ ├── common.proto
│ │ ├── fiber.proto
│ │ ├── messages.proto
│ │ └── records.proto
│ └── apps/ # Application-specific types
│ ├── identity/v1/
│ │ ├── agent.proto
│ │ └── attestation.proto
│ └── contracts/v1/
│ └── contract.proto
├── src/
│ ├── metakit/ # Signing, hashing, HTTP client
│ ├── ottochain/ # Core domain types
│ ├── apps/ # Application modules
│ │ ├── identity/ # Agent Identity types
│ │ └── contracts/ # Contract types
│ ├── generated/ # Protobuf-generated code
│ ├── errors.ts # Custom error classes
│ ├── validation.ts # Zod validation schemas
│ └── index.ts # Main exports
├── examples/ # Working code examples
├── tests/ # Test suites
└── dist/ # Compiled output
``

License

Apache-2.0