;
85 | };
86 |
87 | export class PublicClientRequiredError extends Error {
88 | constructor(message = 'publicClient is required') {
89 | super(message);
90 | this.name = 'PublicClientRequiredError';
91 | Object.setPrototypeOf(this, PublicClientRequiredError.prototype);
92 | }
93 | }
94 |
--------------------------------------------------------------------------------
/src/lib/actions/prepareRegisterKeys/prepareRegisterKeys.test.ts:
--------------------------------------------------------------------------------
1 | import { beforeAll, describe, expect, test } from 'bun:test';
2 | import type { Address, Chain, TransactionReceipt } from 'viem';
3 | import {
4 | type PrepareRegisterKeysParams,
5 | VALID_SCHEME_ID,
6 | parseStealthMetaAddressURI
7 | } from '../../..';
8 | import setupTestEnv from '../../helpers/test/setupTestEnv';
9 | import setupTestStealthKeys from '../../helpers/test/setupTestStealthKeys';
10 | import setupTestWallet from '../../helpers/test/setupTestWallet';
11 | import type { SuperWalletClient } from '../../helpers/types';
12 | import type { StealthActions } from '../../stealthClient/types';
13 | import { PrepareError } from '../types';
14 |
15 | describe('prepareRegisterKeys', () => {
16 | let stealthClient: StealthActions;
17 | let ERC6538Address: Address;
18 | let walletClient: SuperWalletClient;
19 | let account: Address | undefined;
20 | let chain: Chain | undefined;
21 |
22 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
23 | const { stealthMetaAddressURI } = setupTestStealthKeys(schemeId);
24 | const stealthMetaAddressToRegister = parseStealthMetaAddressURI({
25 | stealthMetaAddressURI,
26 | schemeId
27 | });
28 |
29 | // Prepare payload args
30 | let prepareArgs: PrepareRegisterKeysParams;
31 | // Transaction receipt for writing to the contract with the prepared payload
32 | let res: TransactionReceipt;
33 |
34 | beforeAll(async () => {
35 | // Set up the test environment
36 | ({ stealthClient, ERC6538Address } = await setupTestEnv());
37 | walletClient = await setupTestWallet();
38 | account = walletClient.account?.address;
39 | if (!account) throw new Error('No account found');
40 | chain = walletClient.chain;
41 | if (!chain) throw new Error('No chain found');
42 |
43 | prepareArgs = {
44 | account,
45 | ERC6538Address,
46 | schemeId,
47 | stealthMetaAddress: stealthMetaAddressToRegister
48 | } satisfies PrepareRegisterKeysParams;
49 | const prepared = await stealthClient.prepareRegisterKeys(prepareArgs);
50 |
51 | // Prepare tx using viem and the prepared payload
52 | const request = await walletClient.prepareTransactionRequest({
53 | ...prepared,
54 | chain,
55 | account
56 | });
57 |
58 | const hash = await walletClient.sendTransaction({
59 | ...request,
60 | chain,
61 | account
62 | });
63 |
64 | res = await walletClient.waitForTransactionReceipt({ hash });
65 | });
66 | test('should throw PrepareError when given invalid contract address', () => {
67 | const invalidERC6538Address = '0xinvalid';
68 | expect(
69 | stealthClient.prepareRegisterKeys({
70 | ...prepareArgs,
71 | ERC6538Address: invalidERC6538Address
72 | })
73 | ).rejects.toBeInstanceOf(PrepareError);
74 | });
75 |
76 | test('should successfully register a stealth meta-address using the prepare payload', () => {
77 | expect(res.status).toEqual('success');
78 | });
79 | });
80 |
--------------------------------------------------------------------------------
/src/lib/actions/index.ts:
--------------------------------------------------------------------------------
1 | import type { StealthActions } from '../stealthClient/types';
2 | import getAnnouncements from './getAnnouncements/getAnnouncements';
3 | import getAnnouncementsForUser from './getAnnouncementsForUser/getAnnouncementsForUser';
4 | import getAnnouncementsUsingSubgraph from './getAnnouncementsUsingSubgraph/getAnnouncementsUsingSubgraph';
5 | import getStealthMetaAddress from './getStealthMetaAddress/getStealthMetaAddress';
6 | import prepareAnnounce from './prepareAnnounce/prepareAnnounce';
7 | import prepareRegisterKeys from './prepareRegisterKeys/prepareRegisterKeys';
8 | import prepareRegisterKeysOnBehalf from './prepareRegisterKeysOnBehalf/prepareRegisterKeysOnBehalf';
9 | import watchAnnouncementsForUser from './watchAnnouncementsForUser/watchAnnouncementsForUser';
10 | export { default as getAnnouncements } from './getAnnouncements/getAnnouncements';
11 | export { default as getAnnouncementsForUser } from './getAnnouncementsForUser/getAnnouncementsForUser';
12 | export { default as getAnnouncementsUsingSubgraph } from './getAnnouncementsUsingSubgraph/getAnnouncementsUsingSubgraph';
13 | export { default as getStealthMetaAddress } from './getStealthMetaAddress/getStealthMetaAddress';
14 | export { default as prepareAnnounce } from './prepareAnnounce/prepareAnnounce';
15 | export { default as prepareRegisterKeys } from './prepareRegisterKeys/prepareRegisterKeys';
16 | export { default as prepareRegisterKeysOnBehalf } from './prepareRegisterKeysOnBehalf/prepareRegisterKeysOnBehalf';
17 | export { default as watchAnnouncementsForUser } from './watchAnnouncementsForUser/watchAnnouncementsForUser';
18 |
19 | export {
20 | type AnnouncementArgs,
21 | type AnnouncementLog,
22 | type GetAnnouncementsParams,
23 | type GetAnnouncementsReturnType
24 | } from './getAnnouncements/types';
25 | export {
26 | type GetStealthMetaAddressParams,
27 | type GetStealthMetaAddressReturnType
28 | } from './getStealthMetaAddress/types';
29 | export {
30 | type GetAnnouncementsForUserParams,
31 | type GetAnnouncementsForUserReturnType
32 | } from './getAnnouncementsForUser/types';
33 | export {
34 | type GetAnnouncementsUsingSubgraphParams,
35 | type GetAnnouncementsUsingSubgraphReturnType
36 | } from './getAnnouncementsUsingSubgraph/types';
37 | export {
38 | type WatchAnnouncementsForUserParams,
39 | type WatchAnnouncementsForUserReturnType
40 | } from './watchAnnouncementsForUser/types';
41 | export {
42 | type PrepareAnnounceParams,
43 | type PrepareAnnounceReturnType
44 | } from './prepareAnnounce/types';
45 | export {
46 | type PrepareRegisterKeysParams,
47 | type PrepareRegisterKeysReturnType
48 | } from './prepareRegisterKeys/types';
49 | export {
50 | type PrepareRegisterKeysOnBehalfParams,
51 | type PrepareRegisterKeysOnBehalfReturnType
52 | } from './prepareRegisterKeysOnBehalf/types';
53 |
54 | export const actions: StealthActions = {
55 | getAnnouncements,
56 | getAnnouncementsForUser,
57 | getAnnouncementsUsingSubgraph,
58 | getStealthMetaAddress,
59 | prepareAnnounce,
60 | prepareRegisterKeys,
61 | prepareRegisterKeysOnBehalf,
62 | watchAnnouncementsForUser
63 | };
64 |
--------------------------------------------------------------------------------
/src/utils/crypto/test/checkStealthAddress.test.ts:
--------------------------------------------------------------------------------
1 | import { describe, expect, test } from 'bun:test';
2 | import { bytesToHex } from 'viem';
3 | import {
4 | VALID_SCHEME_ID,
5 | checkStealthAddress,
6 | generateStealthAddress,
7 | parseKeysFromStealthMetaAddress,
8 | parseStealthMetaAddressURI
9 | } from '..';
10 |
11 | describe('checkStealthAddress', () => {
12 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
13 | const stealthMetaAddressURI =
14 | 'st:eth:0x02f1f006a160b934c1d71479ce7d57f1c4ec10018230e35ca10ab65db68e8f037b0305d4725c7784262a38af11a9aef490b1307b82b17866f08d66c38db04c946ab1';
15 | const stealthMetaAddress = parseStealthMetaAddressURI({
16 | stealthMetaAddressURI,
17 | schemeId
18 | });
19 | const viewingPrivateKey =
20 | '0x2f8fcb2d1e06f52695e06a792b6d59c80a81ad70fc11b03b5236eed5cff09670';
21 |
22 | const { stealthAddress, ephemeralPublicKey, viewTag } =
23 | generateStealthAddress({
24 | stealthMetaAddressURI,
25 | schemeId
26 | });
27 |
28 | const { spendingPublicKey } = parseKeysFromStealthMetaAddress({
29 | stealthMetaAddress,
30 | schemeId
31 | });
32 |
33 | test('successfully identifies an announcement for the user', () => {
34 | const isForUser = checkStealthAddress({
35 | ephemeralPublicKey,
36 | schemeId,
37 | spendingPublicKey: bytesToHex(spendingPublicKey),
38 | userStealthAddress: stealthAddress,
39 | viewingPrivateKey,
40 | viewTag
41 | });
42 |
43 | expect(isForUser).toBe(true);
44 | });
45 |
46 | test('correctly rejects an announcement with a mismatched view tag', () => {
47 | const mismatchedViewTag = '0x123456'; // Some incorrect view tag
48 | const isForUser = checkStealthAddress({
49 | ephemeralPublicKey,
50 | schemeId,
51 | spendingPublicKey: bytesToHex(spendingPublicKey),
52 | userStealthAddress: stealthAddress,
53 | viewingPrivateKey,
54 | viewTag: mismatchedViewTag
55 | });
56 |
57 | expect(isForUser).toBe(false);
58 | });
59 |
60 | test('correctly rejects an announcement for a different stealth address', () => {
61 | const differentStealthAddress = '0xverynice'; // Some incorrect stealth address
62 | const isForUser = checkStealthAddress({
63 | ephemeralPublicKey,
64 | schemeId,
65 | spendingPublicKey: bytesToHex(spendingPublicKey),
66 | userStealthAddress: differentStealthAddress,
67 | viewingPrivateKey,
68 | viewTag
69 | });
70 |
71 | expect(isForUser).toBe(false);
72 | });
73 |
74 | test('matches addresses regardless of case', () => {
75 | // Test with different case variations
76 | const variations = [
77 | stealthAddress.toLowerCase(),
78 | stealthAddress.toUpperCase()
79 | ];
80 |
81 | for (const addressVariation of variations) {
82 | const result = checkStealthAddress({
83 | ephemeralPublicKey,
84 | schemeId,
85 | spendingPublicKey: bytesToHex(spendingPublicKey),
86 | viewingPrivateKey,
87 | userStealthAddress: addressVariation as `0x${string}`,
88 | viewTag
89 | });
90 |
91 | expect(result).toBe(true);
92 | }
93 | });
94 | });
95 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
2 |
3 | # Logs
4 |
5 | logs
6 | _.log
7 | npm-debug.log_
8 | yarn-debug.log*
9 | yarn-error.log*
10 | lerna-debug.log*
11 | .pnpm-debug.log*
12 |
13 | # Caches
14 |
15 | .cache
16 |
17 | # Diagnostic reports (https://nodejs.org/api/report.html)
18 |
19 | report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
20 |
21 | # Runtime data
22 |
23 | pids
24 | _.pid
25 | _.seed
26 | *.pid.lock
27 |
28 | # Directory for instrumented libs generated by jscoverage/JSCover
29 |
30 | lib-cov
31 |
32 | # Coverage directory used by tools like istanbul
33 |
34 | coverage
35 | *.lcov
36 |
37 | # nyc test coverage
38 |
39 | .nyc_output
40 |
41 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
42 |
43 | .grunt
44 |
45 | # Bower dependency directory (https://bower.io/)
46 |
47 | bower_components
48 |
49 | # node-waf configuration
50 |
51 | .lock-wscript
52 |
53 | # Compiled binary addons (https://nodejs.org/api/addons.html)
54 |
55 | build/Release
56 |
57 | # Dependency directories
58 |
59 | node_modules/
60 | jspm_packages/
61 |
62 | # Snowpack dependency directory (https://snowpack.dev/)
63 |
64 | web_modules/
65 |
66 | # TypeScript cache
67 |
68 | *.tsbuildinfo
69 |
70 | # Optional npm cache directory
71 |
72 | .npm
73 |
74 | # Optional eslint cache
75 |
76 | .eslintcache
77 |
78 | # Optional stylelint cache
79 |
80 | .stylelintcache
81 |
82 | # Microbundle cache
83 |
84 | .rpt2_cache/
85 | .rts2_cache_cjs/
86 | .rts2_cache_es/
87 | .rts2_cache_umd/
88 |
89 | # Optional REPL history
90 |
91 | .node_repl_history
92 |
93 | # Output of 'npm pack'
94 |
95 | *.tgz
96 |
97 | # Yarn Integrity file
98 |
99 | .yarn-integrity
100 |
101 | # dotenv environment variable files
102 |
103 | .env
104 | .env.development.local
105 | .env.test.local
106 | .env.production.local
107 | .env.local
108 |
109 | # parcel-bundler cache (https://parceljs.org/)
110 |
111 | .parcel-cache
112 |
113 | # Next.js build output
114 |
115 | .next
116 | out
117 |
118 | # Nuxt.js build / generate output
119 |
120 | .nuxt
121 | dist
122 |
123 | # Gatsby files
124 |
125 | # Comment in the public line in if your project uses Gatsby and not Next.js
126 |
127 | # https://nextjs.org/blog/next-9-1#public-directory-support
128 |
129 | # public
130 |
131 | # vuepress build output
132 |
133 | .vuepress/dist
134 |
135 | # vuepress v2.x temp and cache directory
136 |
137 | .temp
138 |
139 | # Docusaurus cache and generated files
140 |
141 | .docusaurus
142 |
143 | # Serverless directories
144 |
145 | .serverless/
146 |
147 | # FuseBox cache
148 |
149 | .fusebox/
150 |
151 | # DynamoDB Local files
152 |
153 | .dynamodb/
154 |
155 | # TernJS port file
156 |
157 | .tern-port
158 |
159 | # Stores VSCode versions used for testing VSCode extensions
160 |
161 | .vscode-test
162 |
163 | # yarn v2
164 |
165 | .yarn/cache
166 | .yarn/unplugged
167 | .yarn/build-state.yml
168 | .yarn/install-state.gz
169 | .pnp.*
170 |
171 | # IntelliJ based IDEs
172 | .idea
173 |
174 | # Finder (MacOS) folder config
175 | .DS_Store
176 |
--------------------------------------------------------------------------------
/src/utils/helpers/generateSignatureForRegisterKeysOnBehalf.ts:
--------------------------------------------------------------------------------
1 | import { readContract } from 'viem/actions';
2 | import { ERC6538RegistryAbi } from '../../lib';
3 | import {
4 | GenerateSignatureForRegisterKeysError,
5 | type GenerateSignatureForRegisterKeysParams
6 | } from './types';
7 |
8 | const DOMAIN_NAME = 'ERC6538Registry';
9 | const DOMAIN_VERSION = '1.0';
10 | const PRIMARY_TYPE = 'Erc6538RegistryEntry';
11 |
12 | const SIGNATURE_TYPES = {
13 | [PRIMARY_TYPE]: [
14 | { name: 'schemeId', type: 'uint256' },
15 | { name: 'stealthMetaAddress', type: 'bytes' },
16 | { name: 'nonce', type: 'uint256' }
17 | ]
18 | } as const;
19 |
20 | /**
21 | * Generates a typed signature for registering keys on behalf of a user (account) in the ERC6538 Registry.
22 | *
23 | * This function creates an EIP-712 compliant signature for the `registerKeysOnBehalf` function
24 | * in the ERC6538 Registry contract. It retrieves the current nonce for the account, prepares
25 | * the domain separator and message, and signs the data using the provided Viem wallet client.
26 | *
27 | * @param {GenerateSignatureForRegisterKeysParams} params - The parameters for generating the signature.
28 | * @returns {Promise<`0x${string}`>} A promise that resolves to the generated signature as a hexadecimal string.
29 | *
30 | * @throws {GenerateSignatureForRegisterKeysError} If the contract read fails or if the signing process encounters an issue.
31 | *
32 | * @example
33 | * const signature = await generateSignatureForRegisterKeysOnBehalf({
34 | * walletClient,
35 | * account: '0x1234...5678',
36 | * ERC6538Address: '0xabcd...ef01',
37 | * chainId: 1,
38 | * schemeId: 1,
39 | * stealthMetaAddressToRegister: '0x9876...5432'
40 | * });
41 | */
42 | async function generateSignatureForRegisterKeysOnBehalf({
43 | walletClient,
44 | account,
45 | ERC6538Address,
46 | chainId,
47 | schemeId,
48 | stealthMetaAddressToRegister
49 | }: GenerateSignatureForRegisterKeysParams): Promise<`0x${string}`> {
50 | try {
51 | // Get the registrant's current nonce for the signature
52 | const nonce = await readContract(walletClient, {
53 | address: ERC6538Address,
54 | abi: ERC6538RegistryAbi,
55 | functionName: 'nonceOf',
56 | args: [account]
57 | });
58 |
59 | // Prepare the signature domain
60 | const domain = {
61 | name: DOMAIN_NAME,
62 | version: DOMAIN_VERSION,
63 | chainId,
64 | verifyingContract: ERC6538Address
65 | } as const;
66 |
67 | const message = {
68 | schemeId: BigInt(schemeId),
69 | stealthMetaAddress: stealthMetaAddressToRegister,
70 | nonce
71 | };
72 |
73 | const signature = await walletClient.signTypedData({
74 | account,
75 | primaryType: PRIMARY_TYPE,
76 | domain,
77 | types: SIGNATURE_TYPES,
78 | message
79 | });
80 |
81 | return signature;
82 | } catch (error) {
83 | console.error('Error generating signature:', error);
84 | throw new GenerateSignatureForRegisterKeysError(
85 | 'Failed to generate signature for registerKeysOnBehalf',
86 | error
87 | );
88 | }
89 | }
90 |
91 | export default generateSignatureForRegisterKeysOnBehalf;
92 |
--------------------------------------------------------------------------------
/examples/generateDeterministicStealthMetaAddress/index.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 | import ReactDOM from 'react-dom/client';
3 | import { type Address, createWalletClient, custom } from 'viem';
4 | import { sepolia } from 'viem/chains';
5 | import 'viem/window';
6 |
7 | import { generateStealthMetaAddressFromSignature } from '@scopelift/stealth-address-sdk';
8 |
9 | /**
10 | * This React component demonstrates the process of generating a stealth meta-address deterministically using a user-signed message
11 | * It's deterministic in that the same stealth meta-address is generated for the same user, chain id, and message
12 | * It utilizes Viem's walletClient for wallet interaction
13 | *
14 | * @returns The component renders a button to first handle connecting the wallet, and a subsequent button to handle stealth meta-address generation
15 | *
16 | * @example
17 | * To run the development server: `bun run dev`.
18 | */
19 | const Example = () => {
20 | // Initialize your configuration
21 | const chain = sepolia; // Example Viem chain
22 |
23 | if (!window.ethereum) throw new Error('window.ethereum is required');
24 |
25 | // Initialize Viem wallet client if using Viem
26 | const walletClient = createWalletClient({
27 | chain,
28 | transport: custom(window.ethereum)
29 | });
30 |
31 | // State
32 | const [account, setAccount] = useState();
33 | const [stealthMetaAddress, setStealthMetaAddress] = useState<`0x${string}`>();
34 |
35 | const connect = async () => {
36 | const [address] = await walletClient.requestAddresses();
37 | setAccount(address);
38 | };
39 |
40 | const signMessage = async () => {
41 | // An example message to sign for generating the stealth meta-address
42 | // Usually this message includes the chain id to mitigate replay attacks across different chains
43 | // The message that is signed should clearly communicate to the user what they are signing and why
44 | const MESSAGE_TO_SIGN = `Generate Stealth Meta-Address on ${chain.id} chain`;
45 |
46 | if (!account) throw new Error('A connected account is required');
47 |
48 | const signature = await walletClient.signMessage({
49 | account,
50 | message: MESSAGE_TO_SIGN
51 | });
52 |
53 | return signature;
54 | };
55 |
56 | const handleSignAndGenStealthMetaAddress = async () => {
57 | const signature = await signMessage();
58 | const stealthMetaAddress =
59 | generateStealthMetaAddressFromSignature(signature);
60 |
61 | setStealthMetaAddress(stealthMetaAddress);
62 | };
63 |
64 | if (account)
65 | return (
66 | <>
67 | {!stealthMetaAddress ? (
68 |
71 | ) : (
72 | Stealth Meta-Address: {stealthMetaAddress}
73 | )}
74 | Connected: {account}
75 |
76 | );
77 |
78 | return (
79 |
82 | );
83 | };
84 |
85 | ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
86 |
87 | );
88 |
--------------------------------------------------------------------------------
/src/lib/actions/getAnnouncementsUsingSubgraph/getAnnouncementsUsingSubgraph.ts:
--------------------------------------------------------------------------------
1 | import { GraphQLClient } from 'graphql-request';
2 | import type { AnnouncementLog } from '../getAnnouncements/types';
3 | import {
4 | convertSubgraphEntityToAnnouncementLog,
5 | fetchPages
6 | } from './subgraphHelpers';
7 | import {
8 | GetAnnouncementsUsingSubgraphError,
9 | type GetAnnouncementsUsingSubgraphParams,
10 | type GetAnnouncementsUsingSubgraphReturnType,
11 | type SubgraphAnnouncementEntity
12 | } from './types';
13 |
14 | /**
15 | * Fetches announcement data from a specified subgraph URL.
16 | *
17 | * Supports filtering results based on a filter string that looks like:
18 | * "
19 | * blockNumber_gte: 123456789
20 | * caller: "0x123456789"
21 | * "
22 | *
23 | * `pageSize` can also be adjusted to optimize performance and/or align with the subgraph's pagination limits.
24 | * The default value is 1000, which is a common maximum allowed by the subgraph providers.
25 | * If the subgraph provider has a higher limit, it can be adjusted accordingly.
26 | *
27 | * @param {Object} params - The parameters for the function.
28 | * @param {string} params.subgraphUrl - The URL of the subgraph to query.
29 | * @param {string} [params.filter=''] - Optional filter string for the query.
30 | * @param {number} [params.pageSize=1000] - Number of items to fetch per page.
31 | *
32 | * @returns {Promise} A promise that resolves to an array of AnnouncementLog objects.
33 | * The return value here is the same as the `getAnnouncements` function to be able to seamlessly fallback to fetching via logs
34 | * if the subgraph is not available.
35 | *
36 | * @throws {GetAnnouncementsUsingSubgraphError} If there's an issue fetching the announcements.
37 | */
38 | async function getAnnouncementsUsingSubgraph({
39 | subgraphUrl,
40 | filter = '',
41 | pageSize = 1000
42 | }: GetAnnouncementsUsingSubgraphParams): Promise {
43 | const client = new GraphQLClient(subgraphUrl);
44 | const gqlQuery = `
45 | query GetAnnouncements($first: Int, $id_lt: ID) {
46 | announcements(
47 | where: { __WHERE_CLAUSE__ }
48 | first: $first,
49 | orderBy: id,
50 | orderDirection: desc
51 | ) {
52 | id
53 | blockNumber
54 | blockHash
55 | caller
56 | data
57 | ephemeralPubKey
58 | logIndex
59 | metadata
60 | removed
61 | schemeId
62 | stealthAddress
63 | topics
64 | transactionHash
65 | transactionIndex
66 | }
67 | }
68 | `;
69 |
70 | const allAnnouncements: AnnouncementLog[] = [];
71 |
72 | try {
73 | for await (const batch of fetchPages({
74 | client,
75 | gqlQuery,
76 | pageSize,
77 | filter,
78 | entity: 'announcements'
79 | })) {
80 | allAnnouncements.push(
81 | ...batch.map(convertSubgraphEntityToAnnouncementLog)
82 | );
83 | }
84 | } catch (error) {
85 | throw new GetAnnouncementsUsingSubgraphError(
86 | 'Failed to fetch announcements from the subgraph',
87 | error
88 | );
89 | }
90 |
91 | return allAnnouncements;
92 | }
93 |
94 | export default getAnnouncementsUsingSubgraph;
95 |
--------------------------------------------------------------------------------
/src/utils/helpers/test/generateSignatureForRegisterKeysOnBehalf.test.ts:
--------------------------------------------------------------------------------
1 | import { beforeAll, describe, expect, test } from 'bun:test';
2 | import type { WalletClient } from 'viem';
3 | import { signMessage } from 'viem/actions';
4 | import setupTestEnv from '../../../lib/helpers/test/setupTestEnv';
5 | import setupTestWallet from '../../../lib/helpers/test/setupTestWallet';
6 | import type { VALID_CHAIN_IDS } from '../../../lib/helpers/types';
7 | import { VALID_SCHEME_ID } from '../../crypto';
8 | import generateSignatureForRegisterKeysOnBehalf from '../generateSignatureForRegisterKeysOnBehalf';
9 | import generateStealthMetaAddressFromSignature from '../generateStealthMetaAddressFromSignature';
10 | import { GenerateSignatureForRegisterKeysError } from '../types';
11 |
12 | describe('generateSignatureForRegisterKeysOnBehalf', () => {
13 | let params: Parameters[0];
14 | let walletClient: WalletClient;
15 |
16 | beforeAll(async () => {
17 | walletClient = await setupTestWallet();
18 | const { ERC6538Address } = await setupTestEnv();
19 | const account = walletClient.account;
20 | const chainId = walletClient.chain?.id as VALID_CHAIN_IDS | undefined;
21 | if (!account) throw new Error('No account found');
22 | if (!chainId) throw new Error('No chain found');
23 |
24 | const signatureForStealthMetaAddress = await signMessage(walletClient, {
25 | account,
26 | message:
27 | 'Sign this message to generate your stealth address keys.\nChain ID: 31337'
28 | });
29 |
30 | const stealthMetaAddressToRegister =
31 | generateStealthMetaAddressFromSignature(signatureForStealthMetaAddress);
32 |
33 | params = {
34 | walletClient,
35 | account: account.address,
36 | ERC6538Address,
37 | chainId,
38 | schemeId: VALID_SCHEME_ID.SCHEME_ID_1,
39 | stealthMetaAddressToRegister
40 | };
41 | });
42 |
43 | test('should generate signature successfully', async () => {
44 | const result = await generateSignatureForRegisterKeysOnBehalf(params);
45 | expect(result).toBeTypeOf('string');
46 | expect(result.startsWith('0x')).toBe(true);
47 | });
48 |
49 | test('should throw GenerateSignatureForRegisterKeysError when contract read fails', async () => {
50 | const invalidParams = {
51 | ...params,
52 | ERC6538Address:
53 | '0x1234567890123456789012345678901234567890' as `0x${string}`
54 | };
55 |
56 | expect(
57 | generateSignatureForRegisterKeysOnBehalf(invalidParams)
58 | ).rejects.toBeInstanceOf(GenerateSignatureForRegisterKeysError);
59 | });
60 |
61 | test('should throw GenerateSignatureForRegisterKeysError when signing fails', async () => {
62 | // Create a wallet client that will fail on signTypedData
63 | const failingWalletClient = {
64 | ...walletClient,
65 | signTypedData: async () => {
66 | throw new Error('Signing failed');
67 | }
68 | } as WalletClient;
69 |
70 | const failingParams = {
71 | ...params,
72 | walletClient: failingWalletClient
73 | };
74 |
75 | expect(
76 | generateSignatureForRegisterKeysOnBehalf(failingParams)
77 | ).rejects.toBeInstanceOf(GenerateSignatureForRegisterKeysError);
78 | });
79 | });
80 |
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on:
3 | workflow_dispatch:
4 | pull_request:
5 | push:
6 | branches:
7 | - main
8 | jobs:
9 | build:
10 | runs-on: ubuntu-latest
11 | steps:
12 | - uses: actions/checkout@v4
13 | - name: Install Bun
14 | uses: oven-sh/setup-bun@v1
15 | - name: Build
16 | run: |
17 | bun install
18 | bun run build
19 | test:
20 | runs-on: ubuntu-latest
21 | environment: Testing All Networks
22 | steps:
23 | - uses: actions/checkout@v4
24 | - name: Install Foundry
25 | uses: foundry-rs/foundry-toolchain@v1
26 | - name: Install Bun
27 | uses: oven-sh/setup-bun@v1
28 | - name: Start anvil node
29 | run: anvil &
30 | - name: Run tests
31 | env:
32 | SUBGRAPH_URL_PREFIX: ${{ secrets.SUBGRAPH_URL_PREFIX }}
33 | SUBGRAPH_NAME_ARBITRUM_ONE: ${{ secrets.SUBGRAPH_NAME_ARBITRUM_ONE }}
34 | SUBGRAPH_NAME_ARBITRUM_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_ARBITRUM_SEPOLIA }}
35 | SUBGRAPH_NAME_BASE: ${{ secrets.SUBGRAPH_NAME_BASE }}
36 | SUBGRAPH_NAME_BASE_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_BASE_SEPOLIA }}
37 | SUBGRAPH_NAME_HOLESKY: ${{ secrets.SUBGRAPH_NAME_HOLESKY }}
38 | SUBGRAPH_NAME_MAINNET: ${{ secrets.SUBGRAPH_NAME_MAINNET }}
39 | SUBGRAPH_NAME_MATIC: ${{ secrets.SUBGRAPH_NAME_MATIC }}
40 | SUBGRAPH_NAME_OPTIMISM: ${{ secrets.SUBGRAPH_NAME_OPTIMISM }}
41 | SUBGRAPH_NAME_OPTIMISM_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_OPTIMISM_SEPOLIA }}
42 | SUBGRAPH_NAME_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_SEPOLIA }}
43 | run: |
44 | bun install
45 | bun test
46 | coverage:
47 | runs-on: ubuntu-latest
48 | environment: Testing All Networks
49 | steps:
50 | - uses: actions/checkout@v4
51 | - name: Install Foundry
52 | uses: foundry-rs/foundry-toolchain@v1
53 | - name: Install Bun
54 | uses: oven-sh/setup-bun@v1
55 | - name: Start anvil node
56 | run: anvil &
57 | - name: Run test coverage
58 | env:
59 | SUBGRAPH_URL_PREFIX: ${{ secrets.SUBGRAPH_URL_PREFIX }}
60 | SUBGRAPH_NAME_ARBITRUM_ONE: ${{ secrets.SUBGRAPH_NAME_ARBITRUM_ONE }}
61 | SUBGRAPH_NAME_ARBITRUM_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_ARBITRUM_SEPOLIA }}
62 | SUBGRAPH_NAME_BASE: ${{ secrets.SUBGRAPH_NAME_BASE }}
63 | SUBGRAPH_NAME_BASE_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_BASE_SEPOLIA }}
64 | SUBGRAPH_NAME_HOLESKY: ${{ secrets.SUBGRAPH_NAME_HOLESKY }}
65 | SUBGRAPH_NAME_MAINNET: ${{ secrets.SUBGRAPH_NAME_MAINNET }}
66 | SUBGRAPH_NAME_MATIC: ${{ secrets.SUBGRAPH_NAME_MATIC }}
67 | SUBGRAPH_NAME_OPTIMISM: ${{ secrets.SUBGRAPH_NAME_OPTIMISM }}
68 | SUBGRAPH_NAME_OPTIMISM_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_OPTIMISM_SEPOLIA }}
69 | SUBGRAPH_NAME_SEPOLIA: ${{ secrets.SUBGRAPH_NAME_SEPOLIA }}
70 | run: |
71 | bun install
72 | bun test --coverage
73 | check:
74 | runs-on: ubuntu-latest
75 | steps:
76 | - uses: actions/checkout@v4
77 | - name: Install Bun
78 | uses: oven-sh/setup-bun@v1
79 | - name: Check
80 | run: |
81 | bun install
82 | bun run check
83 |
--------------------------------------------------------------------------------
/src/lib/actions/prepareRegisterKeysOnBehalf/prepareRegisterKeysOnBehalf.test.ts:
--------------------------------------------------------------------------------
1 | import { beforeAll, describe, expect, test } from 'bun:test';
2 | import type { Address, TransactionReceipt } from 'viem';
3 | import {
4 | VALID_SCHEME_ID,
5 | generateSignatureForRegisterKeysOnBehalf,
6 | parseStealthMetaAddressURI
7 | } from '../../..';
8 | import setupTestEnv from '../../helpers/test/setupTestEnv';
9 | import setupTestStealthKeys from '../../helpers/test/setupTestStealthKeys';
10 | import setupTestWallet from '../../helpers/test/setupTestWallet';
11 | import type { StealthActions } from '../../stealthClient/types';
12 | import { PrepareError } from '../types';
13 | import type { RegisterKeysOnBehalfArgs } from './types';
14 |
15 | describe('prepareRegisterKeysOnBehalf', () => {
16 | let stealthClient: StealthActions;
17 | let account: Address | undefined;
18 | let args: RegisterKeysOnBehalfArgs;
19 |
20 | // Transaction receipt for writing to the contract with the prepared payload
21 | let res: TransactionReceipt;
22 |
23 | beforeAll(async () => {
24 | const {
25 | stealthClient: client,
26 | ERC6538Address,
27 | chainId
28 | } = await setupTestEnv();
29 | stealthClient = client;
30 | const walletClient = await setupTestWallet();
31 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
32 | const { stealthMetaAddressURI } = setupTestStealthKeys(schemeId);
33 | const stealthMetaAddressToRegister = parseStealthMetaAddressURI({
34 | stealthMetaAddressURI,
35 | schemeId
36 | });
37 | account = walletClient.account?.address;
38 | if (!account) throw new Error('No account found');
39 | const chain = walletClient.chain;
40 | if (!chain) throw new Error('No chain found');
41 |
42 | const signature = await generateSignatureForRegisterKeysOnBehalf({
43 | walletClient,
44 | account,
45 | ERC6538Address,
46 | chainId,
47 | schemeId,
48 | stealthMetaAddressToRegister
49 | });
50 |
51 | args = {
52 | registrant: account,
53 | schemeId,
54 | stealthMetaAddress: stealthMetaAddressToRegister,
55 | signature
56 | } satisfies RegisterKeysOnBehalfArgs;
57 |
58 | const prepared = await stealthClient.prepareRegisterKeysOnBehalf({
59 | account,
60 | ERC6538Address,
61 | args
62 | });
63 |
64 | // Prepare tx using viem and the prepared payload
65 | const request = await walletClient.prepareTransactionRequest({
66 | ...prepared,
67 | chain,
68 | account
69 | });
70 |
71 | const hash = await walletClient.sendTransaction({
72 | ...request,
73 | chain,
74 | account
75 | });
76 |
77 | res = await walletClient.waitForTransactionReceipt({ hash });
78 | });
79 |
80 | test('should throw PrepareError when given invalid contract address', () => {
81 | if (!account) throw new Error('No account found');
82 |
83 | const invalidERC6538Address = '0xinvalid';
84 |
85 | expect(
86 | stealthClient.prepareRegisterKeysOnBehalf({
87 | account,
88 | ERC6538Address: invalidERC6538Address,
89 | args
90 | })
91 | ).rejects.toBeInstanceOf(PrepareError);
92 | });
93 |
94 | test('should successfully register a stealth meta-address on behalf using the prepare payload', () => {
95 | expect(res.status).toEqual('success');
96 | });
97 | });
98 |
--------------------------------------------------------------------------------
/examples/prepareRegisterKeys/index.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 | import ReactDOM from 'react-dom/client';
3 | import { type Address, createWalletClient, custom } from 'viem';
4 | import { sepolia } from 'viem/chains';
5 | import 'viem/window';
6 |
7 | import {
8 | ERC6538_CONTRACT_ADDRESS,
9 | VALID_SCHEME_ID,
10 | createStealthClient,
11 | parseStealthMetaAddressURI
12 | } from '@scopelift/stealth-address-sdk';
13 |
14 | /**
15 | * This React component demonstrates the process of connecting to a wallet and registering a stealth meta-address.
16 | * It utilizes Viem's walletClient for wallet interaction and the stealth-address-sdk for stealth address operations.
17 | *
18 | * @returns The component renders a button to connect the wallet and announce the stealth address.
19 | *
20 | * @example
21 | * To run this example, ensure you have set up your environment variables VITE_RPC_URL and VITE_STEALTH_META_ADDRESS_URI.
22 | * Run the development server using Vite, `vite run dev`.
23 | */
24 | const Example = () => {
25 | // Initialize your environment variables or configuration
26 | const chainId = 11155111; // Example chain ID
27 | const rpcUrl = import.meta.env.VITE_RPC_URL; // Your Ethereum RPC URL
28 | if (!rpcUrl) throw new Error('VITE_RPC_URL is required');
29 |
30 | // Example URI; see the getStealthMetaAddress example and generateRandomStealthMetaAddress helper for more details
31 | const stealthMetaAddressURI = import.meta.env.VITE_STEALTH_META_ADDRESS_URI;
32 | if (!stealthMetaAddressURI)
33 | throw new Error('VITE_STEALTH_META_ADDRESS_URI is required');
34 |
35 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
36 | const stealthMetaAddressToRegister = parseStealthMetaAddressURI({
37 | stealthMetaAddressURI,
38 | schemeId
39 | });
40 | const chain = sepolia; // Example Viem chain
41 |
42 | if (!window.ethereum) throw new Error('window.ethereum is required');
43 |
44 | // Initialize Viem wallet client if using Viem
45 | const walletClient = createWalletClient({
46 | chain,
47 | transport: custom(window.ethereum)
48 | });
49 |
50 | // Initialize the stealth client with your RPC URL and chain ID
51 | const stealthClient = createStealthClient({ rpcUrl, chainId });
52 | const [account, setAccount] = useState();
53 |
54 | const connect = async () => {
55 | const [address] = await walletClient.requestAddresses();
56 | setAccount(address);
57 | };
58 |
59 | const registerKeys = async () => {
60 | if (!account) return;
61 |
62 | // Prepare the registerKeys payload
63 | const preparedPayload = await stealthClient.prepareRegisterKeys({
64 | account,
65 | ERC6538Address: ERC6538_CONTRACT_ADDRESS,
66 | schemeId,
67 | stealthMetaAddress: stealthMetaAddressToRegister
68 | });
69 |
70 | await walletClient.sendTransaction({
71 | ...preparedPayload
72 | });
73 | };
74 |
75 | if (account)
76 | return (
77 | <>
78 | Connected: {account}
79 |
82 |
83 | );
84 | return (
85 |
88 | );
89 | };
90 |
91 | ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
92 |
93 | );
94 |
--------------------------------------------------------------------------------
/examples/prepareRegisterKeysOnBehalf/index.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 | import ReactDOM from 'react-dom/client';
3 | import { type Address, createWalletClient, custom } from 'viem';
4 | import { sepolia } from 'viem/chains';
5 | import 'viem/window';
6 |
7 | import {
8 | ERC6538_CONTRACT_ADDRESS,
9 | VALID_SCHEME_ID,
10 | createStealthClient,
11 | parseStealthMetaAddressURI
12 | } from '@scopelift/stealth-address-sdk';
13 |
14 | /**
15 | * This React component demonstrates the process of connecting to a wallet and registering a stealth meta-address.
16 | * It utilizes Viem's walletClient for wallet interaction and the stealth-address-sdk for stealth address operations.
17 | *
18 | * @returns The component renders a button to connect the wallet and announce the stealth address.
19 | *
20 | * @example
21 | * To run this example, ensure you have set up your environment variables VITE_RPC_URL and VITE_STEALTH_META_ADDRESS_URI.
22 | * Run the development server using Vite, `vite run dev`.
23 | */
24 | const Example = () => {
25 | // Initialize your environment variables or configuration
26 | const chainId = 11155111; // Example chain ID
27 | const rpcUrl = import.meta.env.VITE_RPC_URL; // Your Ethereum RPC URL
28 | if (!rpcUrl) throw new Error('VITE_RPC_URL is required');
29 |
30 | // Example URI; see the getStealthMetaAddress example and generateRandomStealthMetaAddress helper for more details
31 | const stealthMetaAddressURI = import.meta.env.VITE_STEALTH_META_ADDRESS_URI;
32 | if (!stealthMetaAddressURI)
33 | throw new Error('VITE_STEALTH_META_ADDRESS_URI is required');
34 |
35 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
36 | const stealthMetaAddressToRegister = parseStealthMetaAddressURI({
37 | stealthMetaAddressURI,
38 | schemeId
39 | });
40 | const chain = sepolia; // Example Viem chain
41 |
42 | if (!window.ethereum) throw new Error('window.ethereum is required');
43 |
44 | // Initialize Viem wallet client if using Viem
45 | const walletClient = createWalletClient({
46 | chain,
47 | transport: custom(window.ethereum)
48 | });
49 |
50 | // Initialize the stealth client with your RPC URL and chain ID
51 | const stealthClient = createStealthClient({ rpcUrl, chainId });
52 | const [account, setAccount] = useState();
53 |
54 | const connect = async () => {
55 | const [address] = await walletClient.requestAddresses();
56 | setAccount(address);
57 | };
58 |
59 | const registerKeysOnBehalf = async () => {
60 | if (!account) return;
61 |
62 | // Prepare the registerKeys payload
63 | const preparedPayload = await stealthClient.prepareRegisterKeysOnBehalf({
64 | account, // Your wallet address
65 | ERC6538Address: ERC6538_CONTRACT_ADDRESS,
66 | args: {
67 | registrant: '0x', // Add the registrant address here
68 | schemeId,
69 | stealthMetaAddress: stealthMetaAddressToRegister,
70 | signature: '0x' // Add the signature here
71 | }
72 | });
73 |
74 | await walletClient.sendTransaction({
75 | ...preparedPayload
76 | });
77 | };
78 |
79 | if (account)
80 | return (
81 | <>
82 | Connected: {account}
83 |
86 |
87 | );
88 | return (
89 |
92 | );
93 | };
94 |
95 | ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
96 |
97 | );
98 |
--------------------------------------------------------------------------------
/examples/prepareAnnounce/index.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 | import ReactDOM from 'react-dom/client';
3 | import { type Address, createWalletClient, custom } from 'viem';
4 | import { sepolia } from 'viem/chains';
5 | import 'viem/window';
6 |
7 | import {
8 | ERC5564_CONTRACT_ADDRESS,
9 | VALID_SCHEME_ID,
10 | createStealthClient,
11 | generateStealthAddress
12 | } from '@scopelift/stealth-address-sdk';
13 |
14 | /**
15 | * This React component demonstrates the process of connecting to a wallet and announcing a stealth address.
16 | * It utilizes Viem's walletClient for wallet interaction and the stealth-address-sdk for stealth address operations.
17 | *
18 | * @returns The component renders a button to connect the wallet and announce the stealth address.
19 | *
20 | * @example
21 | * To run this example, ensure you have set up your environment variables VITE_RPC_URL and VITE_STEALTH_META_ADDRESS_URI.
22 | * Run the development server using Vite, `vite run dev`.
23 | */
24 | const Example = () => {
25 | // Initialize your environment variables or configuration
26 | const chainId = 11155111; // Example chain ID
27 | const rpcUrl = import.meta.env.VITE_RPC_URL; // Your Ethereum RPC URL
28 | if (!rpcUrl) throw new Error('VITE_RPC_URL is required');
29 |
30 | // Example URI; see the getStealthMetaAddress example and generateRandomStealthMetaAddress helper for more details
31 | const stealthMetaAddressURI = import.meta.env.VITE_STEALTH_META_ADDRESS_URI;
32 | if (!stealthMetaAddressURI)
33 | throw new Error('VITE_STEALTH_META_ADDRESS_URI is required');
34 |
35 | const chain = sepolia; // Example Viem chain
36 |
37 | if (!window.ethereum) throw new Error('window.ethereum is required');
38 |
39 | // Initialize Viem wallet client if using Viem
40 | const walletClient = createWalletClient({
41 | chain,
42 | transport: custom(window.ethereum)
43 | });
44 |
45 | // Initialize the stealth client with your RPC URL and chain ID
46 | const stealthClient = createStealthClient({ rpcUrl, chainId });
47 | const [account, setAccount] = useState();
48 |
49 | const connect = async () => {
50 | const [address] = await walletClient.requestAddresses();
51 | setAccount(address);
52 | };
53 |
54 | const announce = async () => {
55 | if (!account) return;
56 |
57 | // Generate stealth address details
58 | const { stealthAddress, ephemeralPublicKey, viewTag } =
59 | generateStealthAddress({
60 | stealthMetaAddressURI,
61 | schemeId: VALID_SCHEME_ID.SCHEME_ID_1 // Example scheme ID
62 | });
63 |
64 | // Prepare the announce payload
65 | const preparedPayload = await stealthClient.prepareAnnounce({
66 | account,
67 | ERC5564Address: ERC5564_CONTRACT_ADDRESS,
68 | args: {
69 | schemeId: VALID_SCHEME_ID.SCHEME_ID_1,
70 | stealthAddress,
71 | ephemeralPublicKey,
72 | metadata: viewTag
73 | }
74 | });
75 |
76 | await walletClient.sendTransaction({
77 | ...preparedPayload
78 | });
79 | };
80 |
81 | if (account)
82 | return (
83 | <>
84 | Connected: {account}
85 |
88 |
89 | );
90 | return (
91 |
94 | );
95 | };
96 |
97 | ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
98 |
99 | );
100 |
--------------------------------------------------------------------------------
/src/lib/helpers/logs.ts:
--------------------------------------------------------------------------------
1 | import {
2 | type Abi,
3 | type AbiEvent,
4 | type ContractEventName,
5 | type DecodeEventLogReturnType,
6 | type GetEventArgs,
7 | type Log,
8 | type PublicClient,
9 | decodeEventLog
10 | } from 'viem';
11 | import { getBlockNumber, getLogs } from 'viem/actions';
12 |
13 | /**
14 | * Parameters for fetching and decoding logs in chunks.
15 | * @template TAbi - The ABI type.
16 | */
17 | type FetchLogsParams = {
18 | /** An instance of the viem PublicClient. */
19 | publicClient: PublicClient;
20 | /** The ABI of the contract. */
21 | abi: TAbi;
22 | /** The name of the event to fetch logs for. */
23 | eventName: ContractEventName;
24 | /** The address of the contract. */
25 | address: `0x${string}`;
26 | /** Optional arguments to filter the logs. */
27 | args?: GetEventArgs>;
28 | /** The starting block number for the fetch. Defaults to 'earliest'. */
29 | fromBlock?: bigint | 'earliest';
30 | /** The ending block number for the fetch. Defaults to 'latest'. */
31 | toBlock?: bigint | 'latest';
32 | /** The number of blocks to query in each chunk. Defaults to 5000. */
33 | chunkSize?: number;
34 | };
35 |
36 | type FetchLogsReturnType = Array<
37 | DecodeEventLogReturnType> & Log
38 | >;
39 |
40 | /**
41 | * Fetches and decodes logs in chunks to handle potentially large range queries efficiently.
42 | *
43 | * @template TAbi - The ABI type.
44 | * @param {FetchLogsParams} params - The parameters for fetching logs in chunks.
45 | * @returns {Promise} - A flattened array of all logs fetched in chunks, including decoded event data.
46 | *
47 | * @example
48 | * const logs = await fetchLogsInChunks({
49 | * publicClient,
50 | * abi: myContractABI,
51 | * eventName: 'Transfer',
52 | * address: '0x...',
53 | * fromBlock: 1000000n,
54 | * toBlock: 2000000n,
55 | * chunkSize: 10000
56 | * });
57 | */
58 | export const fetchLogsInChunks = async ({
59 | publicClient,
60 | abi,
61 | eventName,
62 | address,
63 | args,
64 | fromBlock = 'earliest',
65 | toBlock = 'latest',
66 | chunkSize = 5000
67 | }: FetchLogsParams): Promise> => {
68 | const [start, end] = await Promise.all([
69 | fromBlock === 'earliest'
70 | ? 0n
71 | : typeof fromBlock === 'bigint'
72 | ? fromBlock
73 | : getBlockNumber(publicClient),
74 | toBlock === 'latest' ? getBlockNumber(publicClient) : toBlock
75 | ]);
76 |
77 | const eventAbi = abi.find(
78 | (item): item is AbiEvent => item.type === 'event' && item.name === eventName
79 | );
80 |
81 | if (!eventAbi) throw new Error(`Event ${eventName} not found in ABI`);
82 |
83 | const allLogs = [];
84 |
85 | for (
86 | let currentBlock = start;
87 | currentBlock <= end;
88 | currentBlock += BigInt(chunkSize)
89 | ) {
90 | const logs = await getLogs(publicClient, {
91 | address,
92 | event: eventAbi,
93 | args,
94 | fromBlock: currentBlock,
95 | toBlock: BigInt(
96 | Math.min(Number(currentBlock) + chunkSize - 1, Number(end))
97 | ),
98 | strict: true
99 | });
100 |
101 | allLogs.push(
102 | ...logs.map(log => ({
103 | ...log,
104 | ...decodeEventLog({
105 | abi,
106 | eventName,
107 | topics: log.topics,
108 | data: log.data
109 | })
110 | }))
111 | );
112 | }
113 |
114 | return allLogs;
115 | };
116 |
--------------------------------------------------------------------------------
/src/lib/helpers/test/setupTestEnv.test.ts:
--------------------------------------------------------------------------------
1 | import {
2 | afterAll,
3 | afterEach,
4 | beforeEach,
5 | describe,
6 | expect,
7 | mock,
8 | test
9 | } from 'bun:test';
10 | import { VALID_CHAINS } from '../types';
11 | import { LOCAL_ENDPOINT } from './setupTestEnv';
12 |
13 | describe('setupTestEnv with different environment configurations', () => {
14 | afterEach(() => {
15 | process.env.USE_FORK = undefined;
16 | process.env.RPC_URL = undefined;
17 | });
18 |
19 | test('should use local node endpoint url when USE_FORK is true and RPC_URL is defined', async () => {
20 | const exampleRpcUrl = 'http://example-rpc-url.com';
21 | process.env.USE_FORK = 'true';
22 | process.env.RPC_URL = exampleRpcUrl;
23 | const { getRpcUrl } = await import('./setupTestEnv');
24 |
25 | expect(getRpcUrl()).toBe(LOCAL_ENDPOINT);
26 | });
27 |
28 | test('throws error when USE_FORK is true and RPC_URL is not defined', async () => {
29 | process.env.USE_FORK = 'true';
30 | process.env.RPC_URL = undefined;
31 | const { getRpcUrl } = await import('./setupTestEnv');
32 |
33 | expect(getRpcUrl).toThrow('RPC_URL not defined in env');
34 | });
35 |
36 | test('should use local node endpoint when USE_FORK is not true', async () => {
37 | process.env.USE_FORK = 'false';
38 | const { getRpcUrl } = await import('./setupTestEnv');
39 |
40 | expect(getRpcUrl()).toBe(LOCAL_ENDPOINT);
41 | });
42 |
43 | test('should use the default foundry local endpoint when USE_FORK is not defined', async () => {
44 | process.env.USE_FORK = undefined;
45 | const { getRpcUrl } = await import('./setupTestEnv');
46 |
47 | expect(getRpcUrl()).toBe(LOCAL_ENDPOINT);
48 | });
49 | });
50 |
51 | describe('getValidChainId validation', () => {
52 | const { getValidChainId } = require('./setupTestEnv');
53 |
54 | test('valid chain ID returns correctly', () => {
55 | const validChain = VALID_CHAINS[11155111];
56 |
57 | expect(getValidChainId(validChain.id)).toBe(validChain.id);
58 | });
59 |
60 | test('invalid chain ID throws error', () => {
61 | const invalidChainId = 9999;
62 | expect(() => getValidChainId(invalidChainId)).toThrow(
63 | `Invalid chain ID: ${invalidChainId}`
64 | );
65 | });
66 | });
67 |
68 | describe('fetchChainId', async () => {
69 | const { fetchChainId } = await import('./setupTestEnv');
70 |
71 | beforeEach(() => {
72 | // Set the env vars, which are needed to use a fork and not default to using foundry chain id
73 | process.env.USE_FORK = 'true';
74 | process.env.RPC_URL = 'http://example-rpc-url.com';
75 | });
76 |
77 | afterAll(() => {
78 | process.env.USE_FORK = undefined;
79 | process.env.RPC_URL = undefined;
80 | });
81 |
82 | test('successful fetch returns chain ID', async () => {
83 | mock.module('./setupTestEnv', () => ({
84 | fetchJson: () =>
85 | Promise.resolve({
86 | result: '0x1'
87 | })
88 | }));
89 |
90 | const chainId = await fetchChainId();
91 | expect(chainId).toBe(1); // '0x1' translates to 1
92 | });
93 |
94 | test('fetch failure throws error', async () => {
95 | mock.module('./setupTestEnv', () => ({
96 | fetchJson: () => Promise.reject(new Error('Network failure'))
97 | }));
98 |
99 | expect(fetchChainId()).rejects.toThrow('Failed to get the chain ID');
100 | });
101 |
102 | test('throws error when RPC_URL is not defined', async () => {
103 | process.env.RPC_URL = undefined;
104 |
105 | expect(fetchChainId).toThrow('RPC_URL not defined in env');
106 | });
107 | });
108 |
--------------------------------------------------------------------------------
/src/lib/stealthClient/createStealthClient.ts:
--------------------------------------------------------------------------------
1 | import { http, type PublicClient, createPublicClient } from 'viem';
2 | import { actions as stealthActions } from '../actions';
3 | import { getChain } from '../helpers/chains';
4 | import {
5 | type ClientParams,
6 | PublicClientRequiredError,
7 | type StealthClientInitParams,
8 | type StealthClientReturnType
9 | } from './types';
10 |
11 | /**
12 | * Creates a client for use in stealth address operations that align with ERC5564.
13 | *
14 | * @param {StealthClientInitParams} params - Parameters for initializing the stealth client, including chain ID and RPC URL.
15 | * @returns {StealthClientReturnType} - An object containing initialized stealth action functions.
16 | *
17 | * @example
18 | * import { createStealthClient } from 'stealth-address-sdk'
19 | *
20 | * const stealthClient = createStealthClient({
21 | * chainId,
22 | * rpcUrl,
23 | * })
24 | *
25 | * stealthClient.getAnnouncements({ params })
26 | */
27 | function createStealthClient({
28 | chainId,
29 | rpcUrl
30 | }: StealthClientInitParams): StealthClientReturnType {
31 | const chain = getChain(chainId);
32 |
33 | // Init viem client
34 | const publicClient = createPublicClient({
35 | chain,
36 | transport: http(rpcUrl)
37 | });
38 |
39 | const initializedActions: StealthClientReturnType = {
40 | getAnnouncements: params =>
41 | stealthActions.getAnnouncements({
42 | clientParams: { publicClient },
43 | ...params
44 | }),
45 | getAnnouncementsUsingSubgraph: params =>
46 | stealthActions.getAnnouncementsUsingSubgraph({
47 | ...params
48 | }),
49 | getStealthMetaAddress: params =>
50 | stealthActions.getStealthMetaAddress({
51 | clientParams: { publicClient },
52 | ...params
53 | }),
54 | getAnnouncementsForUser: params =>
55 | stealthActions.getAnnouncementsForUser({
56 | clientParams: { publicClient },
57 | ...params
58 | }),
59 | watchAnnouncementsForUser: params =>
60 | stealthActions.watchAnnouncementsForUser({
61 | clientParams: { publicClient },
62 | ...params
63 | }),
64 | prepareAnnounce: params =>
65 | stealthActions.prepareAnnounce({
66 | clientParams: { publicClient },
67 | ...params
68 | }),
69 | prepareRegisterKeys: params =>
70 | stealthActions.prepareRegisterKeys({
71 | clientParams: { publicClient },
72 | ...params
73 | }),
74 | prepareRegisterKeysOnBehalf: params =>
75 | stealthActions.prepareRegisterKeysOnBehalf({
76 | clientParams: { publicClient },
77 | ...params
78 | })
79 | };
80 |
81 | return initializedActions;
82 | }
83 |
84 | const handleViemPublicClient = (clientParams?: ClientParams): PublicClient => {
85 | if (!clientParams) {
86 | throw new PublicClientRequiredError(
87 | 'publicClient or chainId and rpcUrl must be provided'
88 | );
89 | }
90 |
91 | if ('publicClient' in clientParams) {
92 | return clientParams.publicClient;
93 | }
94 |
95 | // Type guard for the 'chainId' and 'rpcUrl' properties
96 | if ('chainId' in clientParams && 'rpcUrl' in clientParams) {
97 | try {
98 | return createPublicClient({
99 | chain: getChain(clientParams.chainId),
100 | transport: http(clientParams.rpcUrl)
101 | });
102 | } catch (error) {
103 | throw new PublicClientRequiredError(
104 | 'public client could not be created.'
105 | );
106 | }
107 | }
108 |
109 | throw new PublicClientRequiredError(
110 | 'Either publicClient or both chainId and rpcUrl must be provided'
111 | );
112 | };
113 |
114 | export { createStealthClient, handleViemPublicClient };
115 | export default createStealthClient;
116 |
--------------------------------------------------------------------------------
/src/lib/actions/getAnnouncements/getAnnouncements.test.ts:
--------------------------------------------------------------------------------
1 | import { beforeAll, describe, expect, test } from 'bun:test';
2 | import type { Account, Address } from 'viem';
3 | import {
4 | VALID_SCHEME_ID,
5 | generateRandomStealthMetaAddress,
6 | generateStealthAddress
7 | } from '../../..';
8 | import ERC556AnnouncerAbi from '../../abi/ERC5564Announcer';
9 | import setupTestEnv from '../../helpers/test/setupTestEnv';
10 | import setupTestWallet from '../../helpers/test/setupTestWallet';
11 | import type { SuperWalletClient } from '../../helpers/types';
12 | import type { StealthActions } from '../../stealthClient/types';
13 |
14 | describe('getAnnouncements', () => {
15 | let stealthClient: StealthActions;
16 | let walletClient: SuperWalletClient;
17 | let fromBlock: bigint;
18 | let ERC5564Address: Address;
19 | let account: Account | undefined;
20 |
21 | // Set up stealth address details
22 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
23 | const { stealthMetaAddressURI } = generateRandomStealthMetaAddress();
24 | const { stealthAddress, viewTag, ephemeralPublicKey } =
25 | generateStealthAddress({
26 | stealthMetaAddressURI,
27 | schemeId
28 | });
29 |
30 | // Set up the test environment and announce the stealth address
31 | beforeAll(async () => {
32 | const {
33 | stealthClient: client,
34 | ERC5564Address,
35 | ERC5564DeployBlock
36 | } = await setupTestEnv();
37 | walletClient = await setupTestWallet();
38 | stealthClient = client;
39 | fromBlock = ERC5564DeployBlock;
40 | account = walletClient.account;
41 |
42 | if (!account) throw new Error('No account found');
43 |
44 | // Announce the stealth address, ephemeral public key, and view tag
45 | const hash = await walletClient.writeContract({
46 | address: ERC5564Address,
47 | functionName: 'announce',
48 | args: [BigInt(schemeId), stealthAddress, ephemeralPublicKey, viewTag],
49 | abi: ERC556AnnouncerAbi,
50 | chain: walletClient.chain,
51 | account
52 | });
53 |
54 | // Wait for the transaction to be mined
55 | await walletClient.waitForTransactionReceipt({
56 | hash
57 | });
58 | });
59 |
60 | test('fetches announcements successfully', async () => {
61 | const announcements = await stealthClient.getAnnouncements({
62 | ERC5564Address,
63 | args: {},
64 | fromBlock
65 | });
66 |
67 | expect(announcements.length).toBeGreaterThan(0);
68 | });
69 |
70 | test('fetches specific announcement successfully using stealth address', async () => {
71 | const announcements = await stealthClient.getAnnouncements({
72 | ERC5564Address,
73 | args: {
74 | stealthAddress
75 | },
76 | fromBlock
77 | });
78 |
79 | expect(announcements[0].stealthAddress).toBe(stealthAddress);
80 | });
81 | test('fetches specific announcements successfully using caller', async () => {
82 | if (!account) throw new Error('No account found');
83 |
84 | const announcements = await stealthClient.getAnnouncements({
85 | ERC5564Address,
86 | args: {
87 | caller: walletClient.account?.address
88 | },
89 | fromBlock
90 | });
91 |
92 | expect(announcements[0].caller).toBe(account.address);
93 | });
94 |
95 | test('fetches specific announcements successfully using schemeId', async () => {
96 | const announcements = await stealthClient.getAnnouncements({
97 | ERC5564Address,
98 | args: {
99 | schemeId: BigInt(schemeId)
100 | },
101 | fromBlock
102 | });
103 |
104 | expect(announcements[0].schemeId).toBe(BigInt(schemeId));
105 |
106 | const invalidSchemeId = BigInt('2');
107 |
108 | const invalidAnnouncements = await stealthClient.getAnnouncements({
109 | ERC5564Address,
110 | args: {
111 | schemeId: invalidSchemeId
112 | },
113 | fromBlock
114 | });
115 |
116 | expect(invalidAnnouncements.length).toBe(0);
117 | });
118 | });
119 |
--------------------------------------------------------------------------------
/src/utils/crypto/test/generateStealthAddress.test.ts:
--------------------------------------------------------------------------------
1 | import { describe, expect, test } from 'bun:test';
2 | import { bytesToHex } from 'viem';
3 | import {
4 | generatePrivateKey,
5 | generateStealthAddress,
6 | getViewTag,
7 | parseKeysFromStealthMetaAddress,
8 | parseStealthMetaAddressURI
9 | } from '..';
10 | import { type HexString, VALID_SCHEME_ID } from '../types';
11 |
12 | describe('generateStealthAddress', () => {
13 | const validStealthMetaAddressURI =
14 | 'st:eth:0x033404e82cd2a92321d51e13064ec13a0fb0192a9fdaaca1cfb47b37bd27ec13970390ad5eca026c05ab5cf4d620a2ac65241b11df004ddca360e954db1b26e3846e';
15 |
16 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
17 |
18 | test('parseStealthMetaAddressURI should return the stealth meta-address', () => {
19 | const expectedStealthMetaAddress =
20 | '0x033404e82cd2a92321d51e13064ec13a0fb0192a9fdaaca1cfb47b37bd27ec13970390ad5eca026c05ab5cf4d620a2ac65241b11df004ddca360e954db1b26e3846e';
21 | // Passing the valid stealth meta-address URI and the scheme ID
22 | const result = parseStealthMetaAddressURI({
23 | stealthMetaAddressURI: validStealthMetaAddressURI,
24 | schemeId
25 | });
26 |
27 | expect(result).toBe(expectedStealthMetaAddress);
28 |
29 | // Passing only the stealth meta-address
30 | const result2 = parseStealthMetaAddressURI({
31 | stealthMetaAddressURI: expectedStealthMetaAddress,
32 | schemeId
33 | });
34 |
35 | expect(result2).toBe(expectedStealthMetaAddress);
36 | });
37 |
38 | test('should generate a valid stealth address given a valid stealth meta-address URI', () => {
39 | // TODO compute the expected stealth address using computeStealthAddress (not yet implemented in the SDK)
40 | const result = generateStealthAddress({
41 | stealthMetaAddressURI: validStealthMetaAddressURI,
42 | schemeId
43 | });
44 |
45 | expect(result.stealthAddress).toBeDefined();
46 | });
47 |
48 | test('should generate the same stealth address given the same ephemeralPrivateKey', () => {
49 | // First and second private keys are the same
50 | const firstPrivateKey = generatePrivateKey({ schemeId });
51 | const secondPrivateKey = generatePrivateKey({
52 | ephemeralPrivateKey: firstPrivateKey,
53 | schemeId
54 | });
55 |
56 | const result = generateStealthAddress({
57 | stealthMetaAddressURI: validStealthMetaAddressURI,
58 | schemeId,
59 | ephemeralPrivateKey: firstPrivateKey
60 | });
61 |
62 | const result2 = generateStealthAddress({
63 | stealthMetaAddressURI: validStealthMetaAddressURI,
64 | schemeId,
65 | ephemeralPrivateKey: secondPrivateKey
66 | });
67 |
68 | expect(result.stealthAddress).toBe(result2.stealthAddress);
69 | });
70 |
71 | test('should correctly parse spending and viewing public keys from valid stealth meta-address', () => {
72 | const stealthMetaAddress = validStealthMetaAddressURI.slice(7) as HexString;
73 | const expectedSpendingPublicKeyHex =
74 | '0x033404e82cd2a92321d51e13064ec13a0fb0192a9fdaaca1cfb47b37bd27ec1397';
75 | const expectedViewingPublicKeyHex =
76 | '0x0390ad5eca026c05ab5cf4d620a2ac65241b11df004ddca360e954db1b26e3846e';
77 |
78 | const result = parseKeysFromStealthMetaAddress({
79 | stealthMetaAddress,
80 | schemeId
81 | });
82 |
83 | expect(bytesToHex(result.spendingPublicKey)).toBe(
84 | expectedSpendingPublicKeyHex
85 | );
86 | expect(bytesToHex(result.viewingPublicKey)).toBe(
87 | expectedViewingPublicKeyHex
88 | );
89 | });
90 |
91 | test('should correctly extract the view tag from the hashed shared secret', () => {
92 | // Replace with the hashed shared secret from which you expect to extract the view tag
93 | const hashedSharedSecret =
94 | '0x158ce29a3dd0c8dca524e5776c2ba6361c280e013f87eee5eb799a713a939501';
95 | const expectedViewTag = '0x15';
96 |
97 | const result = getViewTag({
98 | hashedSharedSecret,
99 | schemeId
100 | });
101 |
102 | expect(result).toBe(expectedViewTag);
103 | });
104 | });
105 |
--------------------------------------------------------------------------------
/src/lib/helpers/test/setupTestEnv.ts:
--------------------------------------------------------------------------------
1 | import { fromHex } from 'viem';
2 | import { foundry } from 'viem/chains';
3 | import { createStealthClient } from '../..';
4 | import deployAllContracts from '../../../scripts';
5 | import { getChain } from '../chains';
6 | import type { VALID_CHAIN_IDS } from '../types';
7 |
8 | export const LOCAL_ENDPOINT = 'http://127.0.0.1:8545';
9 |
10 | /**
11 | * Initializes a test environment for testing purposes.
12 | * Defaults to local anvil node usage or, alternatively, use a remote RPC URL by setting the TEST_RPC_URL environment variable
13 | * @returns An object containing the testing environment setup parameters including chain ID, contract addresses, and a stealth client instance.
14 | */
15 | const setupTestEnv = async () => {
16 | // Setup stealth client
17 | const { chainId } = await getChainInfo();
18 | const rpcUrl = getRpcUrl();
19 | const stealthClient = createStealthClient({ rpcUrl, chainId });
20 |
21 | // Deploy ERC5564 and ERC6538 contracts
22 | const {
23 | erc5564ContractAddress: ERC5564Address,
24 | erc6538ContractAddress: ERC6538Address,
25 | erc5564DeployBlock: ERC5564DeployBlock
26 | } = await deployAllContracts();
27 |
28 | return {
29 | chainId,
30 | ERC5564Address,
31 | ERC5564DeployBlock,
32 | ERC6538Address,
33 | stealthClient
34 | };
35 | };
36 |
37 | /**
38 | * Validates the provided chain ID against a list of valid chain IDs.
39 | * @param {number} chainId - The chain ID to validate.
40 | * @returns {VALID_CHAIN_IDS} - The validated chain ID.
41 | * @throws {Error} If the chain ID is not valid.
42 | */
43 | const getValidChainId = (chainId: number): VALID_CHAIN_IDS => {
44 | if (chainId === 11155111 || chainId === 1 || chainId === 31337) {
45 | return chainId as VALID_CHAIN_IDS;
46 | }
47 | throw new Error(`Invalid chain ID: ${chainId}`);
48 | };
49 |
50 | /**
51 | * Retrieves the TEST RPC URL from env or defaults to foundry http.
52 | * @returns {string } The RPC URL.
53 | */
54 | const getRpcUrl = (): string => {
55 | const useFork = process.env.USE_FORK === 'true';
56 | if (useFork) {
57 | // Check that the RPC_URL is defined if using a fork
58 | if (!process.env.RPC_URL) {
59 | throw new Error('RPC_URL not defined in env');
60 | }
61 | // Use the local node endpoint for the rpc url
62 | return LOCAL_ENDPOINT;
63 | }
64 |
65 | return foundry.rpcUrls.default.http[0];
66 | };
67 |
68 | const getChainInfo = async () => {
69 | const chainId = await fetchChainId();
70 | const validChainId = getValidChainId(chainId);
71 | return { chain: getChain(validChainId), chainId: validChainId };
72 | };
73 |
74 | export const fetchChainId = async (): Promise => {
75 | // If not running fork test script, use the foundry chain ID
76 | if (!isUsingFork()) return foundry.id;
77 |
78 | if (!process.env.RPC_URL) {
79 | throw new Error('RPC_URL not defined in env');
80 | }
81 |
82 | interface ChainIdResponse {
83 | version: string;
84 | id: number;
85 | result: `0x${string}`;
86 | }
87 |
88 | try {
89 | const data = await fetchJson(process.env.RPC_URL, {
90 | method: 'POST',
91 | headers: {
92 | Accept: 'application/json',
93 | 'Content-Type': 'application/json'
94 | },
95 | body: JSON.stringify({
96 | id: 1,
97 | jsonrpc: '2.0',
98 | method: 'eth_chainId'
99 | })
100 | });
101 |
102 | return fromHex(data.result, 'number');
103 | } catch (error) {
104 | throw new Error('Failed to get the chain ID');
105 | }
106 | };
107 |
108 | const fetchJson = async (url: string, options: FetchRequestInit) => {
109 | const response = await fetch(url, options);
110 |
111 | if (!response.ok) {
112 | throw new Error(`HTTP error! status: ${response.status}`);
113 | }
114 |
115 | return response.json() as T;
116 | };
117 |
118 | function isUsingFork(): boolean {
119 | const useFork = process.env.USE_FORK;
120 | return useFork === 'true';
121 | }
122 |
123 | export { getValidChainId, getRpcUrl, getChainInfo, fetchJson };
124 | export default setupTestEnv;
125 |
--------------------------------------------------------------------------------
/src/test/sendReceive.test.ts:
--------------------------------------------------------------------------------
1 | import { beforeAll, describe, expect, test } from 'bun:test';
2 | import { http, createWalletClient, parseEther, publicActions } from 'viem';
3 | import { privateKeyToAccount } from 'viem/accounts';
4 | import { getRpcUrl } from '../lib/helpers/test/setupTestEnv';
5 | import {
6 | VALID_SCHEME_ID,
7 | computeStealthKey,
8 | generateStealthAddress
9 | } from '../utils';
10 | import { generateStealthMetaAddressFromSignature } from '../utils/helpers';
11 | import {
12 | getEndingBalances,
13 | getSignature,
14 | getWalletClientsAndKeys,
15 | sendEth,
16 | setupInitialBalances
17 | } from './helpers';
18 |
19 | /**
20 | * @description Tests for sending and receiving a payment
21 | * Sending means generating a stealth address using the sdk, then sending funds to that stealth address; the sending account is the account that sends the funds
22 | * Withdrawing means computing the stealth address private key using the sdk, then withdrawing funds from the stealth address; the receiving account is the account that receives the funds
23 | *
24 | * The tests need to be run using foundry because the tests utilize the default anvil private keys
25 | */
26 |
27 | describe('Send and receive payment', () => {
28 | const sendAmount = parseEther('1.0');
29 | const withdrawBuffer = parseEther('0.01');
30 | const withdrawAmount = sendAmount - withdrawBuffer;
31 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
32 |
33 | let gasEstimateSend: bigint;
34 | let sendingWalletBalanceChange: bigint;
35 | let receivingWalletBalanceChange: bigint;
36 |
37 | beforeAll(async () => {
38 | const {
39 | receivingAccount,
40 | receivingAccountKeys,
41 | receivingWalletClient,
42 | sendingWalletClient
43 | } = await getWalletClientsAndKeys();
44 |
45 | const { stealthAddress, ephemeralPublicKey } = generateStealthAddress({
46 | stealthMetaAddressURI: generateStealthMetaAddressFromSignature(
47 | await getSignature({ walletClient: receivingWalletClient })
48 | ),
49 | schemeId
50 | });
51 |
52 | const { sendingWalletStartingBalance, receivingWalletStartingBalance } =
53 | await setupInitialBalances({
54 | receivingWalletClient,
55 | sendingWalletClient
56 | });
57 |
58 | // Send ETH to the stealth address
59 | const { gasEstimate } = await sendEth({
60 | sendingWalletClient,
61 | to: stealthAddress,
62 | value: sendAmount
63 | });
64 |
65 | gasEstimateSend = gasEstimate;
66 |
67 | // Compute the stealth key to be able to withdraw the funds from the stealth address to the receiving account
68 | const stealthAddressPrivateKey = computeStealthKey({
69 | schemeId,
70 | ephemeralPublicKey,
71 | spendingPrivateKey: receivingAccountKeys.spendingPrivateKey,
72 | viewingPrivateKey: receivingAccountKeys.viewingPrivateKey
73 | });
74 |
75 | // Set up a wallet client using the stealth address private key
76 | const stealthAddressWalletClient = createWalletClient({
77 | account: privateKeyToAccount(stealthAddressPrivateKey),
78 | chain: sendingWalletClient.chain,
79 | transport: http(getRpcUrl())
80 | }).extend(publicActions);
81 |
82 | // Withdraw from the stealth address to the receiving account
83 | await sendEth({
84 | sendingWalletClient: stealthAddressWalletClient,
85 | to: receivingAccount.address,
86 | value: withdrawAmount
87 | });
88 |
89 | const { sendingWalletEndingBalance, receivingWalletEndingBalance } =
90 | await getEndingBalances({
91 | sendingWalletClient,
92 | receivingWalletClient
93 | });
94 |
95 | // Get the balance changes for the sending and receiving wallets
96 | sendingWalletBalanceChange =
97 | sendingWalletEndingBalance - sendingWalletStartingBalance;
98 | receivingWalletBalanceChange =
99 | receivingWalletEndingBalance - receivingWalletStartingBalance;
100 | });
101 |
102 | test('Can successfully send a stealth transaction from an account and withdraw from a different account by computing the stealth key', () => {
103 | expect(sendingWalletBalanceChange).toBe(-(sendAmount + gasEstimateSend));
104 | expect(receivingWalletBalanceChange).toBe(withdrawAmount);
105 | });
106 | });
107 |
--------------------------------------------------------------------------------
/src/utils/crypto/test/computeStealthKey.test.ts:
--------------------------------------------------------------------------------
1 | import { describe, expect, test } from 'bun:test';
2 | import { CURVE, getPublicKey, utils } from '@noble/secp256k1';
3 | import { bytesToHex, hexToBytes } from 'viem';
4 | import { publicKeyToAddress } from 'viem/accounts';
5 | import {
6 | VALID_SCHEME_ID,
7 | computeStealthKey,
8 | generatePrivateKey,
9 | generateStealthAddress
10 | } from '..';
11 | import { addPriv } from '../computeStealthKey';
12 |
13 | const formatPrivKey = (privateKey: bigint) =>
14 | `${privateKey.toString(16).padStart(64, '0')}`;
15 |
16 | describe('generateStealthAddress and computeStealthKey', () => {
17 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
18 | const stealthMetaAddressURI =
19 | 'st:eth:0x033404e82cd2a92321d51e13064ec13a0fb0192a9fdaaca1cfb47b37bd27ec13970390ad5eca026c05ab5cf4d620a2ac65241b11df004ddca360e954db1b26e3846e';
20 | const spendingPrivateKey =
21 | '0x363721eb9e981558c748b824cb32a840da2b3e8957c2fc3bcb8d9c86cb87456';
22 | const viewingPrivateKey =
23 | '0xb52a0555f6a8663d89f00365893b1ef9e38eaf2e8bc48a63319c9ea5cb4a27c5';
24 |
25 | test('full cycle stealth address generation and validation', () => {
26 | const ephemeralPrivateKey = generatePrivateKey({ schemeId });
27 |
28 | const generatedStealthAddressResult = generateStealthAddress({
29 | ephemeralPrivateKey,
30 | schemeId,
31 | stealthMetaAddressURI
32 | });
33 |
34 | const computedStealthPrivateKeyHex = computeStealthKey({
35 | ephemeralPublicKey: generatedStealthAddressResult.ephemeralPublicKey,
36 | schemeId,
37 | spendingPrivateKey,
38 | viewingPrivateKey
39 | });
40 |
41 | const computedStealthPublicKey = getPublicKey(
42 | hexToBytes(computedStealthPrivateKeyHex),
43 | false
44 | );
45 |
46 | const computedStealthAddress = publicKeyToAddress(
47 | bytesToHex(computedStealthPublicKey)
48 | );
49 |
50 | // Validate the generated stealth address matches the computed stealth address
51 | expect(generatedStealthAddressResult.stealthAddress).toEqual(
52 | computedStealthAddress
53 | );
54 | });
55 | });
56 |
57 | describe('adding private keys', () => {
58 | const privateKey1 = BigInt(
59 | '0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DEDFE92F46681B20A0'
60 | );
61 | const privateKey2 = BigInt(
62 | '0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DEDFE92F46681B20A0'
63 | );
64 | const curveOrder = BigInt(CURVE.n);
65 |
66 | test('demonstrate exceeding curve order results in invalid scalar, and modulo corrects it', () => {
67 | // Curve's order
68 | const curveOrder = BigInt(CURVE.n);
69 |
70 | // Create a scalar that exceeds the curve's order
71 | const exceededScalar = curveOrder + BigInt(1);
72 |
73 | // Check validity without modulo operation
74 | const isValidWithoutModulo = utils.isValidPrivateKey(
75 | formatPrivKey(exceededScalar)
76 | );
77 | expect(isValidWithoutModulo).toBe(false);
78 |
79 | // Apply modulo operation to bring the scalar within valid range
80 | const correctedScalar = exceededScalar % curveOrder;
81 |
82 | // Check validity with modulo operation
83 | const isValidWithModulo = utils.isValidPrivateKey(
84 | formatPrivKey(correctedScalar)
85 | );
86 | expect(isValidWithModulo).toBe(true);
87 |
88 | // Additionally, demonstrate that correctedScalar is less than curveOrder
89 | expect(correctedScalar).toBeLessThan(curveOrder);
90 | });
91 |
92 | test('adding private key scalars with addPriv', () => {
93 | const sumWithoutModulo = privateKey1 + privateKey2;
94 | // The sum exceeds the curve's order, which is invalid
95 | expect(sumWithoutModulo).toBeGreaterThan(curveOrder);
96 |
97 | const sumWithModulo = addPriv({
98 | a: privateKey1,
99 | b: privateKey2
100 | });
101 | // The sum is within the curve's order, which is valid
102 | expect(sumWithModulo).toBeLessThanOrEqual(curveOrder);
103 | });
104 |
105 | test('fuzzTest addPriv', () => {
106 | const iterations = 100000;
107 |
108 | for (let i = 0; i < iterations; i++) {
109 | // Generate two random scalars
110 | const scalarA = BigInt(bytesToHex(utils.randomPrivateKey()));
111 | const scalarB = BigInt(bytesToHex(utils.randomPrivateKey()));
112 |
113 | const result = addPriv({ a: scalarA, b: scalarB });
114 |
115 | expect(utils.isValidPrivateKey(formatPrivKey(result))).toBe(true);
116 | }
117 | });
118 | });
119 |
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
1 | # CLAUDE.md
2 |
3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 |
5 | ## Development Commands
6 |
7 | ### Testing
8 | - `bun test` - Run all tests using local Bun test runner
9 | - `bun test --watch src` - Run tests in watch mode during development
10 | - `bun test src/path/to/specific.test.ts` - Run a specific test file
11 | - `anvil` - Start local Anvil node for testing (required for most tests)
12 | - `bun run anvil-fork` - Start Anvil with fork of provided RPC_URL
13 | - `bun run test-fork` - Run tests against forked network
14 | - `bun run test-fork FILE=src/path/to/test.ts` - Run specific test against fork
15 |
16 | ### Building and Linting
17 | - `bun run build` - Apply Biome linting fixes and compile TypeScript
18 | - `bun run check` - Run Biome linting checks without fixing
19 | - `biome check --apply .` - Apply Biome formatting and linting fixes
20 | - `bun tsc` - Run TypeScript compiler
21 |
22 | ### Publishing
23 | - `bun run publish` - Build and publish to npm
24 |
25 | ## Architecture Overview
26 |
27 | ### Core Structure
28 | This is a TypeScript SDK for Ethereum stealth addresses implementing EIP-5564 and EIP-6538. The codebase is organized into several key layers:
29 |
30 | **Entry Points (`src/index.ts`)**:
31 | - Exports all utilities, client actions, configuration, and types
32 | - Main exports: crypto utilities, helpers, stealth client, contract addresses
33 |
34 | **Stealth Client (`src/lib/stealthClient/`)**:
35 | - `createStealthClient()` - Primary factory function for client instances
36 | - Takes `chainId` and `rpcUrl` parameters, returns initialized action functions
37 | - Uses Viem's `PublicClient` internally for blockchain interactions
38 | - All client actions are pre-bound with the public client instance
39 |
40 | **Actions (`src/lib/actions/`)**:
41 | - Modular blockchain interaction functions organized by domain
42 | - Each action has its own directory with implementation, types, and tests
43 | - Key actions: `getAnnouncements`, `getStealthMetaAddress`, `prepareAnnounce`, etc.
44 | - Actions work with or without the stealth client (can accept raw `PublicClient`)
45 |
46 | **Crypto Utilities (`src/utils/crypto/`)**:
47 | - Pure functions for stealth address cryptography
48 | - Core functions: `generateStealthAddress`, `computeStealthKey`, `checkStealthAddress`
49 | - Uses `@noble/secp256k1` for elliptic curve operations
50 | - All functions return consistent types and handle errors gracefully
51 |
52 | **Helper Utilities (`src/utils/helpers/`)**:
53 | - Supporting functions for key generation, metadata handling, validation
54 | - Includes subgraph integration helpers for off-chain data fetching
55 | - Functions for signature generation and stealth meta-address creation
56 |
57 | **Configuration (`src/config/`)**:
58 | - Contract addresses for different chains
59 | - Contract bytecode and deployment start blocks
60 | - Exports: `ERC5564_CONTRACT_ADDRESS`, `ERC6538_CONTRACT_ADDRESS`
61 |
62 | ### Key Design Patterns
63 |
64 | **Two-Level API Design**:
65 | 1. **High-level**: Use `createStealthClient()` for most applications
66 | 2. **Low-level**: Import individual functions for granular control
67 |
68 | **Error Handling**:
69 | - Custom error classes for different failure modes
70 | - Errors include original error context for debugging
71 | - All async functions properly propagate errors
72 |
73 | **TypeScript Integration**:
74 | - Comprehensive type exports for all parameters and return values
75 | - Uses Viem's types for blockchain interactions
76 | - BigInt used consistently for block numbers and large integers
77 |
78 | **Testing Strategy**:
79 | - Unit tests for pure functions using mocks
80 | - Integration tests against real/forked networks using Anvil
81 | - Real subgraph endpoints used in some tests for accuracy
82 |
83 | ### Subgraph Integration
84 | The SDK supports both direct blockchain queries and subgraph queries for better performance:
85 | - `getAnnouncements()` - Direct blockchain logs
86 | - `getAnnouncementsUsingSubgraph()` - Subgraph queries with pagination
87 | - Subgraph helpers in `src/lib/actions/getAnnouncementsUsingSubgraph/subgraphHelpers.ts`
88 |
89 | ### Contract Interaction Patterns
90 | - Uses Viem for all blockchain interactions
91 | - Contract addresses are environment-specific (pulled from config)
92 | - Actions that modify state return transaction objects (prepare functions)
93 | - Read-only actions return processed data directly
94 |
95 | ## Environment Setup
96 | Tests expect either a local Anvil node or environment variables:
97 | - `RPC_URL` - RPC endpoint for forked testing
98 | - `USE_FORK=true` - Flag to enable fork mode
99 | - Tests default to local Anvil if no environment specified
100 |
101 | ## Code Organization Notes
102 | - Each action/utility has co-located tests in same directory
103 | - Types are defined alongside implementations, exported centrally
104 | - Examples directory contains working usage examples for each major function
105 | - All crypto functions handle both compressed and uncompressed public keys
106 | - Consistent use of hex strings with 0x prefix for addresses and keys
--------------------------------------------------------------------------------
/src/lib/actions/getAnnouncementsUsingSubgraph/subgraphHelpers.ts:
--------------------------------------------------------------------------------
1 | import type { GraphQLClient } from 'graphql-request';
2 | import { ERC5564_CONTRACT_ADDRESS } from '../../../config';
3 | import type { AnnouncementLog } from '../getAnnouncements/types';
4 | import type { SubgraphAnnouncementEntity } from './types';
5 |
6 | /**
7 | * The necessary pagination variables for the subgraph query.
8 | */
9 | export type PaginationVariables = {
10 | first: number;
11 | skip: number;
12 | };
13 |
14 | /**
15 | * Asynchronous generator function to fetch paginated data from a subgraph.
16 | *
17 | * This function fetches data in reverse chronological order (newest first) by using
18 | * the 'id_lt' parameter for pagination. It recursively calls itself to fetch all pages
19 | * of data, using the lastId parameter as the starting point for each subsequent page.
20 | *
21 | * @template T - The type of entities being fetched, must have an 'id' property.
22 | * @param {Object} params - The parameters for the fetch operation.
23 | * @param {GraphQLClient} params.client - The GraphQL client instance.
24 | * @param {string} params.gqlQuery - The GraphQL query string with a '__WHERE_CLAUSE__' placeholder.
25 | * @param {number} params.pageSize - The number of items to fetch per page.
26 | * @param {string} params.filter - Additional filter criteria for the query.
27 | * @param {string} params.entity - The name of the entity being queried.
28 | * @param {string} [params.lastId] - The ID of the last item from the previous page, used for pagination.
29 | * @yields {T[]} An array of entities of type T for each page of results.
30 | * @throws {Error} If there's an error fetching the data from the subgraph.
31 | */
32 | export async function* fetchPages({
33 | client,
34 | gqlQuery,
35 | pageSize,
36 | filter,
37 | entity,
38 | lastId
39 | }: {
40 | client: GraphQLClient;
41 | gqlQuery: string;
42 | pageSize: number;
43 | filter: string;
44 | entity: string;
45 | lastId?: string;
46 | }): AsyncGenerator {
47 | // Set up variables for the GraphQL query
48 | const variables: { first: number; id_lt?: string } = {
49 | first: pageSize
50 | };
51 |
52 | // If lastId is provided, set it as the upper bound for the pagination
53 | if (lastId) {
54 | variables.id_lt = lastId;
55 | }
56 |
57 | // Construct the WHERE clause for the GraphQL query
58 | const whereClause = [filter, lastId ? 'id_lt: $id_lt' : null]
59 | .filter(Boolean)
60 | .join(', ');
61 |
62 | // Replace the placeholder in the query with the constructed WHERE clause
63 | const finalQuery = gqlQuery.replace('__WHERE_CLAUSE__', whereClause);
64 |
65 | try {
66 | const response = await client.request<{ [key: string]: T[] }>(
67 | finalQuery,
68 | variables
69 | );
70 | const batch = response[entity];
71 |
72 | // If no results, end the generator
73 | if (batch.length === 0) {
74 | return;
75 | }
76 |
77 | yield batch;
78 |
79 | // If we've received fewer items than the page size, we're done
80 | if (batch.length < pageSize) {
81 | return;
82 | }
83 |
84 | // Recursively fetch the next page
85 | const newLastId = batch[batch.length - 1].id;
86 | yield* fetchPages({
87 | client,
88 | gqlQuery,
89 | pageSize,
90 | filter,
91 | entity,
92 | lastId: newLastId
93 | });
94 | } catch (error) {
95 | console.error('Error fetching data:', error);
96 | throw error;
97 | }
98 | }
99 |
100 | /**
101 | * Converts a SubgraphAnnouncementEntity to an AnnouncementLog for interoperability
102 | * between `getAnnouncements` and `getAnnouncementsUsingSubgraph`.
103 | *
104 | * This function transforms the data structure returned by the subgraph into the
105 | * standardized AnnouncementLog format used throughout the SDK. It ensures consistency
106 | * in data representation regardless of whether announcements are fetched directly via logs
107 | * or via a subgraph.
108 | *
109 | * @param {SubgraphAnnouncementEntity} entity - The announcement entity from the subgraph.
110 | * @returns {AnnouncementLog} The converted announcement log in the standard format.
111 | */
112 | export function convertSubgraphEntityToAnnouncementLog(
113 | entity: SubgraphAnnouncementEntity
114 | ): AnnouncementLog {
115 | return {
116 | address: ERC5564_CONTRACT_ADDRESS, // Contract address is the same for all chains
117 | blockHash: entity.blockHash as `0x${string}`,
118 | blockNumber: BigInt(entity.blockNumber),
119 | logIndex: Number(entity.logIndex),
120 | removed: entity.removed,
121 | transactionHash: entity.transactionHash as `0x${string}`,
122 | transactionIndex: Number(entity.transactionIndex),
123 | topics: entity.topics as [`0x${string}`, ...`0x${string}`[]] | [],
124 | data: entity.data as `0x${string}`,
125 | schemeId: BigInt(entity.schemeId),
126 | stealthAddress: entity.stealthAddress as `0x${string}`,
127 | caller: entity.caller as `0x${string}`,
128 | ephemeralPubKey: entity.ephemeralPubKey as `0x${string}`,
129 | metadata: entity.metadata as `0x${string}`
130 | };
131 | }
132 |
--------------------------------------------------------------------------------
/src/test/helpers/index.ts:
--------------------------------------------------------------------------------
1 | import {
2 | http,
3 | type Address,
4 | type Client,
5 | type WalletClient,
6 | createWalletClient,
7 | publicActions
8 | } from 'viem';
9 | import { privateKeyToAccount } from 'viem/accounts';
10 | import { getRpcUrl } from '../../lib/helpers/test/setupTestEnv';
11 | import setupTestWallet from '../../lib/helpers/test/setupTestWallet';
12 | import { type SuperWalletClient, VALID_CHAINS } from '../../lib/helpers/types';
13 | import { generateKeysFromSignature } from '../../utils/helpers';
14 |
15 | // Default private key for testing; the setupTestWallet function uses the first anvil default key, so the below will be different
16 | const ANVIL_DEFAULT_PRIVATE_KEY_2 =
17 | '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
18 |
19 | /* Gets the signature to be able to generate reproducible public/private viewing/spending keys */
20 | export const getSignature = async ({
21 | walletClient
22 | }: {
23 | walletClient: WalletClient;
24 | }) => {
25 | if (!walletClient.chain) throw new Error('Chain not found');
26 | if (!walletClient.account) throw new Error('Account not found');
27 |
28 | const MESSAGE = `Signing message for stealth transaction on chain id: ${walletClient.chain.id}`;
29 | const signature = await walletClient.signMessage({
30 | message: MESSAGE,
31 | account: walletClient.account
32 | });
33 |
34 | return signature;
35 | };
36 |
37 | /* Generates the public/private viewing/spending keys from the signature */
38 | export const getKeys = async ({
39 | walletClient
40 | }: {
41 | walletClient: WalletClient;
42 | }) => {
43 | const signature = await getSignature({ walletClient });
44 | const keys = generateKeysFromSignature(signature);
45 | return keys;
46 | };
47 |
48 | /* Sets up the sending and receiving wallet clients for testing */
49 | export const getWalletClients = async () => {
50 | const sendingWalletClient = await setupTestWallet();
51 |
52 | const chain = sendingWalletClient.chain;
53 | if (!chain) throw new Error('Chain not found');
54 | if (!(chain.id in VALID_CHAINS)) {
55 | throw new Error('Invalid chain');
56 | }
57 |
58 | const rpcUrl = getRpcUrl();
59 |
60 | const receivingWalletClient: SuperWalletClient = createWalletClient({
61 | account: privateKeyToAccount(ANVIL_DEFAULT_PRIVATE_KEY_2),
62 | chain,
63 | transport: http(rpcUrl)
64 | }).extend(publicActions);
65 |
66 | return { sendingWalletClient, receivingWalletClient };
67 | };
68 |
69 | export const getAccount = (walletClient: WalletClient | Client) => {
70 | if (!walletClient.account) throw new Error('Account not found');
71 | return walletClient.account;
72 | };
73 |
74 | /* Gets the wallet clients, accounts, and keys for the sending and receiving wallets */
75 | export const getWalletClientsAndKeys = async () => {
76 | const { sendingWalletClient, receivingWalletClient } =
77 | await getWalletClients();
78 |
79 | const sendingAccount = getAccount(sendingWalletClient);
80 | const receivingAccount = getAccount(receivingWalletClient);
81 |
82 | const receivingAccountKeys = await getKeys({
83 | walletClient: receivingWalletClient
84 | });
85 |
86 | return {
87 | sendingWalletClient,
88 | receivingWalletClient,
89 | sendingAccount,
90 | receivingAccount,
91 | receivingAccountKeys
92 | };
93 | };
94 |
95 | /* Set up the initial balance details for the sending and receiving wallets */
96 | export const setupInitialBalances = async ({
97 | sendingWalletClient,
98 | receivingWalletClient
99 | }: {
100 | sendingWalletClient: SuperWalletClient;
101 | receivingWalletClient: SuperWalletClient;
102 | }) => {
103 | const sendingAccount = getAccount(sendingWalletClient);
104 | const receivingAccount = getAccount(receivingWalletClient);
105 | const sendingWalletStartingBalance = await sendingWalletClient.getBalance({
106 | address: sendingAccount.address
107 | });
108 | const receivingWalletStartingBalance = await receivingWalletClient.getBalance(
109 | {
110 | address: receivingAccount.address
111 | }
112 | );
113 |
114 | return {
115 | sendingWalletStartingBalance,
116 | receivingWalletStartingBalance
117 | };
118 | };
119 |
120 | /* Send ETH and wait for the transaction to be confirmed */
121 | export const sendEth = async ({
122 | sendingWalletClient,
123 | to,
124 | value
125 | }: {
126 | sendingWalletClient: SuperWalletClient;
127 | to: Address;
128 | value: bigint;
129 | }) => {
130 | const account = getAccount(sendingWalletClient);
131 | const hash = await sendingWalletClient.sendTransaction({
132 | value,
133 | to,
134 | account,
135 | chain: sendingWalletClient.chain
136 | });
137 |
138 | const receipt = await sendingWalletClient.waitForTransactionReceipt({ hash });
139 |
140 | const gasPriceSend = receipt.effectiveGasPrice;
141 | const gasEstimate = receipt.gasUsed * gasPriceSend;
142 |
143 | return { hash, gasEstimate };
144 | };
145 |
146 | /* Get the ending balances for the sending and receiving wallets */
147 | export const getEndingBalances = async ({
148 | sendingWalletClient,
149 | receivingWalletClient
150 | }: {
151 | sendingWalletClient: SuperWalletClient;
152 | receivingWalletClient: SuperWalletClient;
153 | }) => {
154 | const sendingAccount = getAccount(sendingWalletClient);
155 | const receivingAccount = getAccount(receivingWalletClient);
156 | const sendingWalletEndingBalance = await sendingWalletClient.getBalance({
157 | address: sendingAccount.address
158 | });
159 | const receivingWalletEndingBalance = await receivingWalletClient.getBalance({
160 | address: receivingAccount.address
161 | });
162 |
163 | return {
164 | sendingWalletEndingBalance,
165 | receivingWalletEndingBalance
166 | };
167 | };
168 |
--------------------------------------------------------------------------------
/src/lib/actions/watchAnnouncementsForUser/watchAnnouncementsForUser.test.ts:
--------------------------------------------------------------------------------
1 | import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
2 | import type { Address } from 'viem';
3 | import {
4 | type AnnouncementLog,
5 | ERC5564AnnouncerAbi,
6 | VALID_SCHEME_ID,
7 | generateStealthAddress
8 | } from '../../..';
9 | import setupTestEnv from '../../helpers/test/setupTestEnv';
10 | import setupTestStealthKeys from '../../helpers/test/setupTestStealthKeys';
11 | import setupTestWallet from '../../helpers/test/setupTestWallet';
12 | import type { SuperWalletClient } from '../../helpers/types';
13 | import type { StealthActions } from '../../stealthClient/types';
14 |
15 | const NUM_ANNOUNCEMENTS = 3;
16 | const WATCH_POLLING_INTERVAL = 1000;
17 |
18 | type WriteAnnounceArgs = {
19 | schemeId: bigint;
20 | stealthAddress: `0x${string}`;
21 | ephemeralPublicKey: `0x${string}`;
22 | viewTag: `0x${string}`;
23 | };
24 |
25 | const announce = async ({
26 | walletClient,
27 | ERC5564Address,
28 | args
29 | }: {
30 | walletClient: SuperWalletClient;
31 | ERC5564Address: Address;
32 | args: WriteAnnounceArgs;
33 | }) => {
34 | if (!walletClient.account) throw new Error('No account found');
35 |
36 | // Write to the announcement contract
37 | const hash = await walletClient.writeContract({
38 | address: ERC5564Address,
39 | functionName: 'announce',
40 | args: [
41 | args.schemeId,
42 | args.stealthAddress,
43 | args.ephemeralPublicKey,
44 | args.viewTag
45 | ],
46 | abi: ERC5564AnnouncerAbi,
47 | chain: walletClient.chain,
48 | account: walletClient.account
49 | });
50 |
51 | // Wait for the transaction receipt
52 | await walletClient.waitForTransactionReceipt({
53 | hash
54 | });
55 |
56 | return hash;
57 | };
58 |
59 | // Delay to wait for the announcements to be watched in accordance with the polling interval
60 | const delay = async () =>
61 | await new Promise(resolve => setTimeout(resolve, WATCH_POLLING_INTERVAL * 2));
62 |
63 | describe('watchAnnouncementsForUser', () => {
64 | let stealthClient: StealthActions;
65 | let walletClient: SuperWalletClient;
66 | let ERC5564Address: Address;
67 |
68 | // Set up keys
69 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1;
70 | const schemeIdBigInt = BigInt(schemeId);
71 | const { spendingPublicKey, viewingPrivateKey, stealthMetaAddressURI } =
72 | setupTestStealthKeys(schemeId);
73 |
74 | // Track the new announcements to see if they are being watched
75 | const newAnnouncements: AnnouncementLog[] = [];
76 | let unwatch: () => void;
77 |
78 | beforeAll(async () => {
79 | // Set up the testing environment
80 | ({ stealthClient, ERC5564Address } = await setupTestEnv());
81 | walletClient = await setupTestWallet();
82 |
83 | // Set up watching announcements for a user
84 | unwatch = await stealthClient.watchAnnouncementsForUser({
85 | ERC5564Address,
86 | args: {
87 | schemeId: schemeIdBigInt,
88 | caller: walletClient.account?.address // Watch announcements for the user, who is also the caller here as an example
89 | },
90 | handleLogsForUser: logs => {
91 | // Add the new announcements to the list
92 | // Should be just one log for each call of the announce function
93 | for (const log of logs) {
94 | newAnnouncements.push(log);
95 | }
96 | },
97 | spendingPublicKey,
98 | viewingPrivateKey,
99 | pollOptions: {
100 | pollingInterval: WATCH_POLLING_INTERVAL // Override the default polling interval for testing
101 | }
102 | });
103 |
104 | // Set up the stealth address to announce
105 | const { stealthAddress, ephemeralPublicKey, viewTag } =
106 | generateStealthAddress({
107 | stealthMetaAddressURI,
108 | schemeId
109 | });
110 |
111 | // Sequentially announce NUM_ACCOUNCEMENT times
112 | for (let i = 0; i < NUM_ANNOUNCEMENTS; i++) {
113 | await announce({
114 | walletClient,
115 | ERC5564Address,
116 | args: {
117 | schemeId: schemeIdBigInt,
118 | stealthAddress,
119 | ephemeralPublicKey,
120 | viewTag
121 | }
122 | });
123 | }
124 |
125 | // Small wait to let the announcements be watched
126 | await delay();
127 | });
128 |
129 | afterAll(() => {
130 | unwatch();
131 | });
132 |
133 | test('should watch announcements for a user', () => {
134 | // Check if the announcements were watched
135 | // There should be NUM_ACCOUNCEMENTS announcements because there were NUM_ANNOUNCEMENTS calls to the announce function
136 | expect(newAnnouncements.length).toEqual(NUM_ANNOUNCEMENTS);
137 | });
138 |
139 | test('should correctly not update announcements for a user if announcement does not apply to user', async () => {
140 | // Announce again, but arbitrarily (just as an example/for testing) change the ephemeral public key,
141 | // so that the announcement does not apply to the user, and is not watched
142 | const { stealthAddress, ephemeralPublicKey, viewTag } =
143 | generateStealthAddress({
144 | stealthMetaAddressURI,
145 | schemeId
146 | });
147 |
148 | const incrementLastCharOfHexString = (hexStr: `0x${string}`) => {
149 | const lastChar = hexStr.slice(-1);
150 | const base = '0123456789abcdef';
151 | const index = base.indexOf(lastChar.toLowerCase());
152 | const newLastChar = index === 15 ? '0' : base[index + 1]; // Roll over from 'f' to '0'
153 | return `0x${hexStr.slice(2, -1) + newLastChar}` as `0x${string}`;
154 | };
155 |
156 | // Replace the last character of ephemeralPublicKey with a different character for testing
157 | const newEphemeralPublicKey =
158 | incrementLastCharOfHexString(ephemeralPublicKey);
159 |
160 | // Write to the announcement contract with an inaccurate ephemeral public key
161 | await announce({
162 | walletClient,
163 | ERC5564Address,
164 | args: {
165 | schemeId: BigInt(schemeId),
166 | stealthAddress,
167 | ephemeralPublicKey: newEphemeralPublicKey,
168 | viewTag
169 | }
170 | });
171 |
172 | await delay();
173 |
174 | // Expect no change in the number of announcements watched
175 | expect(newAnnouncements.length).toEqual(NUM_ANNOUNCEMENTS);
176 | });
177 | });
178 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Stealth Address SDK
2 |
3 | This TypeScript SDK provides tools for working with Ethereum stealth addresses as defined in [EIP-5564](https://eips.ethereum.org/EIPS/eip-5564) and [EIP-6538](https://eips.ethereum.org/EIPS/eip-6538). It aims to offer a comprehensive suite of functionalities for both generating stealth addresses and interacting with stealth transactions.
4 |
5 | ## Documentation
6 |
7 | For comprehensive documentation and to learn more about stealth addresses, please visit our [official documentation site](https://stealthaddress.dev/).
8 |
9 | ## Contract Deployments
10 |
11 | Information about contract deployments can be found on the [deployments page](https://stealthaddress.dev/contracts/deployments) of our official documentation site.
12 |
13 | ## Features
14 |
15 | - Generate Ethereum stealth addresses.
16 | - Compute stealth address private keys.
17 | - Check stealth address announcements to determine if they are intended for a specific user.
18 | - Look up the stealth meta address for a registrant
19 | - Fetch announcements
20 | - Watch announcements for a user
21 | - Prepare the payload for announcing stealth address details
22 | - Prepare the payload for registering a stealth meta-address on someone's behalf
23 |
24 | ## Installation
25 |
26 | ```bash
27 | npm install @scopelift/stealth-address-sdk
28 | # or
29 | yarn add @scopelift/stealth-address-sdk
30 | # or
31 | bun install @scopelift/stealth-address-sdk
32 | ```
33 |
34 | ## Testing
35 |
36 | Tests default to using your local [anvil](https://book.getfoundry.sh/anvil/) node
37 |
38 | ```bash
39 | anvil
40 | bun run test
41 | ```
42 |
43 | Alternatively, run your tests using a fork of your provided (`RPC_URL` in `env`) rpc url
44 |
45 | ```bash
46 | bun run anvil-fork
47 | # run all tests
48 | bun run test-fork
49 | # or for a specific file
50 | bun run test-fork FILE={file path}
51 | ```
52 |
53 | ## Quick Start
54 |
55 | ### Generating a Stealth Address
56 |
57 | ```ts
58 | import { generateStealthAddress } from "@scopelift/stealth-address-sdk";
59 |
60 | // Your stealth meta-address URI
61 | // Follows the format: "st::", where is the chain identifier (https://eips.ethereum.org/EIPS/eip-3770#examples) and is the stealth meta-address.
62 | const stealthMetaAddressURI = "...";
63 |
64 | // Generate a stealth address using the default scheme (1)
65 | // To learn more about the initial implementation scheme using SECP256k1, please see the reference here (https://eips.ethereum.org/EIPS/eip-5564)
66 | const result = generateStealthAddress({ stealthMetaAddressURI });
67 |
68 | // Use the stealth address
69 | console.log(result.stealthAddress);
70 | ```
71 |
72 | ### Computing Stealth Key
73 |
74 | ```ts
75 | import {
76 | computeStealthKey,
77 | VALID_SCHEME_ID,
78 | } from "@scopelift/stealth-address-sdk";
79 |
80 | // Example inputs
81 | const viewingPrivateKey = "0x..."; // Viewing private key of the recipient
82 | const spendingPrivateKey = "0x..."; // Spending private key of the recipient
83 | const ephemeralPublicKey = "0x..."; // Ephemeral public key from the sender's announcement
84 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1; // Scheme ID, currently only '1' is supported
85 |
86 | // Compute the stealth private key
87 | const stealthPrivateKey = computeStealthKey({
88 | viewingPrivateKey,
89 | spendingPrivateKey,
90 | ephemeralPublicKey,
91 | schemeId,
92 | });
93 | ```
94 |
95 | ### Checking Stealth Address Announcements
96 |
97 | ```ts
98 | import {
99 | checkStealthAddress,
100 | VALID_SCHEME_ID,
101 | } from "@scopelift/stealth-address-sdk";
102 |
103 | // Example inputs
104 | const ephemeralPublicKey = "0x..."; // The ephemeral public key from the announcement
105 | const spendingPublicKey = "0x..."; // The user's spending public key
106 | const userStealthAddress = "0x..."; // The user's stealth address
107 | const viewingPrivateKey = "0x..."; // The user's viewing private key
108 | const viewTag = "0x..."; // The view tag from the announcement
109 | const schemeId = VALID_SCHEME_ID.SCHEME_ID_1; // Scheme ID, currently only '1' is supported
110 |
111 | // Check if the announcement is intended for the user
112 | const isForUser = checkStealthAddress({
113 | ephemeralPublicKey,
114 | schemeId,
115 | spendingPublicKey,
116 | userStealthAddress,
117 | viewingPrivateKey,
118 | viewTag,
119 | });
120 |
121 | console.log(
122 | isForUser
123 | ? "Announcement is for the user"
124 | : "Announcement is not for the user"
125 | );
126 | ```
127 |
128 | ### Fetching announcements, and checking if the associated stealth address is for the user
129 |
130 | ```ts
131 | import {
132 | ERC5564_CONTRACT_ADDRESS,
133 | VALID_SCHEME_ID,
134 | createStealthClient,
135 | } from "@scopelift/stealth-address-sdk";
136 |
137 | // Example parameters
138 | const chainId = 11155111; // Example chain ID for Sepolia
139 | const rpcUrl = process.env.RPC_URL; // Your env rpc url that aligns with the chainId;
140 | const fromBlock = BigInt(12345678); // Example ERC5564 announcer contract deploy block for Sepolia, or the block in which the user registered their stealth meta address (as an example)
141 |
142 | // Initialize the stealth client
143 | const stealthClient = createStealthClient({ chainId, rpcUrl: rpcUrl! });
144 |
145 | // Use the address of your calling contract if applicable
146 | const caller = "0xYourCallingContractAddress";
147 |
148 | // Your scheme id
149 | const schemeId = BigInt(VALID_SCHEME_ID.SCHEME_ID_1);
150 |
151 | // The contract address of the ERC5564Announcer on your target blockchain
152 | // You can use the provided ERC5564_CONTRACT_ADDRESS get the singleton contract address for a valid chain ID
153 | const ERC5564Address = ERC5564_CONTRACT_ADDRESS;
154 |
155 | async function fetchAnnouncementsForUser() {
156 | // Example call to getAnnouncements action on the stealth client to get all potential announcements
157 | // Use your preferred method to get announcements if different, and
158 | // adjust parameters according to your requirements
159 | const announcements = await stealthClient.getAnnouncements({
160 | ERC5564Address,
161 | args: {
162 | schemeId,
163 | caller,
164 | // Additional args for filtering, if necessary
165 | },
166 | fromBlock, // Optional fromBlock parameter (defaults to 0, which can be slow for many blocks)
167 | });
168 |
169 | // Example call to getAnnouncementsForUser action on the stealth client
170 | // Adjust parameters according to your requirements
171 | const userAnnouncements = await stealthClient.getAnnouncementsForUser({
172 | announcements,
173 | spendingPublicKey: "0xUserSpendingPublicKey",
174 | viewingPrivateKey: "0xUserViewingPrivateKey",
175 | });
176 |
177 | return userAnnouncements;
178 | }
179 | ```
180 |
181 | ## License
182 |
183 | [MIT](/LICENSE) License
184 |
--------------------------------------------------------------------------------