Service Contract¶

Class Name	ServiceContract
Extends	Logger
Source	service-contract.ts
Examples	service-contract.spec.ts

constructor¶

new ServiceContract(options);

Creates a new ServiceContract instance.

Parameters¶

options - ServiceContractOptions: options for ServiceContract constructor.
- cryptoProvider - CryptoProvider: CryptoProvider instance
- dfs - DfsInterface: DfsInterface instance
- keyProvider - KeyProvider: KeyProvider instance
- sharing - Sharing: Sharing instance
- web3 - Web3: Web3 instance
- defaultCryptoAlgo - string (optional): crypto algorith name from CryptoProvider, defaults to aes
- 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¶

ServiceContract instance

Example¶

const serviceContract = new ServiceContract({
    cryptoProvide,
    dfs,
    executor,
    keyProvider,
    loader,
    nameResolver,
    sharing,
    web3,
  });

create¶

serviceContract.create(accountId, businessCenterDomain, service[, descriptionDfsHash]);

create and initialize new contract

Parameters¶

accountId - string: owner(identity or account) of the new contract and transaction executor
businessCenterDomain - string: ENS domain name of the business center
service - any: service definition
descriptionHash - string (optional): bytes2 hash of DBCP description, defaults to 0x0000000000000000000000000000000000000000000000000000000000000000

Returns¶

Promise returns any: contract instance

Example¶

const serviceContract = await serviceContract.create(accounts[0], businessCenterDomain, sampleService);

= Service =¶

The service is the communication pattern definition for the ServiceContract. A single service contract can only have one service definition and all calls and answers must follow its defition.

To create calls and answers with different patterns, create a new ServiceContract and use an updated service definition there.

setService¶

serviceContract.setService(contract, accountId, service, businessCenterDomain[, skipValidation]);

Set service description.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
service - any: service to set
businessCenterDomain - string: domain of the business the service contract belongs to
skipValidation - bool (optional): skip validation of service definition, validation is enabled by default

Returns¶

Promise returns void: resolved when done

Example¶

await serviceContract.setService(contract, accounts[0], sampleService, businessCenterDomain);

getService¶

serviceContract.getService(contract, accountId);

Gets the service of a service contract.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account

Returns¶

Promise returns string: service description as JSON string

Example¶

const service = await sc.getService(contract, accounts[0]);

= Calls =¶

Calls are the requests done by authors, that initiate a service conversation. They are basically the first part of conversations and allow answers to be added to them. Calls are usually broadcasted or multicasted.

Samples for calls are:

capacity requests
information requests
information broadcasts

sendCall¶

serviceContract.sendCall(contract, accountId, call);

Send a call to a service.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
call - any: call to send

Returns¶

Promise returns number: id of new call

Example¶

const callId = await serviceContract.sendCall(contract, accounts[0], sampleCall);

getCalls¶

serviceContract.getCalls(contract, accountId[, count, offset, reverse]);

Get all calls from a contract.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
count - number (optional): number of elments to retrieve, defaults to 10
offset - number (optional): skip this many elements, defaults to 0
reverse - boolean (optional): retrieve last elements first, defaults to false

Returns¶

Promise returns any[]: the calls

Example¶

const calls = await serviceContract.getCalls(contract, accounts[0]);

getCall¶

serviceContract.getCall(contract, accountId, callId);

Get a call from a contract.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
callId - number: index of the call to retrieve

Returns¶

Promise returns any: a single call

Example¶

const call = await serviceContract.getCall(contract, accounts[0], 12);

getCallCount¶

serviceContract.getCallCount(contract);

Get number of calls of a contract.

Parameters¶

contract - any|string: smart contract instance or contract ID

Returns¶

Promise returns number: number of calls

Example¶

let callCount = await serviceContract.getCallCount(contract);
console.log(callCount);
// Output:
// 2
await serviceContract.sendCall(contract, accounts[0], sampleCall);
callCount = await serviceContract.getCallCount(contract);
console.log(callCount);
// Output:
// 3

