Description

Class Name	Description
Extends	Description
Source	description.ts
Examples	description.spec.ts

The Description module is the main entry point for interacting with contract descriptions. It allows you to:

get and set descriptions
work with contracts and ENS descriptions
create web3.js contract instances directly from an Ethereum address and its description
The main use cases for interacting with a contracts description in your application will most probably be reading a contracts description and loading contracts via their description.

The examples folder folder contains some samples for getting started. With consuming or setting contract descriptions.

When setting descriptions to contracts, these contracts have to support the Executor interface.

A simple flow for working with description may look like following:

We already have smart contract, that supports the zz interface and set a description to it.

const address = '0x...'; // or 'test.evan' as ens name
const accountId = '0x...';
const description = {
  "public": {
    "name": "DBCP sample contract",
    "description": "DBCP sample contract description",
    "author": "dbcp test",
    "tags": [
      "example",
      "greeter"
    ],
    "version": "0.1.0",
    "dbcpVersion": 2
  }
};
await runtime.description.setDescription(address, description, accountId);

Now we have made some updates to our contract and we want to update its version to 0.2.0.

// get description const retrieved = await runtime.description.getDescription(address, accountId);

// update version const accountId = ‘0x000000000000000000000000000000000000beef’; retrieved.public.version = ‘0.2.0’; await runtime.description.setDescription(address, retrieved, accountId);

constructor

new Description(options);

Creates a new Description instance.

Parameters

options - DescriptionOptions: options for Description constructor.
- cryptoProvider - CryptoProvider: CryptoProvider instance
- dfs - DfsInterface: DfsInterface instance
- executor - Executor: Executor instance
- keyProvider - KeyProvider: KeyProvider instance
- nameResolver - NameResolver: NameResolver instance
- contractLoader - ContractLoader: ContractLoader instance
- web3 - Web3: Web3 instance
- log - Function (optional): function to use for logging: (message, level) => {...}
- logLevel - LogLevel (optional): messages with this level will be logged with log
- logLog - LogLogInterface (optional): container for collecting log messages
- logLogLevel - LogLevel (optional): messages with this level will be pushed to logLog

Returns

Description instance

Example

const description = new Description({
    cryptoProvider,
    dfs,
    executor,
    keyProvider,
    nameResolver,
    contractLoader,
    web3,
  });

getDescription

description.getDescription(address, accountId);

loads description envelope from ens or contract if an ENS address has a contract set as well and this contract has a defintion, the contract definition is preferred over the ENS definition and therefore returned

Parameters

address - string: The ens address or contract address where the description is stored
accountId - string: identity or account that is allowed to read the description

Returns

Promise returns Envelope: description as an Envelope.

Example

const address = '0x9c0Aaa728Daa085Dfe85D3C72eE1c1AdF425be49';
const accountId = '0x000000000000000000000000000000000000beef';
const description = await runtime.description.getDescription(address, accountId);
console.dir(description);
// Output:
// { public:
//    { name: 'DBCP sample greeter',
//      description: 'smart contract with a greeting message and a data property',
//      author: 'dbcp test',
//      tags: [ 'example', 'greeter' ],
//      version: '0.1.0',
//      dbcpVersion: 2,
//      abis: { own: [Array] } } }

setDescription

description.setDescription(address, envelope, accountId);

set description, can be used for contract addresses and ENS addresses

Parameters

address - string: contract address or ENS address
envelope - Envelope: description as an envelope
accountId - string: identity or account supposed to encrypt the description

Returns

Promise returns void: resolved when done.

Example

const address = '0x...'; // or 'test.evan' as ens name
const accountId = '0x...';
const description = {
  "public": {
    "name": "DBCP sample contract",
    "description": "DBCP sample contract description",
    "author": "dbcp test",
    "tags": [
      "example",
      "greeter"
    ],
    "dbcpVersion": 2,
    "version": "0.1.0"
  }
};
await runtime.description.setDescription(address, description, accountId);

validateDescription

Descriptions are validated when setting them. A list of known DBCP definition schemas is maintained in description.schema.ts . If a description is set, its property dbcpVersion will be used for validating the description, if dbcpVersion is not provided, version 1 is used and a warning is logged.

Descriptions can be checked against the validator before setting them.

description.validateDescription(envelope);

try to validate description envelope; throw Error if validation fails

Parameters

envelope - Envelope: envelop with description data; private has to be unencrypted

Returns

Promise returns boolean|any[]: true if valid or array of issues.

