From 1326ef8a9ac4b38e161437d13fd639d0e1e985bd Mon Sep 17 00:00:00 2001 From: marcomariscal Date: Tue, 23 Apr 2024 13:50:10 -0700 Subject: [PATCH 1/2] 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 feat: stealth client feat: getAnnouncements doc page feat: getAnnouncementsForUser feat: getStealthMetaAddress fix: stealthClient ref feat: prepareAnnounce feat: prepareRegisterKeys feat: prepareRegisterKeysOnBehalf feat: watchAnnouncementsForUser feat: alphabetize types in glossary chore: format Correct highlighted lines feat: glossary terms (#6) * feat: terms * chore: format * Fix nits --------- Co-authored-by: garyghayrat <61768337+garyghayrat@users.noreply.github.com> --- pages/SDK/_meta.json | 2 + pages/SDK/actions/_meta.json | 10 + pages/SDK/actions/getAnnouncements.mdx | 115 ++++++++++ pages/SDK/actions/getAnnouncementsForUser.mdx | 138 ++++++++++++ pages/SDK/actions/getStealthMetaAddress.mdx | 85 ++++++++ pages/SDK/actions/index.mdx | 27 +++ pages/SDK/actions/prepareAnnounce.mdx | 109 ++++++++++ pages/SDK/actions/prepareRegisterKeys.mdx | 108 ++++++++++ .../actions/prepareRegisterKeysOnBehalf.mdx | 91 ++++++++ .../SDK/actions/watchAnnouncementsForUser.mdx | 202 ++++++++++++++++++ pages/SDK/glossary/_meta.json | 4 + pages/SDK/glossary/terms.mdx | 58 +++++ pages/SDK/glossary/types.mdx | 90 +++++++- pages/SDK/stealth-client/_meta.json | 3 + pages/SDK/stealth-client/index.mdx | 68 ++++++ 15 files changed, 1109 insertions(+), 1 deletion(-) create mode 100644 pages/SDK/actions/_meta.json create mode 100644 pages/SDK/actions/getAnnouncements.mdx create mode 100644 pages/SDK/actions/getAnnouncementsForUser.mdx create mode 100644 pages/SDK/actions/getStealthMetaAddress.mdx create mode 100644 pages/SDK/actions/index.mdx create mode 100644 pages/SDK/actions/prepareAnnounce.mdx create mode 100644 pages/SDK/actions/prepareRegisterKeys.mdx create mode 100644 pages/SDK/actions/prepareRegisterKeysOnBehalf.mdx create mode 100644 pages/SDK/actions/watchAnnouncementsForUser.mdx create mode 100644 pages/SDK/glossary/_meta.json create mode 100644 pages/SDK/glossary/terms.mdx create mode 100644 pages/SDK/stealth-client/_meta.json create mode 100644 pages/SDK/stealth-client/index.mdx diff --git a/pages/SDK/_meta.json b/pages/SDK/_meta.json index 9efa8e6..67eff9d 100644 --- a/pages/SDK/_meta.json +++ b/pages/SDK/_meta.json @@ -2,6 +2,8 @@ "overview": "Overview", "getting-started": "Getting Started", "guides": "Guides", + "stealth-client": "Stealth Client", + "actions": "Actions", "utilities": "Utilities", "glossary": "Glossary" } diff --git a/pages/SDK/actions/_meta.json b/pages/SDK/actions/_meta.json new file mode 100644 index 0000000..4abc6c6 --- /dev/null +++ b/pages/SDK/actions/_meta.json @@ -0,0 +1,10 @@ +{ + "index": "Overview", + "getAnnouncements": "getAnnouncements", + "getAnnouncementsForUser": "getAnnouncementsForUser", + "getStealthMetaAddress": "getStealthMetaAddress", + "prepareAnnounce": "prepareAnnounce", + "prepareRegisterKeys": "prepareRegisterKeys", + "prepareRegisterKeysOnBehalf": "prepareRegisterKeysOnBehalf", + "watchAnnouncementsForUser": "watchAnnouncementsForUser" +} diff --git a/pages/SDK/actions/getAnnouncements.mdx b/pages/SDK/actions/getAnnouncements.mdx new file mode 100644 index 0000000..94f724f --- /dev/null +++ b/pages/SDK/actions/getAnnouncements.mdx @@ -0,0 +1,115 @@ +import { Tabs } from "nextra/components"; + +# getAnnouncements + +Get announcement event logs from the `ERC5564Announcer` contract. + +## Usage + + + + ```ts {11-20} + import { stealthClient } from './client'; + + const announcements = await stealthClient.getAnnouncements({ + ERC5564Address, + args, + fromBlock, + toBlock + }); + + /* + [ + { + caller: "0x...", + ephemeralPubKey: "0x...", + metadata: "0x...", + schemeId: 1n, + stealthAddress: "0x...", + more log data... + } + ] + */ + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`GetAnnouncementsReturnType`](../glossary/types.md#getannouncementsreturntype) + + An array of `Announce` event log data emitted from the `ERC5564Announcer` contract. + +## Parameters + +### ERC5564Address + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The address of the `ERC5564Announcer` contract. + +```ts {2} +const announcements = await stealthClient.getAnnouncements({ + ERC5564Address, + args, + fromBlock, + toBlock, +}); +``` + +### args + +- **Type:** [`AnnouncementArgs`](../glossary/types.md#announcementargs) + + The arguments to filter the `Announce` event logs. + +```ts {3} +const announcements = await stealthClient.getAnnouncements({ + ERC5564Address, + args, + fromBlock, + toBlock, +}); +``` + +### fromBlock + +- **Type:** [`BlockType`](../glossary/types.md#blocktype) + + The block number to start fetching logs from. + +```ts {4} +const announcements = await stealthClient.getAnnouncements({ + ERC5564Address, + args, + fromBlock, + toBlock, +}); +``` + +### toBlock + +- **Type:** [`BlockType`](../glossary/types.md#blocktype) + + The block number to stop fetching logs at. + +```ts {5} +const announcements = await stealthClient.getAnnouncements({ + ERC5564Address, + args, + fromBlock, + toBlock, +}); +``` diff --git a/pages/SDK/actions/getAnnouncementsForUser.mdx b/pages/SDK/actions/getAnnouncementsForUser.mdx new file mode 100644 index 0000000..99a4b8a --- /dev/null +++ b/pages/SDK/actions/getAnnouncementsForUser.mdx @@ -0,0 +1,138 @@ +import { Tabs } from "nextra/components"; + +# getAnnouncementsForUser + +Filters a list of given announcements based on if they are relevant for the user. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const userAnnouncements = await stealthClient.getAnnouncementsForUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList + }); + + /* + Array of announcements relevant to the user. + + [ + { + caller: "0x...", + ephemeralPubKey: "0x...", + metadata: "0x...", + schemeId: 1n, + stealthAddress: "0x...", + more log data... + } + ] + */ + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`GetAnnouncementsForUserReturnType`](../glossary/types.md#getannouncementsforuserreturntype) + + An array of announcements relevant to the user, filtered by the provided criteria. + +## Parameters + +### announcements + +- **Type:** [`AnnouncementLog[]`](../glossary/types.md#announcementlog) + + An array of announcement logs to be processed and filtered. + +```ts {2} +const userAnnouncements = await stealthClient.getAnnouncementsFroUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList, +}); +``` + +### spendingPublicKey + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The user's spending public key. + +```ts {3} +const userAnnouncements = await stealthClient.getAnnouncementsFroUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList, +}); +``` + +### viewingPrivateKey + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The user's viewing private key. + +```ts {4} +const userAnnouncements = await stealthClient.getAnnouncementsFroUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList, +}); +``` + +### excludeList (optional) + +- **Type:** [`EthAddress[]`](../glossary/types.md#ethaddress) + + Addresses to exclude from the results. + +```ts {5} +const userAnnouncements = await stealthClient.getAnnouncementsFroUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList, +}); +``` + +### includeList (optional) + +- **Type:** [`EthAddress[]`](../glossary/types.md#ethaddress) + + Addresses to specifically include in the results. + +```ts {6} +const userAnnouncements = await stealthClient.getAnnouncementsFroUser({ + announcements, + spendingPublicKey, + viewingPrivateKey, + excludeList, + includeList, +}); +``` diff --git a/pages/SDK/actions/getStealthMetaAddress.mdx b/pages/SDK/actions/getStealthMetaAddress.mdx new file mode 100644 index 0000000..6fed6be --- /dev/null +++ b/pages/SDK/actions/getStealthMetaAddress.mdx @@ -0,0 +1,85 @@ +import { Tabs } from "nextra/components"; + +# getStealthMetaAddress + +Retrieves a stealth meta-address from the ERC-6538 Registry contract. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const stealthMetaAddress = await stealthClient.getStealthMetaAddress({ + ERC6538Address, + registrant, + schemeId + }); + + // '0x...' + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The stealth meta address of the registrant. + +## Parameters + +### ERC6538Address + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The address of the ERC-6538 Registry contract. + +```ts {2} +const stealthMetaAddress = await stealthClient.getStealthMetaAddress({ + ERC6538Address, + registrant, + schemeId, +}); +``` + +### registrant + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The identifier of the registrant, which could be an Ethereum address or an ENS name. + +```ts {3} +const stealthMetaAddress = await stealthClient.getStealthMetaAddress({ + ERC6538Address, + registrant, + schemeId, +}); +``` + +### schemeId + +- **Type:** [`VALID_SCHEME_ID`](../glossary/types.md#valid_scheme_id) + + The ID of the stealth address scheme. + +```ts {4} +const stealthMetaAddress = await stealthClient.getStealthMetaAddress({ + ERC6538Address, + registrant, + schemeId, +}); +``` diff --git a/pages/SDK/actions/index.mdx b/pages/SDK/actions/index.mdx new file mode 100644 index 0000000..6ee1af3 --- /dev/null +++ b/pages/SDK/actions/index.mdx @@ -0,0 +1,27 @@ +# Overview + +The SDK provides a suite of actions that enable developers to handle various stealth address-related functionalities seamlessly. + +These actions can be consumed from an initialized `stealthClient` instance: + +```ts +import { createStealthClient } from "@scopelift/stealth-address-sdk"; + +const stealthClient = createStealthClient({ + chainId, + rpcUrl, +}); + +const announcements = await stealthClient.getAnnouncements(...args); +``` + +Or alternatively, you can call the action directly by passing the [`clientParams`](../glossary/types.md#clientparams) object with `chainId` and `rpcUrl`: + +```ts +import { getAnnouncements } from "@scopelift/stealth-address-sdk"; + +const announcements = await getAnnouncements({ + clientParams: { chainId, rpcUrl }, + ...args, +}); +``` diff --git a/pages/SDK/actions/prepareAnnounce.mdx b/pages/SDK/actions/prepareAnnounce.mdx new file mode 100644 index 0000000..38bef3b --- /dev/null +++ b/pages/SDK/actions/prepareAnnounce.mdx @@ -0,0 +1,109 @@ +import { Tabs } from "nextra/components"; + +# prepareAnnounce + +Prepares the payload for announcing a stealth address from the ERC-5564 contract. + +This function simulates the contract call to generate the necessary transaction payload without sending a transaction. + +The resulting payload can then be used for sending a transaction. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const payload = await stealthClient.prepareAnnounce({ + account, + args: { + schemeId, + stealthAddress, + ephemeralPublicKey, + metadata + }, + ERC5564Address + }); + + /* { account, data, to, value } */ + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`PreparePayload`](../glossary/types.md#preparepayload) + + The prepared payload to send a transaction to the ERC-5564 contract and call `announce` on the contract. + +## Parameters + +### account + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The address of the account making the announcement. + +```ts {2} +const payload = await prepareAnnounce({ + account, + args: { + schemeId, + stealthAddress, + ephemeralPublicKey, + metadata, + }, + ERC5564Address, +}); +``` + +### args + +- **Type:** [`PrepareAnnounceArgs`](../glossary/types.md#prepareannounceargs) + + The details of the announcement, including the scheme ID, stealth address, ephemeral public key, and metadata. + +```ts {3} +const payload = await prepareAnnounce({ + account, + args: { + schemeId, + stealthAddress, + ephemeralPublicKey, + metadata, + }, + ERC5564Address, +}); +``` + +### ERC5564Address + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The address of the ERC5564 Announcer contract. + +```ts {9} +const payload = await prepareAnnounce({ + account, + args: { + schemeId, + stealthAddress, + ephemeralPublicKey, + metadata, + }, + ERC5564Address, +}); +``` diff --git a/pages/SDK/actions/prepareRegisterKeys.mdx b/pages/SDK/actions/prepareRegisterKeys.mdx new file mode 100644 index 0000000..79bee31 --- /dev/null +++ b/pages/SDK/actions/prepareRegisterKeys.mdx @@ -0,0 +1,108 @@ +import { Tabs } from "nextra/components"; + +# prepareRegisterKeys + +Prepares the payload for registering a stealth meta-address (keys) in the ERC-6538 registry contract. + +This function simulates the contract call to generate the necessary transaction payload without sending a transaction. + +The resulting payload can then be used for sending a transaction. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const payload = await stealthClient.prepareRegisterKeys({ + ERC6538Address, + schemeId, + stealthMetaAddress, + account, + }); + + /* { account, data, to, value } */ + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`PreparePayload`](../glossary/types.md#preparepayload) + + The prepared payload to send a transaction to the ERC-6538 contract and call `registerKeys` on the contract. + +## Parameters + +### ERC6538Address + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The address of the ERC-6538 Registry contract. + +```ts {2} +const payload = await stealthClient.prepareRegisterKeys({ + ERC6538Address, + schemeId, + stealthMetaAddress, + account, +}); +``` + +### schemeId + +- **Type:** `bigint` + + The ID of the stealth address scheme. + +```ts {3} +const payload = await stealthClient.prepareRegisterKeys({ + ERC6538Address, + schemeId, + stealthMetaAddress, + account, +}); +``` + +### stealthMetaAddress + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The stealth meta address of the registrant. + +```ts {4} +const payload = await stealthClient.prepareRegisterKeys({ + ERC6538Address, + schemeId, + stealthMetaAddress, + account, +}); +``` + +### account + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The address that will be used to send the transaction. + +```ts {5} +const payload = await stealthClient.prepareRegisterKeys({ + ERC6538Address, + schemeId, + stealthMetaAddress, + account, +}); +``` diff --git a/pages/SDK/actions/prepareRegisterKeysOnBehalf.mdx b/pages/SDK/actions/prepareRegisterKeysOnBehalf.mdx new file mode 100644 index 0000000..0780382 --- /dev/null +++ b/pages/SDK/actions/prepareRegisterKeysOnBehalf.mdx @@ -0,0 +1,91 @@ +import { Tabs } from "nextra/components"; + +# prepareRegisterKeysOnBehalf + +Prepares the payload for registering a stealth meta-address (keys) in the ERC-6538 registry contract on behalf of another account. + +This function simulates the contract call to generate the necessary transaction payload without sending a transaction. + +The resulting payload can then be used for sending a transaction. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const payload = await stealthClient.prepareRegisterKeysOnBehalf({ + ERC6538Address, + args, + account, + }); + + /* { account, data, to, value } */ + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** [`PreparePayload`](../glossary/types.md#preparepayload) + + The prepared payload to send a transaction to the ERC-6538 contract and call `registerKeysOnBehalf` on the contract. + +## Parameters + +### ERC6538Address + +- **Type:** [`EthAddress`](../glossary/types.md#ethaddress) + + The address of the ERC-6538 Registry contract. + +```ts {2} +const payload = await stealthClient.prepareRegisterKeysOnBehalf({ + ERC6538Address, + args, + account, +}); +``` + +### args + +- **Type:** [`RegisterKeysOnBehalfArgs`](../glossary/types.md#registerkeysonbehalfargs) + + The arguments for registering the stealth meta address. + + Includes the stealth meta address, scheme ID, the registrant's address, and the registrant's signature authorizing the registration. + +```ts {3} +const payload = await stealthClient.prepareRegisterKeysOnBehalf({ + ERC6538Address, + args, + account, +}); +``` + +### account + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The address that will be used to send the transaction. + +```ts {4} +const payload = await stealthClient.prepareRegisterKeysOnBehalf({ + ERC6538Address, + args, + account, +}); +``` diff --git a/pages/SDK/actions/watchAnnouncementsForUser.mdx b/pages/SDK/actions/watchAnnouncementsForUser.mdx new file mode 100644 index 0000000..3912154 --- /dev/null +++ b/pages/SDK/actions/watchAnnouncementsForUser.mdx @@ -0,0 +1,202 @@ +import { Tabs } from "nextra/components"; + +# watchAnnouncementsForUser + +Watches for announcements relevant to the user. + +`checkStealthAddress` is used to determine if the announcement is intended for the specific user. + +## Usage + + + + ```ts + import { stealthClient } from "./client"; + + const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, + }); + ``` + + + + ```ts + import { createStealthClient } from "@scopelift/stealth-address-sdk"; + + export const stealthClient = createStealthClient({ + chainId, + rpcUrl, + }); + ``` + + + + +## Return Value + +- **Type:** `function` + + A function that can be called to stop watching for announcements. + +## Parameters + +### args + +- **Type:** [`AnnouncementArgs`](../glossary/types.md#announcementargs) + + The arguments used to filter all announcements. + + Includes the scheme ID, stealth address, and caller. + +```ts {2} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### spendingPublicKey + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The spending public key of the user. + +```ts {3} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### viewingPrivateKey + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The viewing private key of the user. + +```ts {4} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### ERC5564Address + +- **Type:** [`HexString`](../glossary/types.md#hexstring) + + The address of the `ERC5564Announcer` contract. + +```ts {5} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### excludeList (optional) + +- **Type:** [`EthAddress[]`](../glossary/types.md#ethaddress) + + Addresses to exclude from the results. + +```ts {6} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### includeList (optional) + +- **Type:** [`EthAddress[]`](../glossary/types.md#ethaddress) + + Addresses to include in the results. + +```ts {7} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### handleLogsForUser + +- **Type:** `function` + + A function to transform relevant announcements. + +```ts {8} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` + +### pollOptions (optional) + +- **Type:** [`WatchAnnouncementsForUserPollingOptions`](../glossary/types.md#watchannouncementsforuserpollingoptions) + + Options for polling (watching) the contract. + +```ts {9} +const unwatch = await stealthClient.watchAnnouncementsForUser({ + args, + spendingPublicKey, + viewingPrivateKey, + ERC5564Address, + excludeList, + includeList, + handleLogsForUser, + pollOptions, +}); +``` diff --git a/pages/SDK/glossary/_meta.json b/pages/SDK/glossary/_meta.json new file mode 100644 index 0000000..d8e450c --- /dev/null +++ b/pages/SDK/glossary/_meta.json @@ -0,0 +1,4 @@ +{ + "terms": "Terms", + "types": "Types" +} diff --git a/pages/SDK/glossary/terms.mdx b/pages/SDK/glossary/terms.mdx new file mode 100644 index 0000000..67a7d61 --- /dev/null +++ b/pages/SDK/glossary/terms.mdx @@ -0,0 +1,58 @@ +import { Callout } from "nextra/components"; + +# Terms + +Glossary of Stealth address terms. + +## Stealth Address + +Stealth addresses allow senders of transactions or transfers to non-interactively generate private accounts exclusively accessible by their recipients. + +The recipients alone can access the funds stored at their stealth addresses, as they are the sole owners of the necessary private key. + +## Stealth Meta-Address + +A stealth meta-address is a set of one or two public keys that can be used to compute a stealth address for a given recipient. + +It is composed of: + +- **spending key** + + A private key that can be used to spend funds sent to a stealth address. A “spending public key” is the corresponding public key. + +- **viewing key** + + A private key that can be used to determine if funds sent to a stealth address belong to the recipient who controls the corresponding spending key. A “viewing public key” is the corresponding public key. + +[Learn more](https://eips.ethereum.org/EIPS/eip-5564) + +## Scheme Id + +Each stealth address scheme is identified by a unique identifier called the `schemeID`. + +The implementation of the methods `generateStealthAddress`, `checkStealthAddress`, and `computeStealthKey` are scheme-specific, and so the scheme ID is used to determine which implementation to use. + +The first implementation, with `schemeId` of `1` uses SECP256k1 elliptic curve cryptography. + + + This SDK conforms to the `schemeId` `1` specification laid out in + [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564). + + +## Stealth Key + +Refers to the private key associated with a stealth address. + +## Ephemeral Public Key + +The ephemeral public key is generated from a random ephemeral private key and is used to compute the shared secret, enabling the recipient to decrypt announcements and verify their relevance to the user. + +It is "ephemeral" because it is used only once to derive the corresponding stealth address and its associated details. + +## View Tag + +The first byte of the metadata field in the `Announce` event log emitted from the `ERC5564Announcer` contract. + +The view tag allows for more effective lookup when checking if the stealth address is intended for the recipient. + +If the view tag doesn't match the expected, then the rest of the checking logic can be skipped. diff --git a/pages/SDK/glossary/types.mdx b/pages/SDK/glossary/types.mdx index 5222b49..41488a8 100644 --- a/pages/SDK/glossary/types.mdx +++ b/pages/SDK/glossary/types.mdx @@ -13,10 +13,14 @@ Glossary of types in the Stealth Address SDK. ``` Signifies a valid scheme id; the only valid scheme id is currently `1`. + ## `EthAddress` + Represents an Ethereum address. + ## `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. + This is an informational Solidity event definition and isn't an actual type provided in the SDK. ```solidity event Announcement( @@ -28,5 +32,89 @@ Glossary of types in the Stealth Address SDK. ); ``` + ## `AnnouncementArgs` + + The arguments used to announce a stealth address. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/getAnnouncements/types.ts#L6) + + ## `AnnouncementLog` + + The log data associated with the `Announce` event. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/getAnnouncements/types.ts#L12) + + ## `BlockType` + + A block number as `bigint` or block tag. + + ```ts + bigint | "latest" | "earliest" | "pending" | "safe" | "finalized"; + ``` + + ## `clientParams` + + When passing in the `clientParams` object to an action, the following properties are required: + + - `chainId`: The [chain ID](/#valid_chain_ids) of the network. + - `rpcUrl`: The RPC URL of the network. + ## `EthAddress` + Represents an Ethereum address. + + ## `GetAnnouncementsForUserReturnType` + + The return type of the `getAnnouncementsForUser` action, which is an array of announcements relevant to the specified user. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/getAnnouncementsForUser/types.ts#L14) + + ## `GetAnnouncementsReturnType` + + The return type of the `getAnnouncements` action, which is an array of `Announce` event log data emitted from the `ERC5564Announcer` contract. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/getAnnouncements/types.ts#L27) + + ## `HexString` + + Signifies any length hexadecimal string, synonymous with `0x${string}` + + ## `PrepareAnnounceArgs` + + The arguments used to prepare an announcement. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/prepareAnnounce/types.ts#L14) + + ## `PreparePayload` + + The prepared payload to send a transaction. This is the return type of the `prepare`-prefixed actions. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/types.ts#L9) + + ## `RegisterKeysOnBehalfArgs` + + The arguments used to register a stealth meta-address (keys) on behalf of a user. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/prepareRegisterKeysOnBehalf/types.ts#L5) + + ## `VALID_CHAIN_IDS` + + Valid chain IDs for the SDK. + + A valid chain id has deployed `ERC5564Announcer` and `ERC6538Registry` contracts. + + ## `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`. + + ## `WatchAnnouncementsForUserPollingOptions` + + The polling options used to watch for announcements relevant to the user. + + [See Type](https://github.com/ScopeLift/stealth-address-sdk/blob/main/src/lib/actions/watchAnnouncementsForUser/types.ts#L13) diff --git a/pages/SDK/stealth-client/_meta.json b/pages/SDK/stealth-client/_meta.json new file mode 100644 index 0000000..ca0a2a6 --- /dev/null +++ b/pages/SDK/stealth-client/_meta.json @@ -0,0 +1,3 @@ +{ + "index": "Overview" +} diff --git a/pages/SDK/stealth-client/index.mdx b/pages/SDK/stealth-client/index.mdx new file mode 100644 index 0000000..e48f6ef --- /dev/null +++ b/pages/SDK/stealth-client/index.mdx @@ -0,0 +1,68 @@ +# Stealth Client + +The stealth client provides a suite of actions that enable developers to handle various stealth address-related functionalities seamlessly. + +Some example actions include: + +**Announcement handling**: + +- `getAnnouncements`: retrieves stealth address announcements emitted from the `ERC5564Announcer` contract +- `watchAnnouncementsForUser`: monitors stealth transaction announcements for a specified user + +**Contract interaction preparation**: + +- `prepareAnnounce`: prepares the payload to call the `announce` function on the `ERC5564Announcer` contract +- `prepareRegisterKeys`: prepares the payload to call the `registerKeys` function call on the `ERC6538Registry` contract + +## Import + +```ts +import { createStealthClient } from "@scopelift/stealth-address-sdk"; +``` + +## Usage + +Initialize a Stealth Client with your desired Chain ID (e.g. 1 for Ethereum) and RPC URL. + +```ts +import { createStealthClient } from "@scopelift/stealth-address-sdk"; + +const stealthClient = createStealthClient({ + chainId, + rpcUrl, +}); +``` + +Then you can consume `StealthActions` from the `stealthClient` instance. + +```ts +const announcements = await stealthClient.getAnnouncements(...args); +``` + +## Parameters + +### chainId + +- **Type:** [`VALID_CHAIN_IDS`](../glossary/types.md#valid_chain_ids) + + The ephemeral public key from the announcement. + +```ts {2} +const stealthClient = createStealthClient({ + chainId, + rpcUrl, +}); +``` + +### rpcUrl + +- **Type:** `string` + + The RPC URL of the network that corresponds to the provided `chainId`. + +```ts {3} +const stealthClient = createStealthClient({ + chainId, + rpcUrl, +}); +``` From 017bf7c31feb29dddb2dddb4c1f65fc807c4acca Mon Sep 17 00:00:00 2001 From: garyghayrat Date: Mon, 6 May 2024 22:48:33 -0400 Subject: [PATCH 2/2] Remove repeated types --- pages/SDK/glossary/types.mdx | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/pages/SDK/glossary/types.mdx b/pages/SDK/glossary/types.mdx index 41488a8..3acf3ac 100644 --- a/pages/SDK/glossary/types.mdx +++ b/pages/SDK/glossary/types.mdx @@ -2,20 +2,6 @@ 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`. - - ## `EthAddress` - Represents an Ethereum address. - ## `Announce` The event emitted from the `announce` function call on the ERC-5564 contract.