Class: DomainsService

modules/domains.DomainsService

Service responsible for handling the request to ENS, creating roles/organizations/applications namespaces. See more information about ENS and domains in IAM stack here.

const { connectToCacheServer } = await initWithPrivateKeySigner(privateKey, rpcUrl);
const { domainsService } = await connectToCacheServer();
domainsService.createOrganization(...);

Table of contents

Constructors

• constructor

Accessors

• domainReader

Methods

• changeAppOwnership
• changeOrgOwnership
• changeRoleOwnership
• checkExistenceOfDomain
• createApplication
• createOrganization
• createRole
• deleteApplication
• deleteOrganization
• deleteRole
• getAllowedRolesByIssuer
• getAllowedRolesByRevoker
• getAppsOfOrg
• getDIDsByRole
• getDefinition
• getENSTypesByOwner
• getENSTypesBySearchPhrase
• getOrgHierarchy
• getRolesByNamespace
• getSubOrgsByOrgNamespace
• getSubdomains
• init
• isOwner
• namespacesWithRelations
• readName
• registrationTypesOfRoles
• setRoleDefinition
• updateLegacyDefinition
• validateOwnership
• create

Constructors

constructor

• new DomainsService(_signerService, _cacheClient)

Parameters

Name	Type
_signerService	SignerService
_cacheClient	CacheClient

Accessors

domainReader

• get domainReader(): DomainReader

Returns

DomainReader

Methods

changeAppOwnership

▸ changeAppOwnership(options): Promise<undefined | ReturnStepWithRetryCheck[]>

Change owner of application domain.

domainsService.changeAppOwnership({
    namespace: 'auth.apps.energyweb.iam.ewc',
    newOwner: '0x00...0',
    returnSteps: true,
});

Parameters

Name	Type	Description
options	ChangeAppOwnershipOptions	object containing options

Returns

Promise<undefined | ReturnStepWithRetryCheck[]>

array of steps if returnSteps is true

---

changeOrgOwnership

▸ changeOrgOwnership(options): Promise<undefined | MulticallTx>

Change owner of organization domain including all subdomains.

domainsService.changeOrgOwnership({
    namespace: 'energyweb.iam.ewc',
    newOwner: '0x00...0',
    returnSteps: true,
    withSubdomains: true,
});

Parameters

Name	Type	Description
options	ChangeOrgOwnershipOptions	object containing options

Returns

Promise<undefined | MulticallTx>

array of steps if returnSteps is true

---

changeRoleOwnership

▸ changeRoleOwnership(options): Promise<void>

Change owner of role domain.

domainsService.changeRoleOwnership({
    namespace: 'root.roles.energyweb.iam.ewc',
    newOwner: '0x00...0',
});

Parameters

Name	Type	Description
options	ChangeRoleOwnershipOptions	object containing options

Returns

Promise<void>

---

checkExistenceOfDomain

▸ checkExistenceOfDomain(options): Promise<boolean>

Check if domain exists in ENS registry.

domainsService.checkExistenceOfDomain({
    domain: 'some.energyweb.iam.ewc',
});

Parameters

Name	Type	Description
options	CheckExistenceOfDomainOptions	object containing options

Returns

Promise<boolean>

true if domain exists, false otherwise

---

createApplication

▸ createApplication(options): Promise<undefined | ReturnStep[]>

Create application domain with given definition for given namespace. Also includes creating subdomain for roles. (roles.yourApp.apps.yourOrg.ewc).

domainsService.createApplication({
    appName: 'auth',
    namespace: 'apps.energyweb.iam.ewc',
    data: {
        appName: 'Auth service',
    },
    returnSteps: true,
});

Parameters

Name	Type	Description
options	CreateApplicationOptions	object containing options

Returns

Promise<undefined | ReturnStep[]>

array of steps if returnSteps is true

---

createOrganization

▸ createOrganization(options): Promise<undefined | ReturnStep[]>

Create organization domain with given definition for given namespace. Also includes creating subdomains for roles and applications. (roles.yourOrg.ewc, apps.yourOrg.ewc).

domainsService.createOrganization({
    orgName: 'auth',
    namespace: 'energyweb.iam.ewc',
    data: {
        orgName: 'Auth service',
    },
    returnSteps: true,
});

Parameters

Name	Type	Description
options	CreateOrganizationOptions	object containing options

Returns

Promise<undefined | ReturnStep[]>

array of steps if returnSteps is true

---

createRole

▸ createRole(options): Promise<undefined | ReturnStep[]>

Create role domain with given definition for given namespace.

domainsService.createRole({
    appName: 'root',
    namespace: 'roles.energyweb.iam.ewc',
    data: {
        version: 1,
        issuer: {
            issuerType: 'DID',
            did: ['did:ethr:volta:0x00...0'],
        },
        revoker: {
            issuerType: 'DID',
            did: ['did:ethr:volta:0x00...0'],
        },
        enrolmentPreconditions: [],
    },
    returnSteps: true,
});

