@otskit/core

OpenTimestamps core library — TypeScript, zero-dependency, fail-closed.

The next generation of @alexalves87/opentimestamps, rewritten from the ground up with TypeScript 6 strict mode, zero external dependencies, and a fail-closed security posture.

What is OpenTimestamps?

OpenTimestamps is an open standard for decentralized timestamp proofs. It lets you prove that a document existed at a specific point in time by anchoring its cryptographic hash into the Bitcoin (or Litecoin) blockchain. The proof is stored in a compact .ots file — no trusted third party required for verification, ever.

Features

• Zero dependencies — pure TypeScript implementation, no npm supply chain risk
• Fail-closed by design — strict input validation; rejects ArrayBuffer, Buffer, and any malformed input by default
• TypeScript-first — full type declarations, TypeScript 6 strict mode, ESM + CJS dual build
• Complete protocol — create, serialize, deserialize, merge, and verify timestamps
• Merkle tree support — batch-timestamp thousands of documents in a single blockchain transaction
• Pure crypto — built-in SHA1, SHA256, and RIPEMD-160 with no native bindings

Installation

npm install @otskit/core

Requires Node.js ≥ 20.

Note on confirmation times: After submitting a timestamp, the .ots proof starts as pending — it references a calendar server but has no blockchain attestation yet. Bitcoin confirmations typically arrive within 10–60 minutes, but can take several hours depending on network congestion. This is normal. A pending proof is not a failed proof.

Quick Start

Timestamp a file

import { DetachedTimestampFile, OpSHA256, makePending } from '@otskit/core';
import { readFileSync, writeFileSync } from 'node:fs';

// Hash your file and wrap it in a detached timestamp
const fileContent = new Uint8Array(readFileSync('document.pdf'));
const dtf = DetachedTimestampFile.fromBytes(new OpSHA256(), fileContent);

// Register with an OpenTimestamps calendar (pending — will be upgraded to Bitcoin)
dtf.timestamp.attestations.push(
  makePending('https://alice.btc.calendar.opentimestamps.org'),
);

// Save the .ots proof file alongside the original document
writeFileSync('document.pdf.ots', dtf.serializeToBytes());

Read a .ots file

import { DetachedTimestampFile } from '@otskit/core';
import { readFileSync } from 'node:fs';

const otsBytes = new Uint8Array(readFileSync('document.pdf.ots'));
const dtf = DetachedTimestampFile.deserialize(otsBytes);

console.log('Hash algorithm:', dtf.fileHashOp.tagName);
console.log('File digest:   ', Buffer.from(dtf.fileDigest()).toString('hex'));
console.log('Complete:      ', dtf.timestamp.isTimestampComplete());
console.log('Attestations:  ', dtf.timestamp.getAttestations());

Verify against a Bitcoin block header

import { DetachedTimestampFile, verifyAgainstBlockheader } from '@otskit/core';
import { readFileSync } from 'node:fs';

const dtf = DetachedTimestampFile.deserialize(
  new Uint8Array(readFileSync('document.pdf.ots')),
);

// Retrieve the block header from a full node or trusted block explorer
for (const { msg, attestation } of dtf.timestamp.allAttestations()) {
  if (attestation.kind === 'bitcoin') {
    verifyAgainstBlockheader(msg, blockHeader); // throws VerificationError if invalid
    console.log(`Verified at Bitcoin block height ${attestation.height}`);
  }
}

Batch-timestamp with a Merkle tree

Anchor thousands of documents in a single blockchain transaction:

import { DetachedTimestampFile, OpSHA256, makeMerkleTree, makePending } from '@otskit/core';
import { readFileSync, writeFileSync } from 'node:fs';

const files = ['a.pdf', 'b.pdf', 'c.pdf'];
const op = new OpSHA256();

const dtfs = files.map(f =>
  DetachedTimestampFile.fromBytes(op, new Uint8Array(readFileSync(f))),
);

// One Merkle root covers all documents — one calendar call, one blockchain entry
const root = makeMerkleTree(dtfs.map(d => d.timestamp));
root.attestations.push(makePending('https://alice.btc.calendar.opentimestamps.org'));

// Each .ots file carries its own path to the shared root
files.forEach((f, i) => writeFileSync(`${f}.ots`, dtfs[i]!.serializeToBytes()));

API Reference

DetachedTimestampFile

Immutable wrapper for a .ots proof file.

