feat: add SDK utilities content (#2)

* fix: link * chore: remove comment * feat: overview content * feat: generateStealthAddress * feat: more context on ephemeral priv key * feat: show res vars * feat: computeStealthKey * feat: return values * feat: use tabs * chore: format * fix: tabs * fix: format * chore: format * feat: checkStealthAddress * fix: solidity event def * chore: format * Fix nits --------- Co-authored-by: garyghayrat <[email protected]>
ScopeLift · May 7, 2024 · aec04a7 · aec04a7
1 parent b78f1d2
commit aec04a7
Show file tree

Hide file tree

Showing 11 changed files with 452 additions and 3 deletions.
diff --git a/pages/SDK/_meta.json b/pages/SDK/_meta.json
@@ -1,5 +1,7 @@
 {
   "overview": "Overview",
+  "getting-started": "Getting Started",
   "guides": "Guides",
-  "technical-reference": "Technical Reference"
+  "utilities": "Utilities",
+  "glossary": "Glossary"
 }
diff --git a/pages/SDK/getting-started.mdx b/pages/SDK/getting-started.mdx
@@ -0,0 +1,28 @@
+## Getting Started
+
+This guide will walk you through the installation and basic usage of the Stealth Address SDK, setting you up to integrate stealth transaction capabilities into your Ethereum-based applications.
+
+### Installation
+
+```sh npm2yarn
+npm i @scopelift/stealth-address-sdk
+```
+
+### Basic Usage
+
+Generate a stealth address using the SDK, assuming you have a stealth meta-address (more info in further sections):
+
+```ts
+import { generateStealthAddress } from "@scopelift/stealth-address-sdk";
+
+// The stealth meta-address URI Follows the format: "st:<chain>:<stealthMetaAddress>", where <chain> is the chain identifier (https://eips.ethereum.org/EIPS/eip-3770#examples) and <stealthMetaAddress> is the stealth meta-address.
+// You can also use the stealth meta-address directly, without the URI prefix.
+const stealthMetaAddressURI = "...";
+
+// Generate a stealth address using the default scheme (1)
+// To learn more about the initial implementation scheme using SECP256k1, please see the reference here (https://eips.ethereum.org/EIPS/eip-5564)
+const result = generateStealthAddress({ stealthMetaAddressURI });
+
+// Use the stealth address
+console.log(result.stealthAddress);
+```
diff --git a/pages/SDK/glossary/types.mdx b/pages/SDK/glossary/types.mdx
@@ -0,0 +1,32 @@
+# Types
+
+Glossary of types in the Stealth Address SDK.
+
+    ## `HexString`
+    Signifies any length hexadecimal string, synonymous with `0x${string}`
+
+    ## `VALID_SCHEME_ID`
+    ```ts
+    export enum VALID_SCHEME_ID {
+      SCHEME_ID_1 = 1
+    }
+    ```
+    Signifies a valid scheme id; the only valid scheme id is currently `1`.
+
+    ## `Announce`
+    The event emitted from the `announce` function call on the ERC-5564 contract.
+
+    This is an informational solidity event definition and isn't an actual type provided in the SDK.
+
+    ```solidity
+    event Announcement(
+      uint256 indexed schemeId,
+      address indexed stealthAddress,
+      address indexed caller,
+      bytes ephemeralPubKey,
+      bytes metadata
+    );
+    ```
+
+    ## `EthAddress`
+    Represents an Ethereum address.
diff --git a/pages/SDK/overview.mdx b/pages/SDK/overview.mdx
@@ -0,0 +1,16 @@
+## Overview
+
+### Stealth Address SDK
+
+The Stealth Address SDK provides developers a toolkit for integrating stealth transaction capabilities into Ethereum-based applications, supporting ERC-5564 and ERC-6538.
+
+### Key Features
+
+- **Stealth Address Utilities**: `generateStealthAddress` and `computeStealthKey` are examples of utility functions that help build up a stealth transaction. More info detailed in further sections.
+- **Stealth Transaction Monitoring**: `watchAnnouncementsForUser` combines several important steps in a stealth transaction, such as watching for announcements relevant to a specific user.
+- **Contract Interaction Preparation**: `prepare` functions simulate and return the payloads for key ERC-5564 and ERC-6538 contract interactions, such as `prepareRegisterKeys`, which prepares registering a stealth meta-address and outputs the required transaction payload (`to`, `from`, `data`).
+- **Examples**: The SDK includes a variety of examples to help developers get started with stealth transactions.
+
+### Use Cases
+
+This SDK is built for developers looking to integrate stealth transactions into their applications, adding a layer of privacy into their apps.
diff --git a/pages/SDK/technical-reference.mdx b/pages/SDK/technical-reference.mdx
diff --git a/pages/SDK/utilities/_meta.json b/pages/SDK/utilities/_meta.json
@@ -0,0 +1,6 @@
+{
+  "index": "Overview",
+  "generateStealthAddress": "generateStealthAddress",
+  "computeStealthKey": "computeStealthKey",
+  "checkStealthAddress": "checkStealthAddress"
+}
diff --git a/pages/SDK/utilities/checkStealthAddress.mdx b/pages/SDK/utilities/checkStealthAddress.mdx
@@ -0,0 +1,142 @@
+import { Tabs } from "nextra/components";
+
+# checkStealthAddress
+
+Checks if an [`Announce`](../glossary/types.mdx#announce) event is intended for the user by comparing the derived stealth address with the user's stealth address.
+
+## Import
+
+```ts
+import { checkStealthAddress } from "@scopelift/stealth-address-sdk";
+```
+
+## Usage
+
+<Tabs items={['example.ts']} selectedIndex={0}>
+  <Tabs.Tab>
+    ```ts
+    import { checkStealthAddress } from "@scopelift/stealth-address-sdk";
+
+    const isForUser = checkStealthAddress({
+      ephemeralPublicKey: "0x...",
+      schemeId: 1,
+      spendingPublicKey: "0x...",
+      userStealthAddress: "0x...",
+      viewingPrivateKey: "0x...",
+      viewTag: "0x..."
+    });
+
+    // true
+    ```
+
+  </Tabs.Tab>
+</Tabs>
+
+## Return Value
+
+- **Type:** `boolean`
+  Returns `true` if the derived stealth address matches the user's stealth address, indicating the announcement is intended for the user; returns `false` otherwise.
+
+## Parameters
+
+### ephemeralPublicKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+
+  The ephemeral public key from the announcement.
+
+```ts {2}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
+
+### schemeId
+
+- **Type:** [`VALID_SCHEME_ID`](../glossary/types.md#valid_scheme_id)
+
+  The scheme ID used during the stealth address generation.
+
+```ts {3}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
+
+### spendingPublicKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+
+  The user's spending public key.
+
+```ts {4}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
+
+### userStealthAddress
+
+- **Type:** [`EthAddress`](../glossary/types.md#ethaddress)
+
+  The user's stealth address, against which the derived address is compared.
+
+```ts {5}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
+
+### viewingPrivateKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+
+  The user's viewing private key used to derive the shared secret.
+
+```ts {6}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
+
+### viewTag
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+
+  The view tag from the announcement, used to quickly filter announcements not intended for the user.
+
+```ts {7}
+const isForUser = checkStealthAddress({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPublicKey: "0x...",
+  userStealthAddress: "0x...",
+  viewingPrivateKey: "0x...",
+  viewTag: "0x...",
+});
+```
diff --git a/pages/SDK/utilities/computeStealthKey.mdx b/pages/SDK/utilities/computeStealthKey.mdx
@@ -0,0 +1,95 @@
+import { Tabs } from "nextra/components";
+
+# computeStealthKey
+
+Computes the stealth address private key by combining the spending private key with a hashed shared secret, which is derived from an ephemeral public key and a viewing private key.
+
+## Import
+
+```ts
+import { computeStealthKey } from "@scopelift/stealth-address-sdk";
+```
+
+## Usage
+
+<Tabs items={['example.ts']} selectedIndex={0}>
+  <Tabs.Tab>
+    ```ts
+    import { computeStealthKey } from "@scopelift/stealth-address-sdk";
+
+    const stealthPrivateKey = computeStealthKey({
+      ephemeralPublicKey,
+      schemeId: 1,
+      spendingPrivateKey,
+      viewingPrivateKey
+    });
+
+    // "0x..."
+    ```
+
+  </Tabs.Tab>
+</Tabs>
+
+## Return Value
+
+[`HexString`](../glossary/types.md#hexstring)
+
+The computed stealth address private key.
+
+## Parameters
+
+### ephemeralPublicKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+  The ephemeral public key returned from calling the [`generateStealthAddress`](./generateStealthAddress.mdx) function or emitted from the [`Announce`](../glossary/types.mdx#announce) event.
+
+```ts {2}
+const stealthPrivateKey = computeStealthKey({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPrivateKey: "0x...",
+  viewingPrivateKey: "0x...",
+});
+```
+
+### schemeId
+
+- **Type:** [`VALID_SCHEME_ID`](../glossary/types.mdx#valid_scheme_id)
+  The scheme id used to generate the stealth address.
+
+```ts {3}
+const stealthPrivateKey = computeStealthKey({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPrivateKey: "0x...",
+  viewingPrivateKey: "0x...",
+});
+```
+
+### spendingPrivateKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+  The spending private key used to generate the stealth meta-address.
+
+```ts {4}
+const stealthPrivateKey = computeStealthKey({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPrivateKey: "0x...",
+  viewingPrivateKey: "0x...",
+});
+```
+
+### viewingPrivateKey
+
+- **Type:** [`HexString`](../glossary/types.md#hexstring)
+  The viewing private key used to generate the stealth meta-address.
+
+```ts {5}
+const stealthPrivateKey = computeStealthKey({
+  ephemeralPublicKey: "0x...",
+  schemeId: 1,
+  spendingPrivateKey: "0x...",
+  viewingPrivateKey: "0x...",
+});
+```