Description¶
Class Name | Description |
---|---|
Extends | Logger |
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 descriptin 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.
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
: Account id to load the contract address for
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',
// 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
: ETH account id
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"
],
"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, accountId);
loads description envelope from contract
Parameters¶
address
-string
: The ens address or contract address where the description is storedaccountId
-string
: Account id to load the contract address for
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',
// abis: { own: [Array] } } }
setDescriptionToContract¶
description.setDescriptionToContract(contractAddress, envelope, accountId);
store description at contract
Parameters¶
contractAddress
-string
: The contract address where description will be storedenvelope
-Envelope
: description as an envelopeaccountId
-string
: ETH account id
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"
}
};
await runtime.description.setDescriptionToContract(address, description, accountId);
= 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',
// 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
: ETH account id
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"
}
};
await runtime.description.setDescriptionToEns(address, description, accountId);