From 28f4fffb53e822d872083c320d8e7928b0956b32 Mon Sep 17 00:00:00 2001 From: T-Hax <> Date: Sun, 14 May 2023 22:05:51 +0000 Subject: [PATCH] Update all READMEs, docs. Signed-off-by: T-Hax <> --- README.md | 26 +++---- docs/EXPERIMENTAL.md | 4 +- docs/USAGE.md | 160 ++++++++++++++++++++++++++++--------------- 3 files changed, 121 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 8ee5167..23a71f7 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,27 @@ # Tornado Cash SDK -SDK to integrate your protocol with Tornado Cash. +A general purpose SDK for Tornado Cash interactions. -[Please check out the docs here.](./docs/ABOUT.md) +* [Please check out the docs here.](./docs/ABOUT.md) -You SHOULD familiarize yourself with features [still considered experimental](./docs/EXPERIMENTAL.md). +* You SHOULD familiarize yourself with features [still considered experimental](./docs/EXPERIMENTAL.md). -You may also read, [a note on testing.](./docs/TESTS.md) +* You may also read, [a note on testing.](./docs/TESTS.md) Contributions are welcome, we are here for freedom after all! See [HISTORY.md](./HISTORY.md) for a development log. -# Package `md5sum` checksums +# Latest package `md5sum` checksums + +If they are not correct contact the dev, post an issue, or yell in the Matrix chat. ``` -ecfbb8a878d31a163f6569c0aea32221 tornado-sdk-0.0.10-alpha.zip -05be559908957e0f4961121537abc25c tornado-sdk-chain-0.0.9-alpha.zip -bbc6bebfc9a36b022b5236da7791a234 tornado-sdk-core-0.0.10-alpha.zip -3afd4ac753d27d2371623ba94f0c17aa tornado-sdk-crypto-0.0.9-alpha.zip -d250fbc88e1e55b26f26179fa12aacb9 tornado-sdk-data-0.0.9-alpha.zip -8cee3f65925686ea397d2c20f567be1a tornado-sdk-utils-0.0.9-alpha.zip -49cef79f2e800ccaab5ae54f67dad124 tornado-sdk-web-0.0.9-alpha.zip +19ca2e85b680d6605e7b3c39e9acc791 tornado-sdk-0.0.11-alpha.zip +168bcc32bb6f6973205413ebd685ad55 tornado-sdk-chain-0.0.11-alpha.zip +a2facbdf22e78bbb3de0d0cf6ad86280 tornado-sdk-core-0.0.11-alpha.zip +90c3be466ab4fa4795377336ba7f0e67 tornado-sdk-crypto-0.0.11-alpha.zip +0442a6f42ece8615c4d6b04f2d00f4e9 tornado-sdk-data-0.0.11-alpha.zip +2b79bc500ad061c518c3d369e85e89e6 tornado-sdk-utils-0.0.11-alpha.zip +faf9dc39b0fbbb06f6848ea9217a1b17 tornado-sdk-web-0.0.11-alpha.zip ``` diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md index 1713380..7b953e3 100644 --- a/docs/EXPERIMENTAL.md +++ b/docs/EXPERIMENTAL.md @@ -1,8 +1,8 @@ -# Functions which are still considered experimental +# Functions which are still considered slightly experimental Ranked by danger. -* **Core.buildDepositProof(s)** ➡️ because we still need more testnet tests. Nominally, should work though. Use at own risk. Very very likely won't break. +* **Core.buildDepositProof(s)** ➡️ because we still need more testnet tests. Will most likely not break, but watch out with token withdrawals, until we have a testnet confirmation. * **Relayer.handleWithdrawal** ➡️ because no test relayer has been yet available to handle this. Will likely break. diff --git a/docs/USAGE.md b/docs/USAGE.md index 471c6fc..17e0aec 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,87 +1,137 @@ # Usage Examples -### Build a deposit transaction +### Make a deposit ```ts +import { Wallet, BigNumber } from "ethers" + import * as Tornado from "@tornado/sdk" -import { providers } from "ethers" +import * as dotenv from "dotenv" + +dotenv.config() async function main() { - // Get the core Tornado Cash logic. + const torProvider = + new Tornado.Web.TorProvider(process.env.NETWORK_RPC!, { port: process.env. }) + + const wallet = new Wallet(process.env.PRIVATE_KEY!, torProvider) + + console.log( + "\n 🤑 Balance of the wallet on network => ", + (await wallet.getBalance()).div(BigNumber.from(10).pow(18)).toString(), + '\n' + ) + const core = new Tornado.Core() - // Connect a provider - await core.connect(new providers.JsonRpcProvider("https://some.rpc.url")) + await core.connect(torProvider) - // Build tx (synchronous) - const tx = core.createDepositTransaction(core.getInstance("usdc", "100")) + console.log("\n 🌪️ Tornado Core connected\n") - // Print the tx to console - console.log(tx) + // You can set something lower here, in case you're a poor bastard, like me, obviously xD + const instance = core.getInstance("eth", 1) + + const tx = core.createDepositTransaction(instance) + + console.log(`\n 💱 Deposit request created!\n\n${JSON.stringify(tx)}\n`) + console.log(`\n Sending...\n`) + + const response = await wallet.sendTransaction(tx.request) + + console.log(`\n Response arrived!\n`) + + console.log(`\n Note: ${tx.note}, you need this, but it will be backed up!\n`) + + const receipt = await response.wait() + + console.log(`\n Receipt received!\n`) + + await core.backupNote(instance, tx) + + console.log("\n All backed up! Load with \"core.loadNotes\" next time!\n") } main() ``` -### Build a withdrawal transaction +### Make a withdrawal -This is _still_ considered experimental, I will flag it as _not experimental_ after a certain number of production tests. +Goerli withdrawals for ETH showed to be working, but I still consider it experimental for ETH and definitely for tokens. ```ts +import { Wallet, BigNumber, utils } from "ethers" + import * as Tornado from "@tornado/sdk" -import { providers, BigNumber } from "ethers" +import * as dotenv from "dotenv" + +dotenv.config() async function main() { - // The address to receive the funds... - const receiverAddress = "0x0000000000000000000000000000000000000000" + const torProvider = + new Tornado.Web.TorProvider(process.env.NETWORK_RPC!, { port: 9150 }) - // Get the core Tornado Cash logic. - const core = new Tornado.Core() + const depositorWallet = new Wallet(process.env.DEPOSITOR_PRIVATE_KEY!, torProvider) + const receiverWallet = new Wallet(process.env.RECEIVER_PRIVATE_KEY!, torProvider) - // Get a regular ethers v5 provider. - const provider = new providers.JsonRpcProvider("https://some.rpc.url") + let initialBalanceOfReceiver = await receiverWallet.getBalance() + const initialBalanceOfDepositor = await depositorWallet.getBalance() - // This time we need to connect the provider - await core.connect(provider) + const zeroPointThree = utils.parseUnits("0.3") - // We also need a relayer - const relayer = new Tornado.Web.Relayer({ - url: "https://" + "some.relayer.org", - // Web can also instead provide a TorHttpClient or an (ethers v5) TorProvider - httpClient: new Tornado.Web.RegularHttpClient() - }) + if (initialBalanceOfReceiver.lt(zeroPointThree)) { + const response = await depositorWallet.sendTransaction({ + to: receiverWallet.address, + value: zeroPointThree.sub(initialBalanceOfReceiver) + }) + await response.wait() - // We always have to fetch the current properties of a relayer - await relayer.fetchProperties() + console.log("\n 🤑 Funded receiver wallet to exactly 0.3 ether \n") - // Once that is done let's get an instance we have a proof of - const instance = core.getInstance("eth", "0.1") + initialBalanceOfReceiver = await receiverWallet.getBalance() + } - // We have to load the note, the arguments can be - // indexes - indexes according to which you may choose the notes in cache - // keys - the keys according to which you may choose the notes in cache - // In our case we've set indexes to undefined and choosing our notes according to the instance - // And then selecting the first one of those - const note = (await core.loadNotes(undefined, { - network: '' + core.chain.id, - token: "eth", - denomination: "0.1" - }))[0] + console.log( + "\n 🤑 Initial balance of depositor wallet on network => ", + initialBalanceOfDepositor.toString(), + '\n' + ) - // Now build the proof - const proof = await core.createDepositProof(instance, relayer.properties, receiverAddress, note, { - // Defaults after the function populates as a showcase - // You can also leave all of this out and it will set it by itself - checkNotesSpent: true, - checkKnownRoot: true, - merkleTreeHeight: 20, - tokenDecimals: 18, - ethPurchaseAmounts: [BigNumber.from(0)], // When doing multiple proofs, more elements in array - gasPrice: undefined, - gasPriceCushion: undefined, - }) + console.log( + "\n 🤑 Initial balance of receiver wallet on network => ", + initialBalanceOfReceiver.toString(), + '\n' + ) - console.log(proof) + const core = new Tornado.Core() + + await core.connect(torProvider) + + console.log("\n 🌪️ Tornado Core connected!\n") + + const instance = core.getInstance("eth", 1) + + const note = (await core.loadNotes())[0] + + const proof = await core.createDepositProof( + instance, + { address: receiverWallet.address }, + receiverWallet.address, + note + ) + + console.log(`\n 📜 Proof built:\n\n${proof}\n`) + + const response = await instance.connect(receiverWallet).withdraw(proof[0], proof[1], proof[2], proof[3], proof[4], proof[5], proof[6]) + + await response.wait() + + console.log("\n 🌪️🌪️🌪️💰🥷 Withdrawal successful! \n") + + console.log( + "\n 🤑 Balance of the receiver wallet on network => ", + (await receiverWallet.getBalance()).toString(), + '\n' + ) } main() @@ -109,7 +159,7 @@ async function sync() { // Sync! Output will be in the project dir in the cache folder await core.syncDeposits(instance) - // Now export it as an archive! + // Now export it as a zipped archive! await core.exportCacheZip('Deposits1ETH0.1') } @@ -145,7 +195,7 @@ async function sync() { } ) - // Export as archive again! + // Export as a zipped archive again! await core.exportCacheZip('Deposits1ETH0.1') }