Skip to content

Latest commit

 

History

History
172 lines (133 loc) · 7.9 KB

README.md

File metadata and controls

172 lines (133 loc) · 7.9 KB
Raw

Stampery

NPM Package Build Status Code Climate Test Coverage Issue Count

NodeJS client library for Stampery API, the blockchain-powered, industrial-scale certification platform.

Seamlessly integrate industrial-scale data certification and timestamping into your own NodeJS apps. The Stampery API adds a layer of transparency, attribution, accountability and auditability to your applications by connecting them to Stampery's infinitely scalable Blockchain Timestamping Architecture.

Background

The Stampery API allows you to prove the existence, integrity and ownership of all your data by anchoring (embedding) unique identifiers (hashes) of your files and datasets into the Ethereum and Bitcoin blockchains.

The timestamps and proofs generated by this API are independently verifiable at no cost by anyone in the world, and they will be valid forever—even if Stampery disappeared.

Each proof connects every single stamped hash to a transaction contained in the next Ethereum and Bitcoin block. This means that Ethereum receipts take ~30 seconds in average to be generated, while Bitcoin ones take ~5 minutes.

Our BTA technology aggregates all hashes received between one transaction and the next one by putting them inside a Merkle tree and then broadcasting the result of the aggregation—which we call the Merkle root. This allows us to include millions of hashes in every transaction at a fraction of the cost and without loosing the immutabiity properties of public blockchains.

The proofs themselves contain only a few auxiliar hashes that when concurrently hashed together with your stamped hash, allow anyone to reconstruct the state of the Merkle tree at the very exact point in time when the stamping took place.

As all the hash functions involved in the aggregation are one-way functions, there is no way to counterfeit a proof that would connect a certain hash to any past transaction. Likewise, it is impossible to make up a fake proof that would be valid for a tampered file.

You can read more about BTA and blockchain anchoring in our whitepaper.

Glossary

  • The process of anchoring one hash into a blockchain is called stamping.
  • One embeded hash is called a stamp.
  • The stamping process will return one receipt for every blockchain being used.
  • Each receipt contains all the necessary data for proving the existence and integrity of the stamped data.
  • The part of a receipt telling where to find the blockchain transaction is called anchor.
  • Proving means demonstrating that a receipt is valid and therefore the file or dataset from which the hash was calculated existed by the time the stamp was made.
  • Feel free to use stamp as a verb and say "I will stamp this document".

Installation

  1. Install stampery into your project and add it as a dependency in your package.json:
npm install --save stampery
  1. Go to the API dashboard, sign up, create a token for your application (or use the default one) and copy its user secret. It will resemble this:
14f1e553-325f-4549-ced6-6c5311b1a470

Usage

Basic setup

/**
* Import Stampery API for NodeJS
 */
const Stampery = require('stampery');

/**
* Please replace this dummy user secret with a real one.
* Sign up and get your own user secret at https://api-dashboard.stampery.com
 */
var stampery = new Stampery('14f1e553-325f-4549-ced6-6c5311b1a470');

Stamping workflow

/**
* Simple workflow for stamping a string.
* This will return all the data related to the stamp plus an estimation of the
* remaining time in seconds for the Ethereum and Bitcoin receipts to be ready
* for proving.
 */
const hash = stampery.hash('the piano has been drinking ' + Math.random());

// Without WebHook
stampery.stamp(hash).then((stamp) => {
  return console.log(stamp);
}).catch((err) => {
  return console.error(err);
});

// With WebHook
const hook = "https://example.com/endpoint"

stampery.stamp(hash, hook).then((stamp) => {
  return console.log(stamp);
}).catch((err) => {
  return console.error(err);
});

Retrieving and proving a stamp and its receipts

/**
* Example for retrieving the receipts for a certain stamp at any time
* afterwards. It also verifies if the proof is valid and prints the result.
 */
stampery.getById('5857d1629e7cba66c3ea20a8').then((stamp) => {
   eturn console.log('Valid: ', stampery.prove(stamp.receipts));
}).catch((err) => {
  return console.error(err);
});

Retrieving all stamps related to a hash

/**
* Example for retrieving all the stamps and receipts related to a certain file
* hash at any time afterwards.
 */
stampery.getByHash('<put here the file hash>').then((stampsList) => {
  return console.log(stampsList);
}).catch((err) => {
  return console.error(err);
});

Retrieving the whole stamp history

/**
* Example for retrieving all the receipts in your stamps history at any time
* afterwards. For the sake of responsiveness, it will return only the last 50
* stamps (page 0).
 */
stampery.getAll().then((stampsList) => {
  return console.log(stampsList);
}).catch((err) => {
  return console.error(err);
});
/**
* Example for retrieving next 50 receipts from the stamps history.
* Increase the first argument to get page 0, 1, 2, 3 and so on.
* This example should return stamps numbers from 200 to 249.
 */
stampery.getAll(4).then((stampsList) => {
  return console.log(stampsList);
}).then((err) => {
  return console.error(err);
});

FAQ

Is there any privacy concern derived from using public blockchains?

No. Hashes are always calculated client-side, and only anonymous hashes go through our service and get eventually published. No one can know what you are actually stamping—not even us.

Can I choose which blockchain to use?

No. This API currently anchors your hashes into both the Ethereum and the Bitcoin blockchains for latency and redundancy reasons. In the future we may support other blockchains if they provide interesting features for anchoring.

Can I stamp the same hash twice?

Yes. You can stamp the same hash as many times as you want in order to link the hash to more than one block. Nevertheless, the most valuable stamp is always the oldest one when you aim to prove original ownership or existence of a file.

What is the effective timestamp for a stamp?

Every receipt contains a time field that tells the exact point in time in which the API received the hash. This trust-based, rather traditional timestamp is solely attested by Stampery.

For a decentralized, tamper-proof, censor-resistant, math-backed timestamp, the valid date you are looking for is the one that appears when you take the transaction ID from the anchor in each receipt and search it in a blockchain explorer.

Feedback

Ping us at [email protected] and we will be more than happy to help you with your integration! 😃

License

Code released under the MIT license.

© 2015-2018 Stampery, Inc.