Parameters

Name	Type	Description
options	CreateRoleOptions	object containing options

Returns

Promise<undefined | ReturnStep[]>

array of steps if returnSteps is true

---

deleteApplication

▸ deleteApplication(options): Promise<undefined | ReturnStepWithRetryCheck[]>

Delete application domain and all subdomains.

domainsService.deleteApplication({
    namespace: 'auth.apps.energyweb.iam.ewc',
    returnSteps: true,
});

Parameters

Name	Type	Description
options	DeleteApplicationOptions	object containing options

Returns

Promise<undefined | ReturnStepWithRetryCheck[]>

array of steps if returnSteps is true

---

deleteOrganization

▸ deleteOrganization(options): Promise<undefined | ReturnStepWithRetryCheck[]>

Delete organization domain and all subdomains.

domainsService.deleteOrganization({
    namespace: 'energyweb.iam.ewc',
    returnSteps: true,
});

Parameters

Name	Type	Description
options	DeleteOrganizationOptions	object containing options

Returns

Promise<undefined | ReturnStepWithRetryCheck[]>

array of steps if returnSteps is true

---

deleteRole

▸ deleteRole(options): Promise<void>

Delete role domain.

domainsService.deleteRole({
    namespace: 'auth.roles.energyweb.iam.ewc',
});

Parameters

Name	Type	Description
options	DeleteRoleOptions	object containing options

Returns

Promise<void>

---

getAllowedRolesByIssuer

▸ getAllowedRolesByIssuer(did): Promise<IRole[]>

Get all roles that a DID can issue.

domainsService.getAllowedRolesByIssuer('did:ethr:0x00...0');

Parameters

Name	Type	Description
did	string	issuer DID

Returns

Promise<IRole[]>

array of roles that the DID can issue

---

getAllowedRolesByRevoker

▸ getAllowedRolesByRevoker(did): Promise<IRole[]>

Get all roles that a DID can revoke.

domainsService.getAllowedRolesByRevoker('did:ethr:0x00...0');

Parameters

Name	Type	Description
did	string	issuer DID

Returns

Promise<IRole[]>

array of roles that the DID can issue

---

getAppsOfOrg

▸ getAppsOfOrg(org): Promise<IApp[]>

Fetch all applications for organization namespace.

domainsService.getAppsOfOrg('energyweb.iam.ewc');

Parameters

Name	Type	Description
org	string	organization namespace

Returns

Promise<IApp[]>

array of applications

---

getDIDsByRole

▸ getDIDsByRole(role): Promise<string[]>

Get users did which have certain role.

domainsService.getDIDsByRole('auth.roles.energyweb.iam.ewc');

Parameters

Name	Type	Description
role	string	role namespace

Returns

Promise<string[]>

array of users DID

---

getDefinition

▸ getDefinition(options): Promise<IRoleDefinition | IRoleDefinitionV2 | IOrganizationDefinition | IAppDefinition>

Fetch cached domain definition for organization, application or role.

domainsService.getDefinition({
    type: NamespaceType.Role,
    namespace: 'auth.roles.energyweb.iam.ewc',
});

Parameters

Name	Type	Description
options	GetDefinitionOptions	object containing options

Returns

Promise<IRoleDefinition | IRoleDefinitionV2 | IOrganizationDefinition | IAppDefinition>

domain definition

---

getENSTypesByOwner

▸ getENSTypesByOwner(options): Promise<IApp[] | IRole[] | IOrganization[]>

Get all organization/application/role for certain owner.

domainsService.getENSTypesByOwner({
    type: NamespaceType.Organization,
    owner: '0x00...0',
    withRelations: true,
});

Parameters

Name	Type	Description
options	GetENSTypesByOwnerOptions	object containing options

Returns

Promise<IApp[] | IRole[] | IOrganization[]>

array of organizations/applications/roles for certain owner

---

getENSTypesBySearchPhrase

▸ getENSTypesBySearchPhrase(search, types?): Promise<(IRole | IOrganization | IApp)[]>

Search for organization/application/role with a given search phrase.

domainsService.getENSTypesBySearchPhrase({
    types: [SearchType.App, SearchType.Org, SearchType.Role],
    search: 'energyweb',
});

Parameters

Name	Type	Description
search	string	search phrase
types?	SearchType[]	ENS types to search

Returns

Promise<(IRole | IOrganization | IApp)[]>

array of founded organizations/applications/roles

---

getOrgHierarchy

▸ getOrgHierarchy(namespace): Promise<IOrganization>

Get organization hierarchy. Max 20 levels deep.

domainsService.getOrgHierarchy('energyweb.iam.ewc');

Parameters

Name	Type	Description
namespace	string	organization namespace

Returns

Promise<IOrganization>

organization with all nested sub-organizations

---

getRolesByNamespace

▸ getRolesByNamespace(options): Promise<IRole[]>

Fetch all roles subdomains for certain domain.

