From 3e5bb47cfb891132f5ea043d51c85c55ad4caa88 Mon Sep 17 00:00:00 2001 From: Antonio Antonino Date: Tue, 23 Jan 2024 16:21:52 +0100 Subject: [PATCH 1/3] Address TSDoc warnings --- package.json | 4 +-- src/sibling.ts | 42 +++++++++++------------ src/utils.ts | 83 ++++++++++++++++++++++++---------------------- tsconfig.docs.json | 12 +++++-- yarn.lock | 44 +++++++++++++++++------- 5 files changed, 108 insertions(+), 77 deletions(-) diff --git a/package.json b/package.json index 4dbbee6..b30f7d3 100644 --- a/package.json +++ b/package.json @@ -21,8 +21,8 @@ "eslint-plugin-license-header": "^0.6.0", "prettier": "^3.0.0", "rimraf": "^5.0.1", - "typedoc": "^0.24.8", - "typescript": "^5.3.2", + "typedoc": "^0.25.7", + "typescript": "^5.1", "vitest": "^0.33.0" }, "engines": { diff --git a/src/sibling.ts b/src/sibling.ts index 48ce99a..ac583dc 100644 --- a/src/sibling.ts +++ b/src/sibling.ts @@ -29,52 +29,52 @@ import type { import type { KeyringPair } from "@polkadot/keyring/types" import type { Call, Hash } from "@polkadot/types/interfaces" +/** The DIP proof params. */ export type DipSiblingProofInput = { + /** The `Call` on the consumer chain that requires a DIP origin. */ call: Call + /** The `ApiPromise` instance for the consumer chain. */ consumerApi: ApiPromise + /** The DID URI of the DIP subject that is performing the cross-chain operation. */ didUri: DidUri + /** The verification method IDs of the DID to be revealed in the cross-chain operation. */ keyIds: Array + /** The version of the DIP proof to generate. */ proofVersion: number + /** The `ApiPromise` instance for the provider chain. */ providerApi: ApiPromise + /** The `ApiPromise` instance for the parent relay chain. */ relayApi: ApiPromise + /** The signing callback to sign the cross-chain transaction. */ signer: SignExtrinsicCallback + /** The address of the tx submitter on the consumer chain. */ submitterAddress: KeyringPair["address"] + /** The `VerificationKeyRelationship` required for the DIP operation to be authorized on the relay chain. */ keyRelationship: VerificationKeyRelationship - // Optional, retrieved from chain otherwise + /** The block number on the consumer chain to use for the DID signature. If not provided, the latest best block number is used. */ blockHeight?: BN + /** The genesis hash of the consumer chain to use for the DID signature. If not provided, it is retrieved at runtime from the consumer chain. */ genesisHash?: Hash + /** The block number of the provider to use for the generation of the DIP proof. If not provided, the latest finalized block number is used. */ providerBlockHeight?: BN - // With defaults + /** The runtime type definition for an `AccountId` on the consumer chain. If not provided, the `AccountId` type is used. */ accountIdRuntimeType?: string + /** The runtime type definition for a `BlockNumber` on the consumer chain. If not provided, the `u64` type is used. */ blockNumberRuntimeType?: string + /** The runtime type definition for the `IdentityDetails` on the consumer chain. If not provided, the `Option` type, representing a simple nonce, is used. */ identityDetailsRuntimeType?: string + /** Flag indicating whether the generated DIP proof should include the web3name of the DID subject. If not provided, the web3name is not revealed. */ includeWeb3Name?: boolean + /** The list of linked accounts to reveal in the generated DIP proof. If not provided, no account is revealed. */ linkedAccounts?: readonly PalletDidLookupLinkableAccountLinkableAccountId[] } /** * Generate a submittable extrinsic for the provided call which includes a complete DIP proof according to the parameters provided, to be used on a consumer chain of which the provider chain is a sibling. + * * @param params The DIP proof params. - * @param params.call The [[Call]] on the consumer chain that requires a DIP origin. - * @param params.consumerApi The [[ApiPromise]] instance for the consumer chain. - * @param params.didUri The DID URI of the DIP subject that is performing the cross-chain operation. - * @param params.keyIds The verification method IDs of the DID to be revealed in the cross-chain operation. - * @param params.proofVersion The version of the DIP proof to generate. - * @param params.providerApi The [[ApiPromise]] instance for the provider chain. - * @param params.relayApi The [[ApiPromise]] instance for the parent relay chain. - * @param params.signer The signing callback to sign the cross-chain transaction. - * @param params.submitterAddress The address of the tx submitter on the consumer chain. - * @param params.keyRelationship The [[VerificationKeyRelationship]] required for the DIP operation to be authorized on the relay chain. - * @param params.blockHeight [OPTIONAL] The block number on the consumer chain to use for the DID signature. If not provided, the latest best block number is used. - * @param params.genesisHash [OPTIONAL] The genesis hash of the consumer chain to use for the DID signature. If not provided, it is retrieved at runtime from the consumer chain. - * @param params.providerBlockHeight [OPTIONAL] The block number of the provider to use for the generation of the DIP proof. If not provided, the latest finalized block number is used. - * @param params.accountIdRuntimeType [OPTIONAL] The runtime type definition for an `AccountId` on the consumer chain. If not provided, the `AccountId` type is used. - * @param params.blockNumberRuntimeType [OPTIONAL] The runtime type definition for a `BlockNumber` on the consumer chain. If not provided, the `u64` type is used. - * @param params.identityDetailsRuntimeType [OPTIONAL] The runtime type definition for the `IdentityDetails` on the consumer chain. If not provided, the `Option` type, representing a simple nonce, is used. - * @param params.includeWeb3Name [OPTIONAL] Flag indicating whether the generated DIP proof should include the web3name of the DID subject. If not provided, the web3name is not revealed. - * @param params.linkedAccounts [OPTIONAL] The list of linked accounts to reveal in the generated DIP proof. If not provided, no account is revealed. * - * @returns The [[SubmittableExtrinsic]] containing the signed cross-chain operation, that must be submitted by the account specified as the `submitterAddress` parameter. + * @returns The `SubmittableExtrinsic` containing the signed cross-chain operation, that must be submitted by the account specified as the `submitterAddress` parameter. */ export async function generateDipAuthorizedTxForSibling({ call, diff --git a/src/utils.ts b/src/utils.ts index 05708cd..af2b270 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -33,27 +33,29 @@ export const defaultValues = { /** * The options object provided when generating a Provider state proof. */ -type ProviderStateRootProofOpts = { +export type ProviderStateRootProofOpts = { + /** The `ApiPromise` instance for the provider chain. */ providerApi: ApiPromise + /** The `ApiPromise` instance for the relay chain. */ relayApi: ApiPromise - // Optional + /** The block number on the provider chain to use for the state proof. If not provided, the latest finalized block number is used. */ providerBlockHeight?: BN } /** * The response object containing the provider state root proof. */ -type ProviderStateRootProofRes = { +export type ProviderStateRootProofRes = { + /** The state proof for the provider header. */ proof: ReadProof + /** The block number of the provider which the proof is anchored to. */ providerBlockHeight: BN + /** The block number of the relaychain which the proof is anchored to. */ relayBlockHeight: BN } /** * Generate a state proof that proofs the head of the specified parachain. * * @param params The state proof params. - * @param params.providerApi The [[ApiPromise]] instance for the provider chain. - * @param params.relayApi The [[ApiPromise]] instance for the relay chain. - * @param params.providerBlockHeight [OPTIONAL] The block number on the provider chain to use for the state proof. If not provided, the latest finalized block number is used. * * @returns The generated state proof. */ @@ -101,26 +103,27 @@ export async function generateProviderStateRootProof({ /** * The options object provided when generating a DIP commitment proof. */ -type DipCommitmentProofOpts = { +export type DipCommitmentProofOpts = { + /** The `DidUri` of the subject. */ didUri: DidUri + /** The `ApiPromise` instance for the provider chain. */ providerApi: ApiPromise + /** The block hash on the provider chain to use for the state proof. */ providerBlockHash: Hash + /** The version of the identity commitment to generate the state proof for. */ version: number } /** * The response object for a DIP commitment proof. */ -type DipCommitmentProofRes = { +export type DipCommitmentProofRes = { + /** The storage proof for the DIP commitment value. */ proof: ReadProof } /** * Generate a state proof that proofs the value of an identity commitment on the specified provider chain. * * @param params The state proof params. - * @param params.did The [[Did]] of the subject. - * @param params.providerApi The [[ApiPromise]] instance for the provider chain. - * @param params.providerBlockHash The block hash on the provider chain to use for the state proof. - * @param params.version The version of the identity commitment to generate the state proof for. * * @returns The generated state proof. */ @@ -146,34 +149,38 @@ export async function generateDipCommitmentProof({ /** * The options object provided when generating a DIP identity proof. */ -type DipIdentityProofOpts = { +export type DipIdentityProofOpts = { + /** The `Did` of the subject. */ didUri: DidUri + /** The list of DID verification methods to include in the DIP proof and to reveal to the consumer chain. */ keyIds: Array + /** A flag indicating whether the web3name should be included in the DIP proof. */ includeWeb3Name: boolean + /** The list of accounts linked to the DID ot include in the DIP proof and to reveal to the consumer chain. */ linkedAccounts: readonly PalletDidLookupLinkableAccountLinkableAccountId[] + /** The `ApiPromise` instance for the provider chain. */ providerApi: ApiPromise + /** The version of the DIP proof to generate. */ version: number } /** * The response object for a generated DIP proof. */ -type DipIdentityProofRes = { +export type DipIdentityProofRes = { + /** The generated storage proof. */ proof: { + /** The Merkle proof blinded (not revealed) leaves. */ blinded: Codec + /** The Merkle proof revealed leaves. */ revealed: Codec } + /** The Merkle root hash which the proof is anchored to. */ root: Hash } /** * Generate a DIP proof that reveals the specified information about the DID subject. * * @param params The DIP proof params. - * @param params.did The [[Did]] of the subject. - * @param params.keyIds The list of DID verification methods to include in the DIP proof and to reveal to the consumer chain. - * @param params.includeWeb3Name A flag indicating whether the web3name should be included in the DIP proof. - * @param params.linkedAccounts The list of accounts linked to the DID ot include in the DIP proof and to reveal to the consumer chain. - * @param params.providerApi The [[ApiPromise]] instance for the provider chain. - * @param params.version The version of the DIP proof to generate. * * @returns The generated DIP proof. */ @@ -208,36 +215,46 @@ export async function generateDipIdentityProof({ /** * The Provider options object provided when generating a DIP DID signature. */ -type DipDidSignatureProviderOpts = { +export type DipDidSignatureProviderOpts = { + /** The `DidUri` of the DIP subject that is performing the cross-chain operation. */ didUri: DidUri + /** The list of `Signers` to use to sign the cross-chain payload. */ signer: SignExtrinsicCallback + /** The `SignatureVerificationRelationship` to use from the provided DID Document to sign the cross-chain payload. */ keyRelationship: VerificationKeyRelationship } /** * The Consumer options object provided when generating a DIP DID signature. */ -type DipDidSignatureConsumerOpts = { +export type DipDidSignatureConsumerOpts = { + /** The runtime definition of an `AccountId`. */ accountIdRuntimeType: string + /** The `ApiPromise` instance. */ api: ApiPromise + /** The runtime definition of a `BlockNumber`. */ blockNumberRuntimeType: string + /** The `Call` to DID-authorize. */ call: Call + /** The runtime definition of the `IdentityDetails`. */ identityDetailsRuntimeType: string + /** The address of the submitter account on the consumer chain. */ submitterAddress: KeyringPair["address"] - // Optional + /** The block number to use for the DID signature. If not provided, the latest best block number is used. */ blockHeight?: BN + /** The genesis hash to use for the DID signature. If not provided, it is retrieved at runtime. */ genesisHash?: Hash } /** * The options object provided when generating a DIP DID signature. */ -type DipDidSignatureOpts = { +export type DipDidSignatureOpts = { consumer: DipDidSignatureConsumerOpts provider: DipDidSignatureProviderOpts } /** * The response object for DIP DID signature. */ -type DipDidSignatureRes = { +export type DipDidSignatureRes = { blockNumber: BN signature: Uint8Array type: VerificationKeyType @@ -245,20 +262,8 @@ type DipDidSignatureRes = { /** * Generate a DID signature to be used in conjunction with a DIP proof to DID-authorize a cross-chain operation. * - * @param params The DID signature parameters. - * @param params.provider The provider-specific parameters. - * @param params.provider.didDocument The [[DidDocument] of the DIP subject that is performing the cross-chain operation. - * @param params.provider.signers The list of [[Signers]] to use to sign the cross-chain payload. - * @param params.provider.verificationRelationship The [[SignatureVerificationRelationship]] to use from the provided DID Document to sign the cross-chain payload. - * @param params.consumer The consumer-specific parameters. - * @param params.consumer.accountIdRuntimeType The runtime definition of an `AccountId`. - * @param params.consumer.api The [[ApiPromise]] instance. - * @param params.consumer.blockNumberRuntimeType The runtime definition of a `BlockNumber`. - * @param params.consumer.call The [[Call]] to DID-authorize. - * @param params.consumer.identityDetailsRuntimeType The runtime definition of the `IdentityDetails`. - * @param params.consumer.submitterAddress The address of the submitter account on the consumer chain. - * @param params.consumer.blockHeight [OPTIONAL] The block number to use for the DID signature. If not provided, the latest best block number is used. - * @param params.consumer.genesisHash [OPTIONAL] The genesis hash to use for the DID signature. If not provided, it is retrieved at runtime. + * @param params The signature generation parameters. + * @returns The generated DIP proof. */ export async function generateDipDidSignature({ diff --git a/tsconfig.docs.json b/tsconfig.docs.json index a2fbafb..1883fba 100644 --- a/tsconfig.docs.json +++ b/tsconfig.docs.json @@ -1,9 +1,15 @@ { "extends": "./tsconfig.json", - "include": ["src/**/*"], + "include": [ + "src/**/*" + ], "typedocOptions": { "entryPointStrategy": "resolve", - "entryPoints": ["src/runtime.ts", "src/sibling.ts", "src/utils.ts"], + "entryPoints": [ + "src/runtime.ts", + "src/sibling.ts", + "src/utils.ts" + ], "out": "docs/api", "theme": "default", "exclude": [ @@ -19,4 +25,4 @@ "name": "API Documentation", "readme": "README.md" } -} +} \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index dec0071..e657198 100644 --- a/yarn.lock +++ b/yarn.lock @@ -399,8 +399,8 @@ __metadata: eslint-plugin-license-header: ^0.6.0 prettier: ^3.0.0 rimraf: ^5.0.1 - typedoc: ^0.24.8 - typescript: ^5.3.2 + typedoc: ^0.25.7 + typescript: ^5.1 vitest: ^0.33.0 languageName: unknown linkType: soft @@ -3745,7 +3745,7 @@ __metadata: languageName: node linkType: hard -"minimatch@npm:^9.0.0, minimatch@npm:^9.0.1, minimatch@npm:^9.0.3": +"minimatch@npm:^9.0.1, minimatch@npm:^9.0.3": version: 9.0.3 resolution: "minimatch@npm:9.0.3" dependencies: @@ -4762,7 +4762,7 @@ __metadata: languageName: node linkType: hard -"shiki@npm:^0.14.1": +"shiki@npm:^0.14.7": version: 0.14.7 resolution: "shiki@npm:0.14.7" dependencies: @@ -5322,19 +5322,19 @@ __metadata: languageName: node linkType: hard -"typedoc@npm:^0.24.8": - version: 0.24.8 - resolution: "typedoc@npm:0.24.8" +"typedoc@npm:^0.25.7": + version: 0.25.7 + resolution: "typedoc@npm:0.25.7" dependencies: lunr: ^2.3.9 marked: ^4.3.0 - minimatch: ^9.0.0 - shiki: ^0.14.1 + minimatch: ^9.0.3 + shiki: ^0.14.7 peerDependencies: - typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x bin: typedoc: bin/typedoc - checksum: a46a14497f789fb3594e6c3af2e45276934ac46df40b7ed15a504ee51dc7a8013a2ffb3a54fd73abca6a2b71f97d3ec9ad356fa9aa81d29743e4645a965a2ae0 + checksum: 49c3bf923a3c9401b549e5843f8efaaac8fa28f8ec6bd8617187b5d9ba9932a3fa63dc3863b82389507ffc7d92908af0dce33780fffb4970cd0833274f6fa0cf languageName: node linkType: hard @@ -5347,6 +5347,16 @@ __metadata: languageName: node linkType: hard +"typescript@npm:^5.1": + version: 5.3.3 + resolution: "typescript@npm:5.3.3" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: 2007ccb6e51bbbf6fde0a78099efe04dc1c3dfbdff04ca3b6a8bc717991862b39fd6126c0c3ebf2d2d98ac5e960bcaa873826bb2bb241f14277034148f41f6a2 + languageName: node + linkType: hard + "typescript@npm:^5.3.2": version: 5.3.2 resolution: "typescript@npm:5.3.2" @@ -5357,9 +5367,19 @@ __metadata: languageName: node linkType: hard +"typescript@patch:typescript@^5.1#~builtin": + version: 5.3.3 + resolution: "typescript@patch:typescript@npm%3A5.3.3#~builtin::version=5.3.3&hash=5da071" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: f61375590b3162599f0f0d5b8737877ac0a7bc52761dbb585d67e7b8753a3a4c42d9a554c4cc929f591ffcf3a2b0602f65ae3ce74714fd5652623a816862b610 + languageName: node + linkType: hard + "typescript@patch:typescript@^5.3.2#~builtin": version: 5.3.2 - resolution: "typescript@patch:typescript@npm%3A5.3.2#~builtin::version=5.3.2&hash=14eedb" + resolution: "typescript@patch:typescript@npm%3A5.3.2#~builtin::version=5.3.2&hash=5da071" bin: tsc: bin/tsc tsserver: bin/tsserver From 0e08339a989f7e595a3d767ffc3ef84d1ee69242 Mon Sep 17 00:00:00 2001 From: Antonio Antonino Date: Tue, 23 Jan 2024 16:23:47 +0100 Subject: [PATCH 2/3] Lint fixes --- src/sibling.ts | 2 +- tsconfig.docs.json | 12 +++--------- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/src/sibling.ts b/src/sibling.ts index ac583dc..6f4072e 100644 --- a/src/sibling.ts +++ b/src/sibling.ts @@ -71,7 +71,7 @@ export type DipSiblingProofInput = { /** * Generate a submittable extrinsic for the provided call which includes a complete DIP proof according to the parameters provided, to be used on a consumer chain of which the provider chain is a sibling. - * + * * @param params The DIP proof params. * * @returns The `SubmittableExtrinsic` containing the signed cross-chain operation, that must be submitted by the account specified as the `submitterAddress` parameter. diff --git a/tsconfig.docs.json b/tsconfig.docs.json index 1883fba..a2fbafb 100644 --- a/tsconfig.docs.json +++ b/tsconfig.docs.json @@ -1,15 +1,9 @@ { "extends": "./tsconfig.json", - "include": [ - "src/**/*" - ], + "include": ["src/**/*"], "typedocOptions": { "entryPointStrategy": "resolve", - "entryPoints": [ - "src/runtime.ts", - "src/sibling.ts", - "src/utils.ts" - ], + "entryPoints": ["src/runtime.ts", "src/sibling.ts", "src/utils.ts"], "out": "docs/api", "theme": "default", "exclude": [ @@ -25,4 +19,4 @@ "name": "API Documentation", "readme": "README.md" } -} \ No newline at end of file +} From 6c0a88131ad53ad0a8773c9f7ccd933dd3f79ad7 Mon Sep 17 00:00:00 2001 From: Antonio Antonino Date: Tue, 23 Jan 2024 16:26:42 +0100 Subject: [PATCH 3/3] Revert yarn lock changes --- yarn.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/yarn.lock b/yarn.lock index e657198..d454069 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5369,7 +5369,7 @@ __metadata: "typescript@patch:typescript@^5.1#~builtin": version: 5.3.3 - resolution: "typescript@patch:typescript@npm%3A5.3.3#~builtin::version=5.3.3&hash=5da071" + resolution: "typescript@patch:typescript@npm%3A5.3.3#~builtin::version=5.3.3&hash=14eedb" bin: tsc: bin/tsc tsserver: bin/tsserver @@ -5379,7 +5379,7 @@ __metadata: "typescript@patch:typescript@^5.3.2#~builtin": version: 5.3.2 - resolution: "typescript@patch:typescript@npm%3A5.3.2#~builtin::version=5.3.2&hash=5da071" + resolution: "typescript@patch:typescript@npm%3A5.3.2#~builtin::version=5.3.2&hash=14eedb" bin: tsc: bin/tsc tsserver: bin/tsserver