Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stampery/node
Stampery API for NodeJS. Notarize all your data using the blockchain
https://github.com/stampery/node
anchoring bitcoin blockchain ethereum hash nodejs stampery
Last synced: about 2 months ago
JSON representation
Stampery API for NodeJS. Notarize all your data using the blockchain
- Host: GitHub
- URL: https://github.com/stampery/node
- Owner: stampery
- License: mit
- Created: 2015-09-09T12:28:17.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-02-20T09:26:41.000Z (almost 7 years ago)
- Last Synced: 2024-09-18T12:24:26.987Z (4 months ago)
- Topics: anchoring, bitcoin, blockchain, ethereum, hash, nodejs, stampery
- Language: CoffeeScript
- Size: 133 KB
- Stars: 22
- Watchers: 6
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Stampery
[](https://www.npmjs.org/package/stampery)
[](https://travis-ci.org/stampery/node)
[](https://codeclimate.com/github/stampery/node)
[](https://codeclimate.com/github/stampery/node/coverage)
[](https://codeclimate.com/github/stampery/node)
__NodeJS__ client library for [__Stampery API__](https://stampery.com/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__](https://stampery.com/tech).
## 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/One-way_function), __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__](https://s3.amazonaws.com/stampery-cdn/docs/Stampery-BTA-v5-whitepaper.pdf).
#### 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
```
2. Go to the [API dashboard](https://api-dashboard.stampery.com), 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
```javascript
/**
* 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
```javascript
/**
* 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
```javascript
/**
* 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
```javascript
/**
* Example for retrieving all the stamps and receipts related to a certain file
* hash at any time afterwards.
*/
stampery.getByHash('').then((stampsList) => {
return console.log(stampsList);
}).catch((err) => {
return console.error(err);
});
```
### Retrieving the whole stamp history
```javascript
/**
* 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);
});
```
```javascript
/**
* 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]](mailto:[email protected]) and we will be more than happy to help you with your integration! 😃
## License
Code released under [the MIT license](https://github.com/stampery/node/blob/master/LICENSE).
© 2015-2018 Stampery, Inc.