Introduction

Quickstart

Planetmint is a metadata blockchain. This introduction gives an overview about how to attest data to Planetmint. First, simple transaction creation and sending is shown. Thereafter, an introdcution about how to set up a single node or a cluster is given.

The IPDB Testnet - sending transactions

The IPDB foundation hosts a testnet server that is reset every night at 4am UTC.

The following sequence shows a simple asset notarization / attestion on that testnet: Create a file named notarize.py

from planetmint_driver import Planetmint
from planetmint_driver.crypto import generate_keypair

plntmnt = Planetmint('https://test.ipdb.io')
alice = generate_keypair()
tx = plntmnt.transactions.prepare(
    operation='CREATE',
    signers=alice.public_key,
    asset={'data': {'message': 'Blockchain all the things!'}})
signed_tx = plntmnt.transactions.fulfill(
    tx,
    private_keys=alice.private_key)
plntmnt.transactions.send_commit(signed_tx)

install dependencies and execute it

$ pip install planetmint-driver
$ python notarize.py

Install Planetmint

Local Node

Planemtint is a Tendermint applicatoin with an attached database. A basic installation installs the database, Tendermint and therafter Planetmint.

Planetmint currently supports Tarantool and MongoDB database. The installation is as follows:

# Tarantool
$ curl -L https://tarantool.io/release/2/installer.sh | bash
$ sudo apt-get -y install tarantool

Caveat: Tarantool versions before 2.4.2 automatically enable and start a demonstration instance that listens on port 3301 by default. Refer to the Tarantool documentation for more information.

# MongoDB
$ sudo apt install mongodb

Tendermint can be installed and started as follows

$ wget https://github.com/tendermint/tendermint/releases/download/v0.34.15/tendermint_0.34.15_linux_amd64.tar.gz
$ tar zxf tendermint_0.34.15_linux_amd64.tar.gz
$ ./tendermint init
$ ./tendermint node --proxy_app=tcp://localhost:26658

Planetmint installs and starts as described below

$ pip install planetmint
$ planetmint configure
$ planetmint start

Cluster of nodes

Setting up a cluster of nodes comes down to set up a cluster of tendermint nodes as documented at Tendermint. In addition to that, the database and Planetmint need to be installed on the servers as described above.

Setup Instructions for Various Cases

Develop an App Test

To develop an app that talks to a Planetmint network, you’ll want a test network to test it against. You have a few options:

  1. The IPDB Test Network (or “Testnet”) is a free-to-use, publicly-available test network that you can test against. It is available at IPDB testnet.

  2. You could also run a Planetmint node on you local machine. One way is to use this node setup guide with a one-node “network” by using the all-in-one docker solution, or manual installation and configuration of the components. Another way is to use one of the deployment methods listed in the network setup guide or in the the docs about contributing to Planetmint.

.. Copyright © 2020 Interplanetary Database Association e.V., Planetmint and IPDB software contributors. SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0

What is Planetmint

Basic Facts

  1. One can store arbitrary data (including encrypted data) in a Planetmint network, within limits: there’s a maximum transaction size. Every transaction has a metadata section which can store almost any Unicode string (up to some maximum length). Similarly, every CREATE transaction has an asset.data section which can store almost any Unicode string.

  2. . The data stored in certain Planetmint transaction fields must not be encrypted, e.g. public keys and amounts. Planetmint doesn’t offer private transactions akin to Zcoin.

  3. Once data has been stored in a Planetmint network, it’s best to assume it can’t be change or deleted.

  4. Every node in a Planetmint network has a full copy of all the stored data.

  5. Every node in a Planetmint network can read all the stored data.

  6. Everyone with full access to a Planetmint node (e.g. the sysadmin of a node) can read all the data stored on that node.

  7. Everyone given access to a node via the Planetmint HTTP API can find and read all the data stored by Planetmint. The list of people with access might be quite short.

  8. If the connection between an external user and a Planetmint node isn’t encrypted (using HTTPS, for example), then a wiretapper can read all HTTP requests and responses in transit.

  9. If someone gets access to plaintext (regardless of where they got it), then they can (in principle) share it with the whole world. One can make it difficult for them to do that, e.g. if it is a lot of data and they only get access inside a secure room where they are searched as they leave the room.

