Claims¶
Class Name | Claims |
---|---|
Extends | Logger |
Source | claims.ts |
Tests | claims.spec.ts |
The Claims
module allows to
- issue claims about oneself or about other parties
- confirm or delete claims about oneself
Claims have a pattern similar to file paths, a claim for an account called “foo” being an employee of a company called “bar” may look like this:
/company/bar/employee
Under this “path” a set of values can be found. These value describe the claim, the subject of the claim and optional its response to it. Basically an issuer
creates a claim
about a subject
The values are:
claim (name)
full path to a claim, for example/company/bar/employee/foo
, settable by thesubject
of the parent claim/company/bar/employee
subject
an account, a claim has been issued for, can be a group/wallet or an externally owned account being thesubject
of aclaim
basically means to be the owner of the claim and allows to create subclaims below the own claim pathissuer
an account (group/wallet or externally owned) that creates a claim, to be able to issue a claim, theissuer
has to be thesubject
of the parent claim/company/bar/employee
data
The hash of the claim data, sitting in another location, a bit-mask, call data, or actual data based on the claim scheme.uri
The location of the claim, this can be HTTP links, swarm hashes, IPFS hashes, and such.status
this represents aclaims
status, values areuint8
range from 0 to 255, the currently used values are: - 0: Issued - 1: Confirmedsignature
Signature which is the proof that the claim issuer issued a claim of topic for this identity. It MUST be a signed message of the following structure: keccak256(address identityHolder_address, uint256 _ topic, bytes data)creationDate
creationDate of the claimid
id of the current claimvalid
check if the claim has a valid signature
constructor¶
new Claims(options);
Creates a new Claims instance.
Note, that the option properties registry
and resolver
are optional but should be provided
in most cases. As the module allows to create an own ENS structure, that includes an own ENS
registry and an own default resolver for it, setting them beforehand is optional.
Parameters¶
options
-ClaimsOptions
: options for Claims constructor.accountStore
-AccountStore
:AccountStore
instanceconfig
-any
: config object withNameResolver
configcontractLoader
-ContractLoader
:ContractLoader
instancedescription
-Description
:Description
instancedfs
-DfsInterface
:DfsInterface
instanceexecutor
-Executor
:Executor
instancenameResolver
-NameResolver
:NameResolver
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
storage
-string
(optional): contract address of the identity storage registry
Returns¶
Claims
instance
Example¶
const claims = new Claims({
accountStore,
config,
contractLoader,
description,
dfs,
executor,
nameResolver,
storage: '0x0000000000000000000000000000000000000001',
});
= Issuers =¶
createIdentity¶
claims.createIdentity(accountId[, contractId]);
Creates a new identity for account or contract and registers them on the storage. Returned identity is either a 40B contract address (for account identities) or a 32B idenity hash contract identities.
Parameters¶
accountId
-string
: the account identifier
Returns¶
Promise
returns void
: resolved when done
Example¶
const identity = await claims.createIdentity(accounts[0]);
identityAvailable¶
claims.identityAvailable(subject);
Checks if a account has already an identity contract.
Parameters¶
subject
-string
: target subject to check
Returns¶
Promise
returns boolean
: true if identity exists, otherwise false
Example¶
console.log(await claims.identityAvailable(accounts[0]);
// Output:
// false
await await claims.createIdentity(accounts[0]);
console.log(await claims.identityAvailable(accounts[0]);
// Output:
// true
getIdentityForAccount¶
claims.getIdentityForAccount(subject);
Gets the identity contract for a given account id or contract.
Parameters¶
subject
-string
: target subject to get identity for
Returns¶
Promise
returns any
: identity contract instance
setClaim¶
claims.setClaim(issuer, subject, claimName[, expirationDate, claimValue, descriptionDomain]);
Sets or creates a claim; this requires the issuer to have permissions for the parent claim (if claim name seen as a path, the parent ‘folder’).
Parameters¶
issuer
-string
: issuer of the claimsubject
-string
: subject of the claim and the owner of the claim nodeclaimName
-string
: name of the claim (full path)expirationDate
-number
(optional): expiration date, for the claim, defaults to0
(does not expire)claimValue
-string
(optional): bytes32 hash of the claims value, will not be set if omitteddescriptionDomain
-string
(optional): domain of the claim, this is a subdomain under ‘claims.evan’, so passing ‘example’ will link claims description to ‘example.claims.evan’, unset if omitted
Returns¶
Promise
returns string
: id of new claim
Example¶
// accounts[0] issues claim '/company' for accounts[1]
const firstClaim = await claims.setClaim(accounts[0], accounts[1], '/company');
// accounts[0] issues claim '/company' for accounts[1], sets an expiration date
// and links to description domain 'sample'
const secondClaim = await claims.setClaim(
accounts[0], accounts[1], '/company', expirationDate, claimValue, 'example');
getClaims¶
claims.getClaims(subject, claimName[, isIdentity]);
Gets claim information for a claim name from a given account; results has the following properties: creationBlock, creationDate, data, description, expirationDate, id, issuer, name, signature, status, subject, topic, uri, valid.
Parameters¶
subject
-string
: subject of the claimsclaimName
-string
: name (/path) of a claimisIdentity
-string
(optional): indicates if the subject is already an identity
Returns¶
Promise
returns any[]
: claim info array, contains: issuer, name, status, subject, data, uri, signature, creationDate
Example¶
await claims.setClaim(accounts[0], accounts[1], '/company');
console.dir(await claims.getClaims(accounts[1], '/company'));
// Output:
[{
creationDate: 1234567890,
data: '0x0000000000000000000000000000000000000000000000000000000000000000',
description: {
name: 'sample claim',
description: 'I\'m a sample claim',
author: 'evan.network',
version: '1.0.0',
dbcpVersion: 1,
},
expirationDate: 1234567890,
id: '0x0000000000000000000000000000000000000000000000000000000000000000',
issuer: '0x0000000000000000000000000000000000000001',
name: '/company',
rejectReason: {
"rejected": "rejection message"
},
signature: '0x0000000000000000000000000000000000000000000000000000000000000000',
status: 0 (Issued) || 1 (Confirmed) || 2 (Rejected),
subject: '0x0000000000000000000000000000000000000002',
uri: '',
signature: '0x0000000000000000000000000000000000000000000000000000000000000000',
valid: true
}]
identityAvailable¶
claims.identityAvailable(subject);
checks if a account has already a identity contract
Parameters¶
subject
-string
: subject of the claims
Returns¶
Promise
returns any
: true if identity exists, otherwise false
validateClaim¶
claims.validateClaim(subject, claimId[, isIdentity]);
validates a given claimId in case of integrity
Parameters¶
subject
-string
: subject of the claimsclaimId
-string
: The claim identifierisIdentity
-boolean
(optional): indicates if the subject is already an identity, defaults tofalse
Returns¶
Promise
returns boolean
: resolves with true if the claim is valid, otherwise false
Example¶
console.dir(await claims.validateClaim(
accounts[1]),
'0x0000000000000000000000000000000000000000000000000000000000000000',
);
// Output:
true
validateClaimTree¶
claims.validateClaimTree(subject, claimLabel, treeArr);
validates a whole claim tree if the path is valid (called recursively)
Parameters¶
subject
-string
: subject of the claimsclaimLabel
-string
: claim topic of a claim to build the tree fortreeArr
-array
(optional): result tree array, used for recursion, defaults to[]
Returns¶
Promise
returns any[]
: Array with all resolved claims for the tree
Example¶
console.dir(await claims.validateClaimTree(accounts[1], '/company/test/foo'));
// Output:
[{ issuer: '0x0000000000000000000000000000000000000001',
name: '/company/test/foo',
status: 1
subject: '0x0000000000000000000000000000000000000002',
data: '0x0000000000000000000000000000000000000000000000000000000000000000',
uri: '',
signature: '0x0000000000000000000000000000000000000000000000000000000000000000',
creationDate: 1234567890,
id: '0x0000000000000000000000000000000000000000000000000000000000000000',
valid: true },
{ issuer: '0x0000000000000000000000000000000000000001',
name: '/company/test',
status: 1
subject: '0x0000000000000000000000000000000000000002',
data: '0x0000000000000000000000000000000000000000000000000000000000000000',
uri: '',
signature: '0x0000000000000000000000000000000000000000000000000000000000000000',
creationDate: 1234567890,
id: '0x0000000000000000000000000000000000000000000000000000000000000000',
valid: true }]
deleteClaim¶
claims.deleteClaim(accountId, subject, claimId);
Delete a claim. This requires the accountId to have permissions for the parent claim (if claim name seen as a path, the parent ‘folder’). Subjects of a claim may only delete it, if they are the issuer as well. If not, they can only react to it by confirming or rejecting the claim.
Parameters¶
accountid
-string
: account, that performs the actionsubject
-string
: the subject of the claimclaimId
-string
: id of a claim to delete
Returns¶
Promise
returns void
: resolved when done
Example¶
const claimId = await claims.setClaim(accounts[0], accounts[1], '/company');
await claims.deleteClaim(accounts[0], accounts[1], claimId);
rejectClaim¶
claims.rejectClaim(accountId, subject, claimId, rejectReason?);
Reject a Claim. This claim will be marked as rejected but not deleted. This is important for tracking reasons. You can also optionally add a reject reason as JSON object to track additional informations about the rejection. Issuer and Subject can reject a special claim.
Parameters¶
accountid
-string
: account, that performs the actionsubject
-string
: the subject of the claimclaimId
-string
: id of a claim to deleterejectReason
-object
(optional): JSON Object of the rejection reason
Returns¶
Promise
returns void
: resolved when done
Example¶
const claimId = await claims.setClaim(accounts[0], accounts[1], '/company');
await claims.rejectClaim(accounts[0], accounts[1], claimId, { rejected: "because not valid anymore"});
= Subjects =¶
confirmClaim¶
claims.confirmClaim(accountId, subject, claimId);
Confirms a claim; this can be done, if a claim has been issued for a subject and the subject wants to confirms it.
Parameters¶
accountId
-string
: account, that performs the actionsubject
-string
: claim subjectclaimId
-string
: id of a claim to confirm
Returns¶
Promise
returns void
: resolved when done
Example¶
const newClaim = await claims.setClaim(accounts[0], accounts[1], '/company');
await claims.confirmClaim(accounts[0], accounts[1], newClaim);
= Descriptions =¶
setClaimDescription¶
claims.setClaimDescription(accountId, topic, domain, description);
Set description for a claim under a domain owned by given account. This sets the description at the ENS endpoint for a claim.
Notice, that this will not insert a description at the claim itself. Consider it as setting a global registry with the description for your claims and not as a label attached to a single claim.
So a setting a description for the claim /some/claim
the subdomain example
registers this at the ENS path ${sha3(‘/some/claim’)}example.claims.evan`.
When this description has been set, it can be used when setting claims, e.g. with
claims.setClaim(accounts[0], accounts[1], '/some/claim', expirationDate, claimValue, 'example');
A description can be setup even after claims have been issued. So it is recommended to use the claim domain when setting up claims, even if the description isn’t required at the moment, when claims are set up.
Parameters¶
accountId
-string
: accountId, that performs the description updatetopic
-string
: name of the claim (full path) to set descriptiondomain
-string
: domain of the claim, this is a subdomain under ‘claims.evan’, so passing ‘example’ will link claims description to ‘example.claims.evan’description
-string
: DBCP description of the claim; can be an Envelope but only public properties are used
Returns¶
Promise
returns void
: resolved when done
Example¶
const sampleClaimsDomain = 'sample';
const sampleClaimTopic = '/company';
const sampleDescription = {
name: 'sample claim',
description: 'I\'m a sample claim',
author: 'evan.network',
version: '1.0.0',
dbcpVersion: 1,
};
await claims.setClaimDescription(accounts[0], sampleClaimTopic, sampleClaimsDomain, sampleDescription);
await claims.setClaim(accounts[0], accounts[1], sampleClaimTopic, null, null, sampleClaimsDomain);
const claimsForAccount = await claims.getClaims(accounts[1], sampleClaimTopic);
const last = claimsForAccount.length - 1;
console.dir(claimsForAccount[last].description);
// Output:
// {
// name: 'sample claim',
// description: 'I\'m a sample claim',
// author: 'evan.network',
// version: '1.0.0',
// dbcpVersion: 1,
// }
= Deployment =¶
createStructure¶
claims.createStructure(accountId);
Create a new claims structure; this includes a userregistry and the associated libraries. This isn’t required for creating a module instance, its is solely used for creating new structures on the blockchain.
Parameters¶
accountId
-string
: account, that execute the transaction and owner of the new registry
Returns¶
Promise
returns any
: object with property ‘storage’, that is a web3js
contract instance
Example¶
const claimsStructure = await claims.createStructure(accountId);
console.log(claimsStructure.storage.options.address);
// Output:
// 0x000000000000000000000000000000000000000a