@lacrypta/typescript-opentimestamps
v0.1.0
Published
An OpenTimestamps client written in TypeScript
Downloads
4
Keywords
Readme
TypeScript OpenTimestamps (typescript-opentimestamps
)
An OpenTimestamps client written in TypeScript
This project aims to provide a fully-tested, fully typed, OpenTimestamps Client. It currently supports stamping, upgrading, and verifying timestamps.
Table of Contents
Background
The OpenTimestamps project currently hosts a number of Server, Client, and CLI implementations. This is our contribution to that list, adding TypeScript to it.
The project may be used as-is in Typescript directly, or it may be compiled and packaged for usage in the browser or NodeJS modules.
Install
Installing the library is straightforward:
npm add @lacrypta/typescript-opentimestamps
yarn add @lacrypta/typescript-opentimestamps
pnpm add @lacrypta/typescript-opentimestamps
The only run-time dependency is @noble/hashes
.
Usage
Once installed the library can be directly imported:
import {
type Timestamp,
read as read,
verify as verify,
//
verifiers,
} from '@lacrypta/typescript-opentimestamps';
const rawTimestamp: Uint8Array = Uint8Array.from(someTimestampBytes);
const timestamp: Timestamp = read(rawTimestamp);
verify(
timestamp,
verifiers,
).then(
({ attestations, errors }: { attestations: Record<number, string[]>; errors: Record<string, Error[]> }): void => {
Object.entries(attestations).forEach(([time, verifiers]: [string, string[]]): void => {
console.log(`Verifiers ${verifiers.join(', ')} attest to this timestamp as of ${time}`);
});
Object.entries(errors).forEach(([verifier, errorList]: [string, Error[]]): void => {
console.log(`${verifier} reported the following errors:`);
errorList.forEach((error: Error): void => {
console.log(error.message);
});
});
},
);
API
This library exports the following types:
Timestamp
: a type alias containing version, file hash, and validation tree information.
It exports the following functions:
info
: obtain a human-readable description of theTimestamp
's content.canShrink
: determine whether the givenTimestamp
can be shrunk to a single attestation chain.canUpgrade
: determine whether the givenTimestamp
ca be upgraded via a Calendar.canVerify
: determine whether the givenTimestamp
can be verified in the blockchain(s).read
: read aUint8Array
and transform it into aTimestamp
if valid.shrink
: eliminate all but the oldest attestation found in the givenTimestamp
for the given chain.submit
: submit the givenTimestamp
to a Calendar for eventual inclusion in a blockchain.upgrade
: upgrade the givenTimestamp
via a Calendar so as to make it independently verifiable.is
: a TypeScript type predicate that simply applies validation to the givenTimestamp
.validate
: validate the given parameter and determine whether it is indeed aTimestamp
object.verify
: verify the givenTimestamp
against the blockchain(s).- verifiers: a set of predefined lambda functions that will query the blockchain via explorer-provider APIs to check for the presence of a given Merkle root on-chain.
write
: generate aUint8Array
consisting of the standard serialization of the givenTimestamp
value.
More in-depth information and prototypes can be found in the generated documentation.
Contributing
This project uses pnpm
(think npm
but faster), you'll need to install it if you haven't already.
You may clone the repository as usual:
git clone [email protected]:lacrypta/typescript-opentimestamps.git
cd typescript-opentimestamps
Now, simply install all dependencies:
pnpm install
We provide several pnpm
commands for your convenience:
pnpm format
: will run formatters and linters in all the codebase.pnpm build
: will build all targets (TypeScript type declarations included) in the/dist
directory.pnpm analyze
: will analyze previous build.pnpm doc
: will generate internal and external documentation in the/dist
directory.pnpm clean
: will remove the/dist
directory entirely.pnpm test
: will run all tests and report coverage on the whole codebase.pnpm reset
: will runpnpm clean
, and remove the/node_modules
directory andpnpm-lock.yaml
file, so as to completely reset the installation.
You'll probably want to run the tests first, build the documentation, and take it from there:
pnpm test
pnpm doc
Now navigate to /dist/docs/api/index.html
(for the end-use documentation) or /dist/docs/internal/index.html
(for developer documentation) and peruse the generated documentation at your leisure.
Please follow contribution guidelines at the GitHub repository, we encourage PRs!
License
GNU Affero General Public License v3.0 or later, see LICENSE.md.