Planetmint for Asset Registrations & Transfers

Planetmint can store data of any kind, but it’s designed to be particularly good for storing asset registrations and transfers:

  • The fundamental thing that one sends to a Planetmint network, to be checked and stored (if valid), is a transaction, and there are two kinds: CREATE transactions and TRANSFER transactions.

  • A CREATE transaction can be use to register any kind of asset (divisible or indivisible), along with arbitrary metadata.

  • An asset can have zero, one, or several owners.

  • The owners of an asset can specify (crypto-)conditions which must be satisfied by anyone wishing transfer the asset to new owners. For example, a condition might be that at least 3 of the 5 current owners must cryptographically sign a TRANSFER transaction.

  • Planetmint verifies that the conditions have been satisfied as part of checking the validity of TRANSFER transactions. (Moreover, anyone can check that they were satisfied.)

  • Planetmint prevents double-spending of an asset.

  • Validated transactions are immutable.

.. note::

We used the word “owners” somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See the section titled A Note about Owners in the relevant Planetmint Transactions Spec <https://github.com/planetmint/BEPs/tree/master/tx-specs/>_.

Production-Ready?

Depending on your use case, Planetmint may or may not be production-ready. You should ask your service provider. If you want to go live (into production) with Planetmint, please consult with your service provider.

Note: Planetmint has an open source license with a “no warranty” section that is typical of open source licenses. This is standard in the software industry. For example, the Linux kernel is used in production by billions of machines even though its license includes a “no warranty” section. Warranties are usually provided above the level of the software license, by service providers.

Storing Private Data Off-Chain

A system could store data off-chain, e.g. in a third-party database, document store, or content management system (CMS) and it could use Planetmint to:

  • Keep track of who has read permissions (or other permissions) in a third-party system. An example of how this could be done is described below.

  • Keep a permanent record of all requests made to the third-party system.

  • Store hashes of documents-stored-elsewhere, so that a change in any document can be detected.

  • Record all handshake-establishing requests and responses between two off-chain parties (e.g. a Diffie-Hellman key exchange), so as to prove that they established an encrypted tunnel (without giving readers access to that tunnel). There are more details about this idea in the Privacy Protocols repository <https://github.com/planetmint/privacy-protocols>_.

A simple way to record who has read permission on a particular document would be for the third-party system (“DocPile”) to store a CREATE transaction in a Planetmint network for every document+user pair, to indicate that that user has read permissions for that document. The transaction could be signed by DocPile (or maybe by a document owner, as a variation). The asset data field would contain 1) the unique ID of the user and 2) the unique ID of the document. The one output on the CREATE transaction would only be transferable/spendable by DocPile (or, again, a document owner).

To revoke the read permission, DocPile could create a TRANSFER transaction, to spend the one output on the original CREATE transaction, with a metadata field to say that the user in question no longer has read permission on that document.

This can be carried on indefinitely, i.e. another TRANSFER transaction could be created by DocPile to indicate that the user now has read permissions again.

DocPile can figure out if a given user has read permissions on a given document by reading the last transaction in the CREATE → TRANSFER → TRANSFER → etc. chain for that user+document pair.

There are other ways to accomplish the same thing. The above is just one example.

You might have noticed that the above example didn’t treat the “read permission” as an asset owned (controlled) by a user because if the permission asset is given to (transferred to or created by) the user then it cannot be controlled any further (by DocPile) until the user transfers it back to DocPile. Moreover, the user could transfer the asset to someone else, which might be problematic.

Storing Private Data On-Chain, Encrypted

There are many ways to store private data on-chain, encrypted. Every use case has its own objectives and constraints, and the best solution depends on the use case. The IPDB consulting team <contact@ipdb.global>_ can help you design the best solution for your use case.

Below we describe some example system setups, using various crypto primitives, to give a sense of what’s possible.