Example

const brokenDescription = {
  "public": {
    "name": "DBCP sample contract with way to few properties",
  }
};
console.log(runtime.description.validateDescription(brokenDescription));
// Output:
// [ { keyword: 'required',
//     dataPath: '',
//     schemaPath: '#/required',
//     params: { missingProperty: 'description' },
//     message: 'should have required property \'description\'' },
//   { keyword: 'required',
//     dataPath: '',
//     schemaPath: '#/required',
//     params: { missingProperty: 'author' },
//     message: 'should have required property \'author\'' },
//   { keyword: 'required',
//     dataPath: '',
//     schemaPath: '#/required',
//     params: { missingProperty: 'version' },
//     message: 'should have required property \'version\'' } ]

const workingDescription = {
  "public": {
    "name": "DBCP sample contract",
    "description": "DBCP sample contract description",
    "author": "dbcp test",
    "tags": [
      "example",
      "greeter"
    ],
    "version": "0.1.0"
  }
};
console.log(runtime.description.validateDescription(workingDescription));
// Output:
// true

= Contract =

getDescriptionFromContract

description.getDescriptionFromContract(address, myIdentity);

loads description envelope from contract

Parameters

address - string: The contract address where the description is stored
readerAddress - string: identity or account that is allowed to read the description

Returns

Promise returns Envelope: description as an Envelope.

Example

const address = '0x9c0Aaa728Daa085Dfe85D3C72eE1c1AdF425be49';
const identityId = '0x000000000000000000000000000000000000beef';
const description = await runtime.description.getDescriptionFromContract(address, identityId);
console.dir(description);
// Output:
// { public:
//    { name: 'DBCP sample greeter',
//      description: 'smart contract with a greeting message and a data property',
//      author: 'dbcp test',
//      tags: [ 'example', 'greeter' ],
//      version: '0.1.0',
//      dbcpVersion: 2,
//      abis: { own: [Array] } } }

setDescriptionToContract

description.setDescriptionToContract(contractAddress, envelope, myIdentity);

store description at contract

Parameters

contractAddress - string: The contract address where description will be stored
envelope - Envelope: description as an envelope
encryptorAddress - string: identity or account that is supposed to encrypt the description

Returns

Promise returns void: resolved when done.

Example

const address = '0x...';
const myIdentity = '0x...';
const description = {
  "public": {
    "name": "DBCP sample contract",
    "description": "DBCP sample contract description",
    "author": "dbcp test",
    "tags": [
      "example",
      "greeter"
    ],
    "version": "0.1.0",
    "dbcpVersion": 2
  }
};
await runtime.description.setDescriptionToContract(address, description, myIdentity);

= ENS =

ENS addresses are able to hold multiple values at once. So they may be holding a contract address and a description. If this is the case and the contract at the ENS address has another description, the contracts description is preferred over the ENS description. If you explicitly intend to retrieve an ENS endpoints description and want to ignore the contracts description, use the function getDescriptionFromEns.

getDescriptionFromEns

description.getDescriptionFromEns(address);

loads description envelope from ens

Parameters

ensAddress - string: The ens address where the description is stored

Returns

Promise returns Envelope: description as an Envelope.

Example

const address = '0x9c0Aaa728Daa085Dfe85D3C72eE1c1AdF425be49';
const accountId = '0x000000000000000000000000000000000000beef';
const description = await runtime.description.getDescriptionFromContract(address, accountId);
console.dir(description);
// Output:
// { public:
//    { name: 'DBCP sample greeter',
//      description: 'smart contract with a greeting message and a data property',
//      author: 'dbcp test',
//      tags: [ 'example', 'greeter' ],
//      version: '0.1.0',
//      dbcpVersion": 2,
//      abis: { own: [Array] } } }

setDescriptionToEns

description.setDescriptionToEns(ensAddress, envelope, accountId);

store description at contract

Parameters

contractAddress - string: The ens address where description will be stored
envelope - Envelope: description as an envelope
accountId - string: identity or account that is supposed to encrypt the description

Returns

Promise returns void: resolved when done.

Example

const address = '0x...';
const accountId = '0x...';
const description = {
  "public": {
    "name": "DBCP sample contract",
    "description": "DBCP sample contract description",
    "author": "dbcp test",
    "tags": [
      "example",
      "greeter"
    ],
    "version": "0.1.0",
    "dbcpVersion": 2
  }
};
await runtime.description.setDescriptionToEns(address, description, accountId);