Consent Contracts
Overview¶
This section goes over how to create a Consent Contract for sharing of data with your partners, customers, patients, or other third parties.
NOTE: It is important to understand that multiple types of documents are stored on the BurstChain® and can be consented and
viewed. When creating a consent contract you can specify that you only want to share a certain type of document, either
an asset or a smart contract. To restrict to a specific type you’ll need define that in the WHEN clause. If a document
type isn’t specified in the WHEN clause then the consent contract will share both assets and smart contracts with the consented party.
| Clause | Description |
|---|---|
consents {value} |
This is where you can define who is being consented data. |
for {chain-name} |
This defines the chain that contains the data that is being consented. |
until Date('{date-time}') |
This sets the time duration that the data is consented. |
when {conditional} |
This contains a conditional for when data is shared. |
only {attributes} |
This allows you to specify certain attributes that are being shared. |
—¶
CONSENTS¶
This section specifies who is being consented the data. This could contain specific Public ID, IDs, role, or ‘*’.
In the examples below you will see consent contracts for a fake chain called test_data.
Consenting to a single person whose Public ID is 123456789:
CONSENTS '123456789' FOR test_data
Consenting to multiple people:
CONSENTS '123456789', '987654321' FOR test_data
Consenting to everyone:
CONSENTS * FOR test_chain
Consenting does have a special case for supressing a field. Using the keywords GLOBAL SUPRESS with a Public ID, a
list of Public IDs or a '*' consent everything, and if you specify fields in the ONLY cluase it will only prevent
those fields from showing up in query results.
In the example below if we have a chain called test_data that contains fields name, age and date_of_birth and we used
GLOBAL SUPPRESS with '*', all users who own or were consented data in that chain when querying data will see
everything but the name field.
CONSENT GLOBAL SUPPRESS '*' FOR test_data ONLY name
Global is a special use case that certain users will have access to write because it applies globally to the chain that
is specified in the global suppress consent contract. In this example where name is suppressed, any user who queries
the data and is not the owner of the data would not be able to see the name. This functions differently from normal
consent contracts because it applies to anyone who querys for data in that chain.
CONSENT GLOBAL SUPPRESS '*' FOR test_data ONLY name
The example above is the equivalent of this one below assuming that the only fields in the chain are name, age, and date_of_birth.
CONSENTS '*' FOR test_data ONLY age, date_of_birth
FOR¶
This defines the chain that contains the data that is being consented.
The below example is consenting data to the user whose public id is 123456789 from the chain test_data.
CONSENTS '123456789' FOR test_data
WHEN¶
This contains a conditional for when data is shared, it follows the same rules as the Tql and TQLFlow WHERE clause.
Adding type = 'asset' to the WHEN clause will consent only assets and will not share smart contracts.
To only consent smart contracts (consent contracts) with another user you can add type = 'smart_contract' to the
WHEN clause.
In the example below, data is being consented to the user whose Public ID is 123456789 from the chain test_data but
only if the asset has an attribute called “name” whose value is “John” and where the result is an asset and not a smart contract.
CONSENTS '123456789' FOR test_data WHEN name = 'John' AND type = 'asset'
ONLY¶
This allows you to specify certain attributes that are being shared.
In the example, data is consented to the user whose Public ID is 123456789 from the chain test_data, but they
can only see the field “name” from the data shared.
CONSENTS '123456789' FOR test_data ONLY name
UNTIL¶
This sets an expiration time for the consented data. After this date the user who was consented data will no longer be able to query for the consented data.
The example below is consenting data to the user whose Public ID is 123456789 from the chain test_data until January 10th, 2020.
CONSENTS '123456789' FOR test_data UNTIL Date('2020-01-10')
This next example works the same as the one above with one exception. The until contains a time with the date, so now the consent contract expires on January 10th, 2020 as 8:30 AM.
CONSENTS '123456789' FOR test_data UNTIL Datetime('2020-01-10 08:40:00.000')