Please note:

  • Ed25519 keypairs are designed for signing and verifying cryptographic signatures, not for encrypting and decrypting messages <https://crypto.stackexchange.com/questions/27866/why-curve25519-for-encryption-but-ed25519-for-signatures>_. For encryption, you should use keypairs designed for encryption, such as X25519.

  • If someone (or some group) publishes how to decrypt some encrypted data on-chain, then anyone with access to that encrypted data will be able to get the plaintext. The data can’t be deleted.

  • Encrypted data can’t be indexed or searched by MongoDB. (It can index and search the ciphertext, but that’s not very useful.) One might use homomorphic encryption to index and search encrypted data, but MongoDB doesn’t have any plans to support that any time soon. If there is indexing or keyword search needed, then some fields of the asset.data or metadata objects can be left as plain text and the sensitive information can be stored in an encrypted child-object.

System Example 1


Encrypt the data with a symmetric key and store the ciphertext on-chain (in ``metadata`` or ``asset.data``). To communicate the key to a third party, use their public key to encrypt the symmetric key and send them that. They can decrypt the symmetric key with their private key, and then use that symmetric key to decrypt the on-chain ciphertext.

The reason for using a symmetric key along with public/private keypairs is so the ciphertext only has to be stored once.

System Example 2

This example uses proxy re-encryption <https://en.wikipedia.org/wiki/Proxy_re-encryption>_:

#. MegaCorp encrypts some data using its own public key, then stores that encrypted data (ciphertext 1) in a Planetmint network. #. MegaCorp wants to let others read that encrypted data, but without ever sharing their private key and without having to re-encrypt themselves for every new recipient. Instead, they find a “proxy” named Moxie, to provide proxy re-encryption services. #. Zorban contacts MegaCorp and asks for permission to read the data. #. MegaCorp asks Zorban for his public key. #. MegaCorp generates a “re-encryption key” and sends it to their proxy, Moxie. #. Moxie (the proxy) uses the re-encryption key to encrypt ciphertext 1, creating ciphertext 2. #. Moxie sends ciphertext 2 to Zorban (or to MegaCorp who forwards it to Zorban). #. Zorban uses his private key to decrypt ciphertext 2, getting the original un-encrypted data.

Note:

  • The proxy only ever sees ciphertext. They never see any un-encrypted data.

  • Zorban never got the ability to decrypt ciphertext 1, i.e. the on-chain data.

  • There are variations on the above flow.

System Example 3


This example uses `erasure coding <https://en.wikipedia.org/wiki/Erasure_code>`_:

#. Erasure-code the data into n pieces.
#. Encrypt each of the n pieces with a different encryption key.
#. Store the n encrypted pieces on-chain, e.g. in n separate transactions.
#. Share each of the the n decryption keys with a different party.

If k < N of the key-holders gets and decrypts k of the pieces, they can reconstruct the original plaintext. Less than k would not be enough.

System Example 4

This setup could be used in an enterprise blockchain scenario where a special node should be able to see parts of the data, but the others should not.

  • The special node generates an X25519 keypair (or similar asymmetric encryption keypair).

  • A Planetmint end user finds out the X25519 public key (encryption key) of the special node.

  • The end user creates a valid Planetmint transaction, with either the asset.data or the metadata (or both) encrypted using the above-mentioned public key.

  • This is only done for transactions where the contents of asset.data or metadata don’t matter for validation, so all node operators can validate the transaction.

  • The special node is able to decrypt the encrypted data, but the other node operators can’t, and nor can any other end user.

Properties of Planetmint

Decentralization

Decentralization means that no one owns or controls everything, and there is no single point of failure.

Ideally, each node in a Planetmint network is owned and controlled by a different person or organization. Even if the network lives within one organization, it’s still preferable to have each node controlled by a different person or subdivision.

We use the phrase “Planetmint consortium” (or just “consortium”) to refer to the set of people and/or organizations who run the nodes of a Planetmint network. A consortium requires some form of governance to make decisions such as membership and policies. The exact details of the governance process are determined by each consortium, but it can be very decentralized.

A consortium can increase its decentralization (and its resilience) by increasing its jurisdictional diversity, geographic diversity, and other kinds of diversity.

There’s no node that has a long-term special position in the Planetmint network. All nodes run the same software and perform the same duties.