| Member | Description | |--------|-------------| | DetachedTimestampFile.fromBytes(op, content) | Create from raw file bytes | | DetachedTimestampFile.fromHash(op, digest) | Create from a pre-computed digest | | DetachedTimestampFile.deserialize(bytes) | Parse a .ots file (Uint8Array only — fail-closed) | | .serializeToBytes() | Serialize back to .ots bytes | | .fileDigest() | The file's hash as Uint8Array (defensive copy) | | .fileHashOp | The CryptOp used to hash the file | | .timestamp | The root Timestamp of the proof tree |

Timestamp

A node in the proof tree. Each node holds a digest (msg), direct attestations, and operation branches leading to sub-timestamps.

| Member | Description | |--------|-------------| | new Timestamp(msg) | Create a new leaf node | | .add(op) | Apply an operation and return (or reuse) the sub-timestamp | | .addExisting(op, stamp) | Cross-link to an existing timestamp (used internally by Merkle) | | .merge(other) | Absorb attestations and branches from another timestamp with the same msg | | .attestations | Direct Attestation[] — push to add seals to this node | | .getDigest() | Defensive copy of msg | | .getAttestations() | All attestations anywhere in the tree | | .allAttestations() | All { msg, attestation } pairs in the tree | | .isTimestampComplete() | true if a Bitcoin or Litecoin attestation exists | | .allTips() | The leaf digests (nodes with no operations) | | .equals(other) | Deep structural equality |

Operations

All operations extend Op and are serializable. Binary ops (OpAppend, OpPrepend) take a Uint8Array argument in their constructor.

| Class | Tag | Description | |-------|-----|-------------| | OpSHA256 | 0x08 | SHA-256 hash | | OpSHA1 | 0x02 | SHA-1 hash | | OpRIPEMD160 | 0x03 | RIPEMD-160 hash | | OpAppend(suffix) | 0xf0 | Append bytes | | OpPrepend(prefix) | 0xf1 | Prepend bytes | | OpReverse | 0xf2 | Reverse byte order | | OpHexlify | 0xf3 | Encode to ASCII hex |

Attestations

| Function | Description | |----------|-------------| | makePending(uri) | Pending calendar attestation — proof not yet upgraded to blockchain | | makeBitcoin(height) | Bitcoin blockchain attestation at block height | | makeLitecoin(height) | Litecoin blockchain attestation at block height | | verifyAgainstBlockheader(digest, header) | Verify a 32-byte digest against a block's Merkle root — throws VerificationError on failure |

Merkle tree

| Function | Description | |----------|-------------| | makeMerkleTree(timestamps) | Build a Merkle-Mountain-Range from an array of timestamps. Returns the root. Throws EmptyMerkleTreeError on empty input. |

Serialization contexts

For low-level binary I/O following the OpenTimestamps wire format (LEB128 varints, length-prefixed bytes):

| Class | Description | |-------|-------------| | StreamSerializationContext | Write binary data; call .getOutput() for the result | | StreamDeserializationContext | Read binary data with bounds checking and EOF enforcement |

Utilities

| Function | Description | |----------|-------------| | hexToBytes(hex) | Hex string → Uint8Array | | bytesToHex(bytes) | Uint8Array → lowercase hex string | | textToBytes(text) | UTF-8 string → Uint8Array | | bytesToText(bytes) | Uint8Array → UTF-8 string (throws on invalid sequences) | | randBytes(n) | Cryptographically secure random bytes via crypto.getRandomValues — throws if unavailable |

Errors

All error classes extend Error and are exported by name for precise catch handling.

| Category | Error classes | |----------|--------------| | Deserialization | DeserializationError, BadMagicError, TruncatedStreamError, OversizedDataError, VaruintOverflowError, TrailingGarbageError, UnknownOperationError, InvalidUriError, UnsupportedVersionError | | Operation | OpExecutionError, MessageTooLongError, ResultTooLongError | | Verification | VerificationError | | Tree | EmptyTimestampError, MergeError, EmptyMerkleTreeError |

Contributing

git clone https://github.com/OTSkit/OTSkit-core.git
cd OTSkit-core
npm install
npm test           # run the full test suite
npm run build      # ESM + CJS + TypeScript declarations
npm run coverage   # test coverage report

All contributions must preserve the fail-closed philosophy: strict input validation at every boundary, no silent failures, no implicit type coercion.

License

MIT © 2026 OTSkit contributors — see LICENSE.