{"id":21280830,"url":"https://github.com/consensysmesh/stow-js","last_synced_at":"2025-07-11T10:32:56.590Z","repository":{"id":57163071,"uuid":"136506589","full_name":"ConsenSysMesh/stow-js","owner":"ConsenSysMesh","description":"Stow  JavaScript API -- Formerly linnia-js ","archived":false,"fork":false,"pushed_at":"2018-12-20T22:19:48.000Z","size":1498,"stargazers_count":19,"open_issues_count":1,"forks_count":4,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-11-10T19:43:44.978Z","etag":null,"topics":["decentralized-applications","ethereum","linnia"],"latest_commit_sha":null,"homepage":"https://stow-protocol.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ConsenSysMesh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-07T16:52:45.000Z","updated_at":"2023-07-20T16:47:30.000Z","dependencies_parsed_at":"2022-09-11T16:30:16.412Z","dependency_job_id":null,"html_url":"https://github.com/ConsenSysMesh/stow-js","commit_stats":null,"previous_names":["consensys/stow-js","consensys/linnia-js"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConsenSysMesh%2Fstow-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConsenSysMesh%2Fstow-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConsenSysMesh%2Fstow-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConsenSysMesh%2Fstow-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ConsenSysMesh","download_url":"https://codeload.github.com/ConsenSysMesh/stow-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225715945,"owners_count":17512908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decentralized-applications","ethereum","linnia"],"created_at":"2024-11-21T10:41:18.660Z","updated_at":"2024-11-21T10:41:19.678Z","avatar_url":"https://github.com/ConsenSysMesh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/ConsenSys/stow-resources/master/assets/stow-logo.png\" width=\"300\" height=\"300\" /\u003e\n\n## [![NPM Package](https://img.shields.io/npm/v/@stowprotocol/stow-js.svg?style=flat-square)](https://www.npmjs.com/package/@stowprotocol/stow-js) ![Build Status](https://circleci.com/gh/ConsenSys/stow-js.png?circle-token=:circle-token\u0026style=shield)\n\n# StowJS\n\n## Quickstart\n\n```javascript\nconst Web3 = require(\"web3\");\nconst Stow = require(\"@stowprotocol/stow-js\");\n\nconst web3 = new Web3(new Web3.providers.HttpProvider(\"http://localhost:7545\"));\n\nconst stow = new Stow(web3);\n\n// get the deployed contracts\nconst { _, users, records, permissions } = await stow.getContractInstances();\n```\n\n## Installation\n\nYou can install using npm:\n\n```bash\nnpm i @stowprotocol/stow-js\n```\n\nor add inject the library onto the `window` using a script tag:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"https://cdn.jsdelivr.net/npm/@stowprotocol/stow-js-script-tag@0.3.0/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\n## Building\n\n```\nnpm run build\n```\n\nThe compiled library is generated in `lib`, which you can require by typing `require('./lib')`\n\n## Setting up a Dev Environment\n\nNew to ethereum and/or Stow? Head over to our [resources page](https://github.com/ConsenSys/stow-resources) to learn more about the protocol and how to set up your ethereum development environment.\n\n## API Documentation\n\n### Constructor\n\n```javascript\nnew Stow(web3 [, options])\n```\n\n### Parameters\n\n1. `Object` - An instantiated web3 API object\n1. `Object` - (Optional) Constructor options\n\n- `hubAddress`: `String` - Address of the StowHub. If not specified, library will use the address of the latest version of the contract deployed on the network.\n- `tokenAddress`:`String` - Address of the StowToken.  If not specified, library will use the address of the latest version of the contract deployed on the network.\n### Example\n\n```javascript\nconst Web3 = require(\"web3\");\nconst Stow = require(\"@stowprotocol/stow-js\");\nconst web3 = new Web3(new Web3.providers.HttpProvider(\"http://localhost:7545\"));\nconst stow = new Stow(web3);\n```\n\n## stow.getContractInstances\n\n```javascript\nstow.getContractInstances();\n```\n\nGets Stow contract instances, wrapped in truffle contract.\n\n### Returns\n\n`Promise\u003cObject\u003e` - A promise when resolved returns an object with truffle Contract instances.\n\n- `_hub`: `Object` - DO NOT USE - INTERNAL - StowHub truffle contract instance\n- `users`: `Object` - StowUsers truffle contract instance\n- `records`: `Object` - StowRecords truffle contract instance\n- `permissions`: `Object` - StowPermissions truffle contract instance\n\n### Example\n\n```javascript\nstow.getContractInstances().then(instances =\u003e {\n  let users = instances.users;\n  let records = instances.records;\n  let permissions = instances.permissions;\n});\n```\n\n## stow.getRecord\n\n```javascript\nstow.getRecord(dataHash);\n```\n\nGets a record from Stow by data hash\n\n### Parameters\n\n1. `String` - The data hash, hex-encoded, 0x prefixed\n\n### Returns\n\n`Promise\u003cObject\u003e` - A promise when resolved returns an instance of Record class.\n\n- `owner`: `String` - Hex-encoded record owner address\n- `metadataHash`: `String` - Hex-encoded metadata hash\n- `sigCount`: `Object` - A bignumber object, the signature count\n- `irisScore`: `Object` - A bignumber object, the IRIS score\n- `dataUri`: `String` - URI of the data\n- `timestamp`: `Date` - The timestamp when the record is added to Stow\n\n## stow.getAttestation\n\n```javascript\nstow.getAttestation(dataHash, attesterAddress);\n```\n\nGets the attestation of the data\n\n### Parameters\n\n1. `String` - The data hash, hex-encoded, 0x prefixed\n1. `String` - The address of the attester\n\n### Returns\n\n`Promise\u003cBoolean\u003e` - A promise when resolved returns true if the record is attested by the specified attester.\n\n## stow.getPermission\n\n```javascript\nstow.getPermission(dataHash, viewerAddress);\n```\n\nGets the permission information of a record\n\n### Parameters\n\n1. `String` - The data hash, hex-encoded, 0x prefixed\n1. `String` - The address of the data viewer\n\n### Returns\n\n`Promise\u003cObject\u003e` - A promise when resolved returns a Stow Permission object.\n\n- `canAccess`: `Boolean` - True if the specified viewer is allowed to access the record\n- `dataUri`: `String` - The data URI of the shared record\n\n---\n\n# Append data to Stow\n\nIn order to append data to Stow, your web3 instance need to be able to sign with the private key of the owner of the data.\n\n## stow.addRecordWithReward\n\n```javascript\nstow.addRecordWithReward(dataHash, metadata, dataUri, ethParams);\n```\n\nAdd record to Stow and receive a small reward of stow tokens.  This requires an optional parameter\nto be set in the constructor as follows: \n\n`new Stow(web3, (tokenAddress: 0x4cdfbdec0aa003116bf030f249a8a7285cd6a184))`\n\n\n### Parameters\n\n1. `String` - The data hash. Hash of the plain text data + metadata\n2. `Object` - The metadata of the record. [Click here to read more about the metadata](https://github.com/ConsenSys/stow-resources/blob/master/METADATA.md)\n3. `String` - The dataUri, link to the data (eg. the IPFS hash)\n4. `Object` - The ethParams, ethereum account params. (The object need to contain the key 'from')\n\n### Returns\n\n`Promise\u003cRecord\u003e` - A promise when resolved returns the record object that was stored.\n\n## stow.addRecord\n\n```javascript\nstow.addRecord(dataHash, metadata, dataUri, ethParams);\n```\n\nAdd record to Stow\n\n### Parameters\n\n1. `String` - The data hash. Hash of the plain text data + metadata\n2. `Object` - The metadata of the record. [Click here to read more about the metadata](https://github.com/ConsenSys/stow-resources/blob/master/METADATA.md)\n3. `String` - The dataUri, link to the data (eg. the IPFS hash)\n4. `Object` - The ethParams, ethereum account params. (The object need to contain the key 'from')\n\n### Returns\n\n`Promise\u003cRecord\u003e` - A promise when resolved returns the record object that was stored.\n\n### Append data using Stow Js in the browser\n\n If you are using a Stow Js in the browser you can create the Stow instance with the web3 object from Metamask and append a record the following way:\n\n### Example\n\n```javascript\nconst Stow = require(\"@stowprotocol/stow-js\");\nconst stow = new Stow(web3);\n\nconst dataHash = \"0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689\";\nconst metadata = {\n    dataFormat: \"json\",\n    domain: \"social media\",\n    storage: \"IPFS\",\n    encryptionScheme: \"x25519-xsalsa20-poly1305\",\n    encryptionPublicKey: \"hQYhHJpzZH/tGhz1wtqSjkL17tJSnEEC4yVGyNTHNQY=\",\n    stowjsVersion: \"0.1.4\",\n    providerName: \"SocialMedia\",\n    providerEthereumAddress: \"0x349e31e92027f86b0ffeb5cd5e07003c7f229872\",\n    keywords: [ \"socialmedia\", \"friends list\", \"people\" ],\n    creationDate: new Date(Date.UTC(96, 1, 2, 3, 4, 5))\n};\nconst dataUri = \"QmSg3jCiroFERczWdpFJUau5CofHfMKCSm5vZXSzn7sZGW\";\nconst ethParams = {\n    from: \"0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72\", gas: 500000, gasPrice: 20000000000\n};\n\nconst record = await stow.addRecord(dataHash, metadata, dataUri, ethParams);\n```\n\nIn the example above the dataUri is the IPFS Hash where the file was stored.\n\n### Append data using Stow Js outside of the browser\n\nIn order to add a file you need to generate a web3 instance that can handle the private keys of the owner of the file.\n\n### Example\n\n```javascript\nconst Stow = require(\"@stowprotocol/stow-js\");\nconst HDWalletProvider = require('truffle-hdwallet-provider');\n\n// HERE YOU NEED TO ADD THE PRIVATE KEYS OF THE OWNERS\nconst privKeys = [privkey1, privkey2, ...]\n                  \n// HERE YOU NEED TO ADD THE PROVIDER, YOU COULD GET AND INFURA KEY AND PUT IT BELOW \n// OR USE ANY ETH PROVIDER\nconst provider = 'https://ropsten.infura.io/INFURA_KEY'\nconst hdWalletProvider = new HDWalletProvider(privKeys, provider);\nconst web3 = new Web3(hdWalletProvider);\n\nconst stow = new Stow(web3);\n\nconst dataHash = \"0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689\";\nconst metadata = {\n    dataFormat: \"json\",\n    domain: \"social media\",\n    storage: \"IPFS\",\n    encryptionScheme: \"x25519-xsalsa20-poly1305\",\n    encryptionPublicKey: \"hQYhHJpzZH/tGhz1wtqSjkL17tJSnEEC4yVGyNTHNQY=\",\n    stowjsVersion: \"0.1.4\",\n    providerName: \"SocialMedia\",\n    providerEthereumAddress: \"0x349e31e92027f86b0ffeb5cd5e07003c7f229872\",\n    keywords: [ \"socialmedia\", \"friends list\", \"people\" ],\n    creationDate: new Date(Date.UTC(96, 1, 2, 3, 4, 5))\n};\nconst dataUri = \"QmSg3jCiroFERczWdpFJUau5CofHfMKCSm5vZXSzn7sZGW\";\nconst ethParams = {\n    from: \"0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72\", gas: 500000, gasPrice: 20000000000\n};\n\nconst record = await stow.addRecord(dataHash, metadata, dataUri, ethParams);\n```\n\n# Attest data on Stow\n\nAttest data on Stow means sign a record and verify that contain legitimate and correct information.\n\n## stow.signRecord\n\n```javascript\nstow.signRecord(dataHash, ethParams);\n```\n\nAttest a record to Stow\n\n### Parameters\n\n1. `String` - The data hash, hex-encoded, 0x prefixed\n2. `Object` - The ethParams, ethereum account params. (The object need to contain the key 'from')\n\n### Returns\n\n`Promise\u003cAttestation\u003e` - A promise when resolved returns the Attestation that was added.\n\n### Example\n\n```javascript\nconst Stow = require(\"@stowprotocol/stow-js\");\nconst stow = new Stow(web3);\n\nconst dataHash = \"0xcc85fc3d763b9a1d83e4386b37b4b0f3daf9881638ba8b7db0c501c417acb689\";\nconst ethParams = {\n    from: \"0xb717d7adf0d19f5f48bb7ff0030e30fcd19eed72\", gas: 500000, gasPrice: 20000000000\n};\n\nconst attestation = await stow.signRecord(dataHash, ethParams);\n```\n\n------\n\n\n\n# Record class\n\nAn instance of Record class is returned when `stow.getRecord` is called and promise resolved.\n\n## Members\n\n- `owner`: `String` - Hex-encoded record owner address\n- `metadataHash`: `String` - Hex-encoded metadata hash\n- `sigCount`: `Object` - A bignumber object, the signature count\n- `irisScore`: `Object` - A bignumber object, the IRIS score\n- `dataUri`: `String` - URI of the data\n- `timestamp`: `Date` - The timestamp when the record is added to Stow\n\n## record.getAttestation\n\n```javascript\nrecord.getAttestation(attesterAddress);\n```\n\nGets the attestation of the data\n\n### Parameters\n\n1. `String` - The address of the attester\n\n### Returns\n\n`Promise\u003cBoolean\u003e` - A promise when resolved returns true if the record is attested by the specified attester.\n\n### Example\n\n```javascript\nlet dataHash =\n  \"0x174e6ab7cf9a53497cff763d0743258f5d5014cb20ae08c7ec22bf50f5d5e326\";\nlet attester = \"0xac07bea81fe26b379de0e4327f1a6ecd0875edfc\";\nstow\n  .getRecord(dataHash)\n  .then(record =\u003e record.getAttestation(attester))\n  .then(attested =\u003e {\n    if (attested) {\n      // ...\n    } else {\n      // ...\n    }\n  });\n```\n\n## record.getPermission\n\n```javascript\nrecord.getPermission(viewerAddress);\n```\n\nGets the permission information of a record\n\n### Parameters\n\n1. `String` - The address of the data viewer\n\n### Returns\n\n`Promise\u003cObject\u003e` - A promise when resolved returns a Stow Permission object.\n\n- `canAccess`: `Boolean` - True if the specified viewer is allowed to access the record\n- `dataUri`: `String` - The data URI of the shared record\n\n## record.decryptData\n\n```javascript\nrecord.decryptData(privKey, uriResolver);\n```\n\nGets the plaintext data of the record\n\n### Parameters\n\n1. `String` - The private key to decrypt the data\n1. `(String) =\u003e (String)` - A function to resolve the data URI. The parameter is the string data URI. The function should return the plaintext data.\n\n### Returns\n\n`String` - The plaintext data\n\n### Example\n\n```javascript\nlet privKey =\n  \"0x5230a384e9d271d59a05a9d9f94b79cd98fcdcee488d1047c59057046e128d2b\";\nstow\n  .decryptData(privKey, dataUri =\u003e {\n    // assume data URI is HTTP URL here\n    return fetch(dataUri).then(res =\u003e {\n      return res.arrayBuffer();\n    });\n  })\n  .then(plainText =\u003e {\n    console.log(plainText.toString());\n  });\n```\n\n## record.decryptPermissioned\n\n```javascript\nrecord.decryptPermissioned(viewerAddress, privKey, uriResolver)\n```\n\nGets the plaintext data of a permissioned copy of the record\n\n### Parameters\n\n1. `String` - The address of viewer\n1. `String` - 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.\n1. `(String) =\u003e (Promise\u003cString\u003e)` - A function to resolve the data URI. The parameter is the string data URI. The function should return the encrypted data..\n\n### Returns\n\n`String` - The plaintext data\n\n## record.verifyData\n\n```javascript\nrecord.verifyData(plaintext);\n```\n\nVerifies the hash of the data against the one in Stow.\n\n### Parameters\n\n1. `String` - The plaintext data to be verified\n\n### Returns\n\n`Boolean` - True if hash matches\n\n## record.reencryptData\n\n```javascript\nrecord.reencryptData(pubKey, privKey, uriResolver);\n```\n\nRe-encrypts the data to another public key\n\n### Parameters\n\n1. `String` - Public key to re-encrypt the data to\n1. `String` - Private key to decrypt the record data. This should be a key controlled by the record owner\n1. `(String) =\u003e (String)` - A function to resolve the data URI. The parameter is the string data URI. The function should return the encrypted data.\n\n### Returns\n\n`String` - The re-encrypted data\n\n---\n\n# Attestation class\n\n## Members\n\n- `attester`: `String` - Hex-encoded attester address\n- `dataHash`: `String` - Hex-encoded data hash\n\n------\n\n\n\n# Utility functions\n\n## Stow.util.encrypt\n\n```javascript\nStow.util.encrypt(pubKeyTo, plaintext)\n```\n\nEncrypts a message.\n\n### Parameters\n\n1. `String` - The public key to encrypt the data\n1. `String` - The plaintext data\n\n### Returns\n\n`String` - The encrypted data, which includes the IV, ephemeral public key, MAC, and ciphertext.\n\n### Example\n\n```javascript\nlet pubKey =\n  \"0xb1f26f98d374540eac3d31208f13a3935318e228207084c9ee32d741ff1ad2341af4ac9658aba4a254bf1dc6451b3c08524febba5273bec227c73e25cd376387\";\nlet encrypted = Stow.util.encrypt(pubKey, \"foo\");\nconsole.log(encrypted.toString(\"hex\"));\n```\n\n## Stow.util.decrypt\n\n```javascript\nStow.util.decrypt(privKey, ciphertext);\n```\n\nDecrypts a message encrypted by `Stow.util.encrypt`.\n\n### Parameters\n\n1. `String` - The private key to decrypt the data.\n1. `String` - The encrypted data, which includes the IV, ephemeral public key, MAC, and ciphertext.\n\n### Returns\n\n`String` - The decrypted plaintext\n\n### Example\n\n```javascript\nlet encrypted =\n  \"0xbf18f1b6eb4b748b18cc3bd4a8d47f5f045766a445431dd918a43d6ca7871bdf7acd2214dce02a508a97f173f0697e781cf3cbf1b2d6fc0dcce940cdcef0aab443469773eb672b04117d4cb36336891aa98cd21f07d994b756f456f52db2b26a316fdbaaf87f52a638e0ad4d4280b63ec6447befdc97ecf07117bfc9eb8f8a073f\";\nlet privKey =\n  \"0x5230a384e9d271d59a05a9d9f94b79cd98fcdcee488d1047c59057046e128d2b\";\nlet plaintext = Stow.util.decrypt(privKey, encrypted).toString();\n// plaintext is 'foo'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsensysmesh%2Fstow-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconsensysmesh%2Fstow-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsensysmesh%2Fstow-js/lists"}