@tonomy/antelope-did

Contributions

The Antelope Identity Working Group is an open working group where we, the Antelope community, discuss identity on Antelope chains and progress work such as this DID specification and it's implementation. We have a weekly meeting and a Slack channel.

Comments regarding this document are welcome. Please file issues and PRs directly on Github. Contributors are recognized through adding commits to the code base.

See README.tsdx.md for instructions on how to run, build, test and test this library.

Contributors:

• Jack Tanner [e-mail]
• Caspar Roelofs [e-mail]
• Jonas Walter
• Julius Rahaus

Antelope DID

This library is intended to use Antelope accounts as fully self managed Decentralized Identifiers and wrap them in a DID Document

It supports the proposed Decentralized Identifiers spec from the W3C Credentials Community Group.

The DID specification can be found at antelope-did-spec.

DID Create

const antelopeDid = new AntelopeDID({
    chain: 'eos:testnet:jungle',
    signatureProvider: new JsSignatureProvider(['PVT_K1_27yS4sdX86VDahQRABMLCcDABH5Vzy8vgLLS7wBeKESyrXetMf'])
});
const myPermission = {
    threshold: 1,
    keys: [{
        key: 'PUB_K1_5irHomACLB3oRbkqdgYTdh1GHGt8yvzQ7no5dxvEw5eYAiUiut',
        weight: 1,
    }],
    accounts: [],
    waits: [],
};

// "didtester333" account creates a new account called "newaccount11" with the owner and active permission set to "mypermission"
// on the Jungle testnet
const didCreateResult = await antelopeDid.create('didtester333', 'newaccount11', myPermission, myPermission);

DID Resolve

const antelopeDid = new AntelopeDID();

// resolves the "didtester333" account on the Jungle testnet account to a DID Document
const didResolveResult = await antelopeDid.resolve('did:antelope:eos:testnet:jungle:didtester333');

DID Update

const antelopeDID = new AntelopeDID({
    account: 'didtester333',
    signatureProvider: new JsSignatureProvider(['PVT_K1_27yS4sdX86VDahQRABMLCcDABH5Vzy8vgLLS7wBeKESyrXetMf']),
    chain: 'eos:testnet:jungle'
});

const myNewPermission = {
    threshold: 1,
    keys: [{
        key: 'PUB_K1_5irHomACLB3oRbkqdgYTdh1GHGt8yvzQ7no5dxvEw5eYAiUiut',
        weight: 1,
    }],
    accounts: [],
    waits: [],
};

// "didtester333" changes it's "active" permission to the "myNewPermission" on the Jungle testnet
const didUpdateResult = await antelopeDID.update('didtester333', 'active', 'owner', myNewPermission);

DID Deactivate

Note: DID Deactive always throws an error as it is not supported by default on an Antelope chain. See the Antelope DID Spec for more information.

const antelopeDID = new AntelopeDID({
    account: 'didtester333',
    signatureProvider: new JsSignatureProvider(['PVT_K1_27yS4sdX86VDahQRABMLCcDABH5Vzy8vgLLS7wBeKESyrXetMf']),
    chain: 'eos:testnet:jungle'
});

// Will throw an error
await antelopeDID.deactivate('did:antelope:eos:testnet:jungle:didtester333');

Conficuration

All function calls (create, resolve, update, deactivate) can be called with an optional options argument with the following optional properties:

{
  chain?: string;
  fetch?: any;
  account?: string;
  signatureProvider?: SignatureProvider;
  accountPermission?: string;
  registry?: ChainRegistry;
  transactionOptions?: {
    blocksBehind?: number;
    expireSeconds?: number;
  };
}

chain - the chain id or the registered chain name (see the DID method schema part of the Antelope DID spec). This must be provided to know which chain to contact and a corresponding item in the antelope-did-chain-registry.json or registry property must exist e.g.
eos:testnet:jungle
telos
4667b205c6838ef70ff7988f6e8257e8be0e1284a2f59699054a018f743b1d11
fetch - fetch object used to communicate with the antelope API. If using nodejs then you need to import the node-fetch npm package and use this. See the eosjs documentation for more details.
signatureProvider - the SignatureProvider object that will be used to sign txs
accountPermission - the permission name that will be used to send txs
registry - additional ChainRegisries that are used to find the API endpoints of the antelope API. This should be used when communicating with Antelope blockchain nodes that have not been registed in the antelope-did-chain-registry.json
transactionOptions - overrides the tx options when the tx is sent. See the eosjs documentation for more details.

Create configuration

The create function can be called with the following additional optional properties:

{
  buyrambytes?: number;
  stakeNetQuantity?: string;
  stakeCpuQuantity?: string;
  transfer?: boolean;
}

buyrambytes - amount of RAM to allocate to the new account in bytes (default = 8192)
stakeNetQuantity - amout of NET to stake to the new account (default = "1.0000 EOS")
stakeCpuQuantity - amount of CPU to stake to the new account (default = "1.0000 EOS")
transfer - transfer the ownership of the staked tokens to the new account (default = false)

Error handling

All function calls (create, resolve, update, deactivate) return an object containing an errors encountered. They do not throw errors.

For example

const didResolveResult = await antelopeDid.resolve('did:antelope:invalid_did_string');
// This will NOT throw an error

console.log(didResolveResult);
/*
{
    didResolutionMetadata: { 'invalidDid' },
    didDocument: null,
    didDocumentMetadata: {},
}
*/