@linniaprotocol/linnia-js v0.3.0
LinniaJS
Quickstart
const Web3 = require("web3");
const Linnia = require("@linniaprotocol/linnia-js");
const web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:7545"));
const linnia = new Linnia(web3);
// get the deployed contracts
const { _, users, records, permissions } = await linnia.getContractInstances();
Installation
You can install using npm:
npm i @linniaprotocol/linnia-js
or add inject the library onto the window
using a script tag:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@linniaprotocol/linnia-js-script-tag@0.1.1/dist/index.min.js"></script>
Building
npm run build
The compiled library is generated in lib
, which you can require by typing require('./lib')
Setting up a Dev Environment
New to ethereum and/or Linnia? Head over to our resources page to learn more about the protocol and how to set up your ethereum development environment.
API Documentation
Constructor
new Linnia(web3 [, options])
Parameters
Object
- An instantiated web3 API objectObject
- (Optional) Constructor options
linniaContractUpgradeHubAddress
:String
- Address of the LinniaHub. If not specified, Linnia Javascript API will attempt to find the address of the deployed LinniaHub on the network defined inweb3
.
Example
const Web3 = require("web3");
const Linnia = require("@linniaprotocol/linnia-js");
const web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:7545"));
const linnia = new Linnia(web3);
linnia.getContractInstances
linnia.getContractInstances();
Gets Linnia contract instances, wrapped in truffle contract.
Returns
Promise<Object>
- A promise when resolved returns an object with truffle Contract instances.
linniaContractUpgradeHubAddress
:Object
- DO NOT USE - INTERNAL - LinniaHub truffle contract instanceusers
:Object
- LinniaUsers truffle contract instancerecords
:Object
- LinniaRecords truffle contract instancepermissions
:Object
- LinniaPermissions truffle contract instance
Example
linnia.getContractInstances().then(instances => {
let users = instances.users;
let records = instances.records;
let permissions = instances.permissions;
});
linnia.getRecord
linnia.getRecord(dataHash);
Gets a record from Linnia by data hash
Parameters
String
- The data hash, hex-encoded, 0x prefixed
Returns
Promise<Object>
- A promise when resolved returns an instance of Record class.
owner
:String
- Hex-encoded record owner addressmetadataHash
:String
- Hex-encoded metadata hashsigCount
:Object
- A bignumber object, the signature countirisScore
:Object
- A bignumber object, the IRIS scoredataUri
:String
- URI of the datatimestamp
:Date
- The timestamp when the record is added to Linnia
linnia.getAttestation
linnia.getAttestation(dataHash, attestatorAddress);
Gets the attestation of the data
Parameters
String
- The data hash, hex-encoded, 0x prefixedString
- The address of the attestator
Returns
Promise<Boolean>
- A promise when resolved returns true if the record is attested by the specified attestator.
linnia.getPermission
linnia.getPermission(dataHash, viewerAddress);
Gets the permission information of a record
Parameters
String
- The data hash, hex-encoded, 0x prefixedString
- The address of the data viewer
Returns
Promise<Object>
- A promise when resolved returns a Linnia Permission object.
canAccess
:Boolean
- True if the specified viewer is allowed to access the recorddataUri
:String
- The data URI of the shared record
Append data to Linnia
In order to append data to Linnia, your web3 instance need to be able to sign with the private key of the owner of the data.
linnia.addRecordWithReward
linnia.addRecordWithReward(dataHash, metadata, dataUri, ethParams);
Add record to Linnia and receive a small reward of linnia tokens
Parameters
String
- The data hash. Hash of the plain text data + metadataObject
- The metadata of the record. Click here to read more about the metadataString
- The dataUri, link to the data (eg. the IPFS hash)Object
- The ethParams, ethereum account params. (The object need to contain the key 'from')
Returns
Promise<Record>
- A promise when resolved returns the record object that was stored.
linnia.addRecord
linnia.addRecord(dataHash, metadata, dataUri, ethParams);
Add record to Linnia
Parameters
String
- The data hash. Hash of the plain text data + metadataObject
- The metadata of the record. Click here to read more about the metadataString
- The dataUri, link to the data (eg. the IPFS hash)Object
- The ethParams, ethereum account params. (The object need to contain the key 'from')
Returns
Promise<Record>
- A promise when resolved returns the record object that was stored.
Append data using Linnia Js in the browser
If you are using a Linnia Js in the browser you can create the Linnia instance with the web3 object from Metamask and append a record the following way:
Example
const Linnia = require("@linniaprotocol/linnia-js");
const linnia = new Linnia(web3);
const dataHash = "0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689";
const metadata = {
dataFormat: "json",
domain: "social media",
storage: "IPFS",
encryptionScheme: "x25519-xsalsa20-poly1305",
encryptionPublicKey: "hQYhHJpzZH/tGhz1wtqSjkL17tJSnEEC4yVGyNTHNQY=",
linniajsVersion: "0.1.4",
providerName: "SocialMedia",
providerEthereumAddress: "0x349e31e92027f86b0ffeb5cd5e07003c7f229872",
keywords: [ "socialmedia", "friends list", "people" ],
creationDate: new Date(Date.UTC(96, 1, 2, 3, 4, 5))
};
const dataUri = "QmSg3jCiroFERczWdpFJUau5CofHfMKCSm5vZXSzn7sZGW";
const ethParams = {
from: "0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72", gas: 500000, gasPrice: 20000000000
};
const record = await linnia.addRecord(dataHash, metadata, dataUri, ethParams);
In the example above the dataUri is the IPFS Hash where the file was stored.
Append data using Linnia Js outside of the browser
In order to add a file you need to generate a web3 instance that can handle the private keys of the owner of the file.
Example
const Linnia = require("@linniaprotocol/linnia-js");
const HDWalletProvider = require('truffle-hdwallet-provider');
// HERE YOU NEED TO ADD THE PRIVATE KEYS OF THE OWNERS
const privKeys = [privkey1, privkey2, ...]
// HERE YOU NEED TO ADD THE PROVIDER, YOU COULD GET AND INFURA KEY AND PUT IT BELOW
// OR USE ANY ETH PROVIDER
const provider = 'https://ropsten.infura.io/INFURA_KEY'
const hdWalletProvider = new HDWalletProvider(privKeys, provider);
const web3 = new Web3(hdWalletProvider);
const linnia = new Linnia(web3);
const dataHash = "0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689";
const metadata = {
dataFormat: "json",
domain: "social media",
storage: "IPFS",
encryptionScheme: "x25519-xsalsa20-poly1305",
encryptionPublicKey: "hQYhHJpzZH/tGhz1wtqSjkL17tJSnEEC4yVGyNTHNQY=",
linniajsVersion: "0.1.4",
providerName: "SocialMedia",
providerEthereumAddress: "0x349e31e92027f86b0ffeb5cd5e07003c7f229872",
keywords: [ "socialmedia", "friends list", "people" ],
creationDate: new Date(Date.UTC(96, 1, 2, 3, 4, 5))
};
const dataUri = "QmSg3jCiroFERczWdpFJUau5CofHfMKCSm5vZXSzn7sZGW";
const ethParams = {
from: "0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72", gas: 500000, gasPrice: 20000000000
};
const record = await linnia.addRecord(dataHash, metadata, dataUri, ethParams);
Attest data on Linnia
Attest data on Linnia means sign a record and verify that contain legitimate and correct information.
linnia.signRecord
linnia.signRecord(dataHash, ethParams);
Attest a record to Linnia
Parameters
String
- The data hash, hex-encoded, 0x prefixedObject
- The ethParams, ethereum account params. (The object need to contain the key 'from')
Returns
Promise<Attestation>
- A promise when resolved returns the Attestation that was added.
Example
const Linnia = require("@linniaprotocol/linnia-js");
const linnia = new Linnia(web3);
const dataHash = "0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689";
const ethParams = {
from: "0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72", gas: 500000, gasPrice: 20000000000
};
const attestation = await linnia.signRecord(dataHash, ethParams);
Record class
An instance of Record class is returned when linnia.getRecord
is called and promise resolved.
Members
owner
:String
- Hex-encoded record owner addressmetadataHash
:String
- Hex-encoded metadata hashsigCount
:Object
- A bignumber object, the signature countirisScore
:Object
- A bignumber object, the IRIS scoredataUri
:String
- URI of the datatimestamp
:Date
- The timestamp when the record is added to Linnia
record.getAttestation
record.getAttestation(attestatorAddress);
Gets the attestation of the data
Parameters
String
- The address of the attestator
Returns
Promise<Boolean>
- A promise when resolved returns true if the record is attested by the specified attestator.
Example
let dataHash =
"0x174e6ab7cf9a53497cff763d0743258f5d5014cb20ae08c7ec22bf50f5d5e326";
let attestator = "0xac07bea81fe26b379de0e4327f1a6ecd0875edfc";
linnia
.getRecord(dataHash)
.then(record => record.getAttestation(attestator))
.then(attested => {
if (attested) {
// ...
} else {
// ...
}
});
record.getPermission
record.getPermission(viewerAddress);
Gets the permission information of a record
Parameters
String
- The address of the data viewer
Returns
Promise<Object>
- A promise when resolved returns a Linnia Permission object.
canAccess
:Boolean
- True if the specified viewer is allowed to access the recorddataUri
:String
- The data URI of the shared record
record.decryptData
record.decryptData(privKey, uriResolver);
Gets the plaintext data of the record
Parameters
String
- The private key to decrypt the data(String) => (String)
- A function to resolve the data URI. The parameter is the string data URI. The function should return the plaintext data.
Returns
String
- The plaintext data
Example
let privKey =
"0x5230a384e9d271d59a05a9d9f94b79cd98fcdcee488d1047c59057046e128d2b";
linnia
.decryptData(privKey, dataUri => {
// assume data URI is HTTP URL here
return fetch(dataUri).then(res => {
return res.arrayBuffer();
});
})
.then(plainText => {
console.log(plainText.toString());
});
record.decryptPermissioned
record.decryptPermissioned(viewerAddress, privKey, uriResolver)
Gets the plaintext data of a permissioned copy of the record
Parameters
String
- The address of viewerString
- The private key to decrypt the data of the permissioned copy. Note that this is the key controlled by the viewer, not the record owner.(String) => (Promise<String>)
- A function to resolve the data URI. The parameter is the string data URI. The function should return the encrypted data..
Returns
String
- The plaintext data
record.verifyData
record.verifyData(plaintext);
Verifies the hash of the data against the one in Linnia.
Parameters
String
- The plaintext data to be verified
Returns
Boolean
- True if hash matches
record.reencryptData
record.reencryptData(pubKey, privKey, uriResolver);
Re-encrypts the data to another public key
Parameters
String
- Public key to re-encrypt the data toString
- Private key to decrypt the record data. This should be a key controlled by the record owner(String) => (String)
- A function to resolve the data URI. The parameter is the string data URI. The function should return the encrypted data.
Returns
String
- The re-encrypted data
Attestation class
Members
attestator
:String
- Hex-encoded attestator addressdataHash
:String
- Hex-encoded data hash
Utility functions
Linnia.util.encrypt
Linnia.util.encrypt(pubKeyTo, plaintext)
Encrypts a message.
Parameters
String
- The public key to encrypt the dataString
- The plaintext data
Returns
String
- The encrypted data, which includes the IV, ephemeral public key, MAC, and ciphertext.
Example
let pubKey =
"0xb1f26f98d374540eac3d31208f13a3935318e228207084c9ee32d741ff1ad2341af4ac9658aba4a254bf1dc6451b3c08524febba5273bec227c73e25cd376387";
let encrypted = Linnia.util.encrypt(pubKey, "foo");
console.log(encrypted.toString("hex"));
Linnia.util.decrypt
Linnia.util.decrypt(privKey, ciphertext);
Decrypts a message encrypted by Linnia.util.encrypt
.
Parameters
String
- The private key to decrypt the data.String
- The encrypted data, which includes the IV, ephemeral public key, MAC, and ciphertext.
Returns
String
- The decrypted plaintext
Example
let encrypted =
"0xbf18f1b6eb4b748b18cc3bd4a8d47f5f045766a445431dd918a43d6ca7871bdf7acd2214dce02a508a97f173f0697e781cf3cbf1b2d6fc0dcce940cdcef0aab443469773eb672b04117d4cb36336891aa98cd21f07d994b756f456f52db2b26a316fdbaaf87f52a638e0ad4d4280b63ec6447befdc97ecf07117bfc9eb8f8a073f";
let privKey =
"0x5230a384e9d271d59a05a9d9f94b79cd98fcdcee488d1047c59057046e128d2b";
let plaintext = Linnia.util.decrypt(privKey, encrypted).toString();
// plaintext is 'foo'