getCallOwner¶

serviceContract.getCallOwner(contract, callId);

Gets the owner/creator of a call.

Parameters¶

contract - any|string: smart contract instance or contract ID
callId - number: index of the call to retrieve owner for

Returns¶

Promise returns string: account id of call owner

Example¶

console.log(await serviceContract.getCallOwner(contract, 2));
// Output:
0x0000000000000000000000000000000000000001

addToCallSharing¶

serviceContract.addToCallSharing(contract, accountId, callId, to[, hashKey, contentKey, section]);

Adds list of accounts to a calls sharings list.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
callId - number: id of the call to retrieve
to - string[]: accountIds, to add sharings for
hashKey - string (optional): hash key to share, if omitted, key is retrieved with accountId
contentKey - string (optional): content key to share, if omitted, key is retrieved with accountId
section - string (optional): section to share key for, defaults to ‘*’

Returns¶

Promise returns void: resolved when done

Example¶

// account[0] adds accounts[2] to a sharing
await serviceContract.addToCallSharing(contract, accounts[0], callId, [accounts[2]]);

= Answers =¶

Answers are replies to calls. Answers can only be created as answers to calls. Answers are usually directed to the author of a call.

Examples are

capacity replies
information responses

sendAnswer¶

serviceContract.sendAnswer(contract, accountId, answer, callId, callAuthor);

Send answer to service contract call.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
answer - any: answer to send
callId - number: index of the call to which the answer was created
callAuthor - string: Ethereum account ID of the creator of the initial call

Returns¶

Promise returns number: id of new answer

Example¶

await serviceContract.inviteToContract(businessCenterDomain, contract.options.address, accounts[0], accounts[2]);
const contentKey = await sharing.getKey(contract.options.address, accounts[0], '*', 0);
await sharing.addSharing(contract.options.address, accounts[0], accounts[2], '*', 0, contentKey);
await serviceContract.sendCall(contract, accounts[0], sampleCall);
const call = await serviceContract.getCall(contract, accounts[0], 0);
const answerId = await serviceContract.sendAnswer(contract, accounts[2], sampleAnswer, 0, call.metadata.author);

getAnswers¶

serviceContract.getAnswers(contract, accountId, callid[, count, offset, reverse]);

Retrieves answers for a given call.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: Ethereum account ID
callId - number: index of the call to which the answers were created
count - number (optional): number of elements to retrieve, defaults to 10
offset - number (optional): skip this many elements, defaults to 0
reverse - boolean (optional): retrieve last elements first, defaults to false

Returns¶

Promise returns any[]: the answers

Example¶

const answers = await serviceContract.getAnswers(contract, accounts[0], 12);

getAnswer¶

serviceContract.getAnswer(contract, accountId, answerIndex);

Get a answer from a contract.

Parameters¶

contract - any|string: smart contract instance or contract ID
accountId - string: identity or account
callId - number: index of the call to which the answer was created
answerIndex - number: index of the answer to retrieve

Returns¶

Promise returns any: a single answer

Example¶

const answer = await serviceContract.getAnswer(contract, accounts[0], 12, 2);

getAnswerCount¶

serviceContract.getAnswerCount(contract, callId);

Retrieves number of answers for a given call.

Parameters¶

contract - any|string: smart contract instance or contract ID
callId - number: index of the call to which the answer was created

Returns¶

Promise returns number: number of answers

Example¶

const sampleCallId = 3;
let answerCount = await serviceContract.getAnswerCount(contract, sampleCallId);
console.log(answerCount);
// Output:
// 2
await serviceContract.sendAnswer(contract, accounts[0], sampleAnswer, sampleCallId, accounts[1]);
answerCount = await serviceContract.getAnswerCount(contract, sampleCallId);
console.log(answerCount);
// Output:
// 3