domainsService.getRolesByNamespace({
    parentType: NamespaceType.Application,
    namespace: 'auth.apps.energyweb.iam.ewc',
});

Parameters

Name	Type	Description
options	GetRolesByNamespaceOptions	object containing options

Returns

Promise<IRole[]>

array of role subdomains

---

getSubOrgsByOrgNamespace

▸ getSubOrgsByOrgNamespace(namespace): Promise<IOrganization[]>

Fetch all sub-organizations for organization namespace.

domainsService.getSubOrgsByOrgNamespace('energyweb.iam.ewc');

Parameters

Name	Type	Description
namespace	string	organization namespace

Returns

Promise<IOrganization[]>

array of sub-organizations

---

getSubdomains

▸ getSubdomains(options): Promise<string[]>

Fetch subdomains for certain domain.

domainsService.getSubdomains({
    domain: 'energyweb.iam.ewc',
    mode: 'ALL',
});

Parameters

Name	Type	Description
options	GetSubdomainsOptions	object containing options

Returns

Promise<string[]>

array of subdomains

---

init

▸ init(): Promise<void>

Returns

Promise<void>

---

isOwner

▸ isOwner(options): Promise<boolean>

Check if user is owner of the domain.

domainsService.isOwner({
    domain: 'energyweb.iam.ewc',
    user: '0x00...0',
});

Parameters

Name	Type	Description
options	IsOwnerOptions	object containing options

Returns

Promise<boolean>

true if user is owner, false otherwise

---

namespacesWithRelations

▸ namespacesWithRelations(namespaces): Promise<{ namespace: string ; owner: string }[]>

Collect related data for given domain. Currently only related data is owner.

domainsService.namespacesWithRelations(['root.roles.energyweb.iam.ewc', 'admin.roles.energyweb.iam.ewc']);

@param {Array<String>} namespaces array of namespaces
@return object containing registration types for given roles as keys

#### Parameters

| Name | Type |
| :------ | :------ |
| `namespaces` | `string`[] |

#### Returns

`Promise`<{ `namespace`: `string` ; `owner`: `string`  }[]\>

___

### readName

▸ **readName**(`namehashToRead`): `Promise`<`string`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `namehashToRead` | `string` |

#### Returns

`Promise`<`string`\>

___

### registrationTypesOfRoles

▸ **registrationTypesOfRoles**(`roles`): `Promise`<`Record`<`string`, `Set`<[`RegistrationTypes`](../enums/modules_claims.RegistrationTypes.md)\>\>\>

Get possible registration types for given roles.

```typescript
domainsService.registrationTypesOfRoles(['root.roles.energyweb.iam.ewc', 'admin.roles.energyweb.iam.ewc']);

@param {Array<String>} roles array of roles
@return object containing registration types for given roles as keys

#### Parameters

| Name | Type |
| :------ | :------ |
| `roles` | `string`[] |

#### Returns

`Promise`<`Record`<`string`, `Set`<[`RegistrationTypes`](../enums/modules_claims.RegistrationTypes.md)\>\>\>

___

### setRoleDefinition

▸ **setRoleDefinition**(`options`): `Promise`<`void`\>

Update ENS domain definition for already created domain.

```typescript
domainsService.setRoleDefinition({
    name: 'auth.apps.energyweb.iam.ewc',
    data: {
        appName: 'Auth service',
    }
});

Parameters

Name	Type	Description
options	SetRoleDefinitionOptions	object containing options

Returns

Promise<void>

---

updateLegacyDefinition

▸ updateLegacyDefinition(domain, data): Promise<boolean>

Move domain to latest version of resolver.

In initial version, role definitions where contained in ENS PublicResolver. However, in order for key properties of role definitions to be readable on-chain, a new RoleDefinitionResolver is used. This function sets the resolver in the ENS to the new contract for definitions that are pointing to the old contract.

domainsService.updateLegacyDefinition({
    namespace: 'energyweb.iam.ewc',
    data: {
         orgName: 'Energy Web Foundation',
    },
});

@param {String} domain domain namespace to update
@param {DomainDefinition} data definition to apply to domain
@return true if domain was updated, false otherwise

#### Parameters

| Name | Type |
| :------ | :------ |
| `domain` | `string` |
| `data` | [`DomainDefinition`](../modules/modules_domains.md#domaindefinition) |

#### Returns

`Promise`<`boolean`\>

___

### validateOwnership

▸ **validateOwnership**(`options`): `Promise`<`string`[]\>

Get not owned domains in given namespace for current user.

```typescript
domainsService.validateOwnership({
    namespace: 'energyweb.iam.ewc',
    type: NamespaceType.Organization,
});

Parameters

Name	Type	Description
options	ValidateOwnershipOptions	object containing options

Returns

Promise<string[]>

array of not owned domains

---

create

▸ Static create(signerService, cacheClient): Promise<DomainsService>

Parameters

Name	Type
signerService	SignerService
cacheClient	CacheClient

Returns

Promise<DomainsService>