amarnath-rao / building-on-bitcoin-hackathon

StacksShare

This prototype was the submission for the Building on Bitcoin Hackathon by dabuchera and hujens. It was part of our ongoing research efforts (see also here). The contribution took 2nd winner place.

The prototype demonstrates how to use role-based and token-based smart contract access control for files and text snippets. This is exciting because access-logic to data can be decentralized with the dApp and Smart Contracts, instead of relying on access logic managed by a central server. The data is stored off-chain using a data storage protocol called Gaia.

Follow the instructions below to test the prototype.

Important: Please be patient. It takes time until transactions are confirmed and changes to the access logic are reflected in the prototype. You can always check the state of the transaction in the Stacks Explorer, e.g. for the RolesAccess or TokenAccess contract.

Test the Prototype

We deployed a test instance of the prototype. The dApp is accessible here. The smart contracts are deployed on the Stacks testnet (RolesAccess, TokenAccess, accessNFT, ownershipNFT).

Follow this tutorial to store and access files:

Getting Ready

1. Install Hiro Wallet for the browser of your choice. Follow the set up process and carefully memorize your Seed and password if you plan to reuse your account at a later stage.
2. Enter the menu (top right) in the Hiro wallet and "Change Network" to "testnet".
3. Move to the Testnet faucet to receive some free STX so you can pay for transactions. You need to connect your wallet with the account you want to fund.
4. Access the StacksShare dApp and connect your account with the "Connect Wallet" button.

The landing page to connect the wallet.

Upload Data

• To upload a new file or text you can head to the /upload tab.
• Public files will not be encrypted.
• Private files (not public) will be encrypted and can only be accessed with the connected account that uploaded the file.

Upload page.

Enable Sharing of Data

• After the upload the file is visible under the main page.
• Files can be deleted or shared.

The uploaded private file.

• When clicking "Allow Sharing", the dApp receives permission to share the data.
• The sharing control button becomes available, where role-based and token-based sharing can be specified.

After enabling sharing, the file is marked as shared.

Shared, public, and private files are marked respectively.

Sharing Control

• The buttons trigger the access logic in the respective smart contracts. The smart contracts are deployed on the Stacks testnet (RolesAccess, TokenAccess).

Role-Based Sharing

• Role-Based sharing means to share files on an address-basis. Access-rights are non-transferable.
• The owner account first needs to claim ownership by registering for the ownership role.
• Then the owner can register other accounts to grant them access to the data.

The sharing control page of the file: Role-Based access control.

Token-Based Sharing

• Token-based sharing means to share files on a token basis. Every holder of an access-NFT can access the data. This means access-rights are transferable.
• The owner first claims the ownership-NFT.
• Afterwards, the owner holding the ownership-NFT can claim access-NFTs to send to other accounts to grant access.

The sharing control page of the file: Token-Based access control.

Account 1 is the owner of the file. It owns the ownership-NFT and two access-NFTs that can be sent to other accounts.

Access Data

• If another account connects with the dApp without permssions to access files, it sees them as private in the /overview tab (even if they were shared with the dApp or other accounts).

Account 3 sees the shared files with the dApp also as private.

• Account 2 received access permission through an accessNFT.
• The dApp recognizes the connected account holds an accessNFT and grants permission to access the data. It is also visible as shared in the /overview tab.
• In case Account 2 holds an access role, the dApp notices this in the same way as it notices wether it holds an access-NFT by reading the states of access roles from the smart contract.

Account 2 owns one of the access-NFTs.

Account 2 can access the shared file in the dApp.

Local Development

We use Stacks for this protoype with smart contracts written in Clarity.

To run and test the smart contracts locally, you can deploy them to a local network with Clarinet.

• Install Clarinet.

Test Contracts with Unit Tests

## Move into /contracts folder
$ cd contracts

## Execute the unit tests in a local network
$ clarinet test

Test Contracts with Front-End

• Install and run Docker.
• Spwan a local Devnet and deploy the contracts:

## Move into /contracts folder
$ cd contracts

## Start the local network and deploy contracts
$ clarinet integrate

Next, start the front-end. The frontend was built using React and Chakra.

## Move into /frontend folder
$ cd frontend

# Install dependencies
$ npm install

# Start dev server
$ npm run dev

Access the frontend on the indicated localhost, most likely http://localhost:3000.

Finally, connect a wallet to interact with the deployed contracts on Devnet. For that you need a blockchain wallet to interact with the dApp and the smart contracts. The most popular choice for Stacks is for now the Hiro Wallet.

• Install Hiro for the browser of your choice.
• Set up a wallet with one of the default addresses listed in the Devnet.toml file (so you have a funded address to play with).