If someone has (or gets) admin access to a node, they can mess with that node (e.g. change or delete data stored on that node), but those changes should remain isolated to that node. The Planetmint network can only be compromised if more than one third of the nodes get compromised. See the Tendermint documentation for more details.

It’s worth noting that not even the admin or superuser of a node can transfer assets. The only way to create a valid transfer transaction is to fulfill the current crypto-conditions on the asset, and the admin/superuser can’t do that because the admin user doesn’t have the necessary information (e.g. private keys).

Byzantine Fault Tolerance

Tendermint is used for consensus and transaction replication, and Tendermint is Byzantine Fault Tolerant (BFT).

Node Diversity

Steps should be taken to make it difficult for any one actor or event to control or damage “enough” of the nodes. (Because Planetmint Server uses Tendermint, “enough” is ⅓.) There are many kinds of diversity to consider, listed below. It may be quite difficult to have high diversity of all kinds.

  1. Jurisdictional diversity. The nodes should be controlled by entities within multiple legal jurisdictions, so that it becomes difficult to use legal means to compel enough of them to do something.

  2. Geographic diversity. The servers should be physically located at multiple geographic locations, so that it becomes difficult for a natural disaster (such as a flood or earthquake) to damage enough of them to cause problems.

  3. Hosting diversity. The servers should be hosted by multiple hosting providers (e.g. Amazon Web Services, Microsoft Azure, Digital Ocean, Rackspace), so that it becomes difficult for one hosting provider to influence enough of the nodes.

  4. Diversity in general. In general, membership diversity (of all kinds) confers many advantages on a consortium. For example, it provides the consortium with a source of various ideas for addressing challenges.

Note: If all the nodes are running the same code, i.e. the same implementation of Planetmint, then a bug in that code could be used to compromise all of the nodes. Ideally, there would be several different, well-maintained implementations of Planetmint Server (e.g. one in Python, one in Go, etc.), so that a consortium could also have a diversity of server implementations. Similar remarks can be made about the operating system.

Immutability

The blockchain community often describes blockchains as “immutable.” If we interpret that word literally, it means that blockchain data is unchangeable or permanent, which is absurd. The data can be changed. For example, a plague might drive humanity extinct; the data would then get corrupted over time due to water damage, thermal noise, and the general increase of entropy.

It’s true that blockchain data is more difficult to change (or delete) than usual. It’s more than just “tamper-resistant” (which implies intent), blockchain data also resists random changes that can happen without any intent, such as data corruption on a hard drive. Therefore, in the context of blockchains, we interpret the word “immutable” to mean practically immutable, for all intents and purposes. (Linguists would say that the word “immutable” is a term of art in the blockchain community.)

Blockchain data can be made immutable in several ways:

  1. No APIs for changing or deleting data. Blockchain software usually doesn’t expose any APIs for changing or deleting the data stored in the blockchain. Planetmint has no such APIs. This doesn’t prevent changes or deletions from happening in other ways; it’s just one line of defense.

  2. Replication. All data is replicated (copied) to several different places. The higher the replication factor, the more difficult it becomes to change or delete all replicas.

  3. Internal watchdogs. All nodes monitor all changes and if some unallowed change happens, then appropriate action can be taken.

  4. External watchdogs. A consortium may opt to have trusted third-parties to monitor and audit their data, looking for irregularities. For a consortium with publicly-readable data, the public can act as an auditor.

  5. Economic incentives. Some blockchain systems make it very expensive to change old stored data. Examples include proof-of-work and proof-of-stake systems. Planetmint doesn’t use explicit incentives like those.

  6. Data can be stored using fancy techniques, such as error-correction codes, to make some kinds of changes easier to undo.

  7. Cryptographic signatures are often used as a way to check if messages (e.g. transactions) have been tampered with enroute, and as a way to verify who signed the messages. In Planetmint, each transaction must be signed by one or more parties.

  8. Full or partial backups may be recorded from time to time, possibly on magnetic tape storage, other blockchains, printouts, etc.

  9. Strong security. Node owners can adopt and enforce strong security policies.