Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds SDK section to Reference. #307

Draft
wants to merge 16 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Dependencies
/node_modules
*node_modules*

# Production
/public
Expand Down
6 changes: 0 additions & 6 deletions content/reference/javascript-sdk.md

This file was deleted.

79 changes: 79 additions & 0 deletions content/reference/javascript-sdk/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: "JavaScript SDK"
lead: "The SDK is the fastest way to start integrating the Entropy network into your project. This section covers concepts specific to the JS SDK, a basic _hello world_ tutorial to help you get started, and links to in-depth reference documentation."
aliases:
- "sdk"
---

{{< callout type="warning" >}}
The Entropy SDK is currently in alpha. While we're excited about its capabilities, keep in mind that breaking changes may occur, APIs might be unstable, and features and functionality may change. Do not use this SDK in a production environment.
{{< /callout >}}

## Overview

The Entropy SDK enables developers to integrate decentralized threshold signatures into their projects. Unlike traditional signature solutions that rely on single keys or centralized services, Entropy distributes the signing process across a decentralized network while maintaining the simplicity of a regular API. The SDK also features robust account management and Entropy Program deployment functions.

Built on Substrate, Entropy provides a robust foundation for blockchain applications that require secure, distributed signing capabilities. The SDK abstracts away the complexity of threshold cryptography, allowing developers to focus on building their applications.

## Core features

{{< cards cols="2" >}}
{{< card link="../callout" title="Program deployment" icon="tag" subtitle="Deploy and manage programs that define your signing logic. Each program acts as a customizable rule set for how signatures should be generated and validated." >}}
{{< card link="../callout" title="Signature creation and verification" icon="tag" subtitle="Create and verify signatures through a straightforward API that handles all the underlying cryptographic operations." >}}
{{< card link="../callout" title="Account management" icon="tag" subtitle="Manage user accounts and keys securely with the SDKs built-in account functions." >}}
{{< card link="../callout" title="General utilities" icon="tag" subtitle="Easily incorporate basic utilite functions built right into the SDK.">}}
{{< /cards >}}

## Getting Started

Start building with the Entropy SDK quickly by grabbing the appropriate package, setting up a development environment, and creating a basic startup script.

### Installation

Install the SDK using NPM or Yarn:

{{< tabs items="NPM, Yarn" >}}

{{< tab >}}
```shell
npm install @entropyxyz/sdk
```
{{< /tab >}}

{{< tab >}}
```shell
yarn add @entropyxyz/sdk
```
{{< /tab >}}

{{< /tabs >}}

### Basic Setup

Initialize the SDK to create your first signature:

```javascript
import { Keyring } from '@entropyxyz/sdk/keys';
import { wasmGlobalsReady, Entropy } from '@entropyxyz/sdk';

async function quickStart() {
await wasmGlobalsReady();
const keyring = new Keyring({ seed: yourSeed });
const entropy = new Entropy({
endpoint: 'ws://127.0.0.1:9944',
keyring
});
await entropy.ready;
// Your code here
}
```

### Local Development

For development and testing, we recommend [setting up a local devnet](https://docs.entropy.xyz/guides/spin-up-a-devnet/). A devnet provides a controlled environment to freely experiment with different programs and configurations.

### Move to the testnet

Once your application works locally, move to testnet testing by using the testnet endpoint: `wss://testnet.entropy.xyz`. Remember that programs can only be deployed once per account on testnet. Use the [Entropy CLI](https://github.com/entropyxyz/cli) for additional testing and management capabilities

## Next steps
97 changes: 97 additions & 0 deletions content/reference/javascript-sdk/example-scripts/end-to-end.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import { Keyring } from '@entropyxyz/sdk/keys';
import { wasmGlobalsReady, Entropy } from '@entropyxyz/sdk';
import { Buffer } from 'buffer';

async function runEntropyDemo() {
try {
// Wait for WASM to be ready
console.log('Initializing WASM...');
await wasmGlobalsReady();
console.log('WASM initialized successfully');

// Replace this with your actual seed from the Entropy platform
const seed = '0x2d4be88e8c759f4e614bb6f95bde9f625fed38c4b343fa72bf4de98a2f1c8fdf';

// Initialize the keystore with your seed
const keyStore = { seed };
console.log('Keystore initialized');

// Create a new keyring instance
const keyring = new Keyring(keyStore);
console.log('Keyring created successfully');

// Configure the Entropy connection
const opts = {
endpoint: 'wss://testnet.entropy.xyz', // Use testnet endpoint
keyring
};

// Initialize Entropy
console.log('Connecting to Entropy network...');
const entropy = new Entropy(opts);
await entropy.ready;
console.log('Successfully connected to Entropy network');

return entropy;
} catch (error) {
console.error('Error in setup:', error);
throw error;
}
}

async function createAndVerifySignature(entropy) {
try {
// Create a message to sign
const message = 'Hello world: signature from entropy!';
console.log(`Creating signature for message: ${message}`);

const msgObject = {
msg: Buffer.from(message).toString('hex')
};

// Register with the network
console.log('Registering with network...');
const verifyingKey = await entropy.register();
console.log('Registration successful. Verifying key:', verifyingKey);

// Create signature
console.log('Creating signature...');
const signatureData = await entropy.signWithAdaptersInOrder({
msg: msgObject,
order: ['deviceKeyProxy']
});
console.log('Signature created:', signatureData);

// Verify the signature
console.log('Verifying signature...');
const isValid = await entropy.verify(signatureData);

if (!isValid) {
throw new Error('Signature verification failed');
}

console.log('Signature verified successfully!');
return signatureData;

} catch (error) {
console.error('Error in signature creation/verification:', error);
throw error;
} finally {
// Clean up by closing the connection
await entropy.close();
}
}

// Main execution
async function main() {
try {
const entropy = await runEntropyDemo();
const signatureData = await createAndVerifySignature(entropy);
console.log('Complete signature data:', signatureData);
} catch (error) {
console.error('Main execution error:', error);
}
}

// Run the demo
main();
Loading