@iota/signing

IOTA Signing Scheme

Usage no npm install needed!

<script type="module">
  import iotaSigning from 'https://cdn.skypack.dev/@iota/signing';
</script>

README

@iota/signing

IOTA Signing Scheme

Installation

Install using npm:

npm install @iota/signing

or using yarn:

yarn add @iota/signing

API Reference

signing.subseed(seed, index)

Summary: Generates a subseed.
Throws:

  • errors.ILLEGAL_SUBSEED_INDEX : Make sure that the index argument is a number greater than 0.
Param Type Description
seed Int8Array A 243-trit seed to use to derive the subseed
index number The private key index to use to derive the subseed

This method derives a subseed from a seed and a private key index.

You can use the subseed to derive private keys and their addresses.

Note: If the given seed is less then 243 trits, 0 trits are appended to it until it is 243 trits long.

Related methods

To convert a seed from trytes to trits, use the trytesToTrits() method.

To derive a private key from the subseed, use the key() method.

Returns: Int8Array - subseed - A subseed in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Sign.subseed(Converter.trytesToTrits(seed), 0);

signing.key(subseedTrits, numberOfFragments)

Summary: Generates a private key.
Throws:

  • errors.ILLEGAL_SUBSEED_LENGTH : Make sure that the subseedTrits argument contains 243 trits.
  • errors.ILLEGAL_NUMBER_OF_FRAGMENTS : Make sure that the numberOfFragments argument is a valid security level (between 1 and 3).
Param Type Description
subseedTrits Int8Array A subseed in trits
numberOfFragments number The security level that you want the private key to have

This method derives a private key from a subseed.

You can use the private key to derive an address and to sign bundles that withdraw from that address.

Related methods

To generate a subseed, use the subseed() method.

Returns: Int8Array - privateKey - A private key in trits.
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

signing.digests(key)

Summary: Generates key digests for a given private key.
Throws:

  • errors.ILLEGAL_KEY_LENGTH : Make sure that the key argument contains 2,187, 4,374, or 6,561 trits.
Param Type Description
key Int8Array Private key in trits

This method derives key digests from a private key.

You can use the key digests to generate an address.

Related methods

To generate a private key, use the key() method.

Returns: Int8Array - digests - Key digests in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

const digests = Signing.digests(privateKey);

signing.address(digests)

Summary: Derives an address from the given key digests.
Throws:

  • errors.ILLEGAL_DIGESTS_LENGTH : Make sure that the digests argument contains a multiple of 243 trits.
Param Type Description
digests Int8Array Key digests in trits

This method derives a 243-trit address from the given key digests.

Related methods

To generate a private key, use the key() method.

Returns: Int8Array - address - Address in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

const digests = Signing.digests(privateKey);

const address = Signing.address(digests);

signing.validateSignatures(expectedAddress, signatureFragments, bundle)

Summary: Validates the given signature, using the given bundle and address.
Throws:

  • errors.ILLEGAL_BUNDLE_HASH_LENGTH : Make sure that the bundle argument contains a 243-trit bundle hash.
Param Type Description
expectedAddress Int8Array Input address in trits
signatureFragments Array.<Int8Array> Signature fragments in trits
bundle Int8Array Bundle hash in trits

This method validates a signature by doing the following:

  • Normalizing the bundle hash
  • Deriving the key digests of the address, using the normalized bundle hash and the signature -.Deriving an address from the key digests
  • Comparing the derived address to the expectedAddress argument to find out if they match

If the addresses match, the signature is valid.

For more information about signatures see the documentation portal.

Related methods

To convert trytes such as bundle hashes and addresses to trits, use the trytesToTrits() method.

Returns: boolean - valid - Whether the signatures are valid.
Example

let valid = Signing.validateSignatures(expectedAddress, signatureFragments, bundle);

signing.normalizedBundle(bundle)

Summary: Normalizes the bundle hash.
Throws:

  • errors.ILLEGAL_BUNDLE_HASH_LENGTH : Make sure that the bundle argument contains a 243-trit bundle hash.
Param Type Description
bundle Int8Array Bundle hash in trits

This method normalizes the given bundle hash to make sure that only around half of the private key is revealed when the bundle hash is signed.

For more information about signatures see the documentation portal.

To find out more about why the bundle hash is normalized, see this answer on StackExchange.

Related methods

To convert a bundle hash from trytes to trits, use the trytesToTrits() method.

Returns: Int8Array - Normalized bundle hash in trits
Example

let normalizedBundleHash = Signing.normalizedBundle(bundle);