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
instancedfs
-DfsInterface
:DfsInterface
instanceexecutor
-Executor
:Executor
instancekeyProvider
-KeyProvider
:KeyProvider
instancenameResolver
-NameResolver
:NameResolver
instancecontractLoader
-ContractLoader
:ContractLoader
instanceweb3
-Web3
:Web3
instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
(optional): messages with this level will be logged withlog
logLog
-LogLogInterface
(optional): container for collecting log messageslogLogLevel
-LogLevel
(optional): messages with this level will be pushed tologLog
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 storedaccountId
-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 addressenvelope
-Envelope
: description as an envelopeaccountId
-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 storedreaderAddress
-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 storedenvelope
-Envelope
: description as an envelopeencryptorAddress
-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 storedenvelope
-Envelope
: description as an envelopeaccountId
-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);