diff --git a/docs/getting-started/Quickstart-Javascript.md b/docs/getting-started/Quickstart-Javascript.md index 125d15db..0b6ebbbd 100644 --- a/docs/getting-started/Quickstart-Javascript.md +++ b/docs/getting-started/Quickstart-Javascript.md @@ -24,21 +24,49 @@ All API requests require an organization ID. Yours can be located in the user dr style={{ width: 940 }} /> -For convenience, it's worth setting this as a constant in your app: +You'll want to save this somewhere in your code, as you'll need it to make requests to the Turnkey API. ```javascript -const TURNKEY_ORGANIZATION_ID="" +const TURNKEY_ORGANIZATION_ID = ""; ``` +## Create an API Key + +Turnkey API Keys are generic public / private key pairs that allow you to make requests to our API. You can create an API Key from your user page of the dashboard. Navigate to your user page by clicking on "User Details" in the user dropdown menu, and then click "Create an API key". + +Find user details + +Find user details + +- Select "Generate API keys in-browser" and click continue. +- Give your API key pair a name and click continue. +- Save your Public and Private Key locally. +- Make sure to click "Approve" to sign the API Creation activity with your authenticator device. + +A couple of notes: +- You will need both the public and private key to sign requests to the Turnkey API. +- **Any code using a Turnkey API private key should only ever be run server-side.** + ## Require the Turnkey Libraries -There are two libraries that you need, the Turnkey HTTP library, for making API requests to the Turnkey API. And a Turnkey "Stamper" library. The stamper library is responsible for signing the operation into Turnkey, and comes in 3 different flavors: +There are two libraries that you will need to make API requests to Turnkey: + 1. The Turnkey HTTP library. + 2. A Turnkey "stamper" library. + +The stamper library is responsible for signing the operation into Turnkey, and comes in 3 different flavors: 1. `api-key-stamper` which signs requests with your Turnkey API key 2. `webauthn-stamper` which signs requests with a end-user's passkey 3. `iframe-stamper` which is used for ... -For this example we're going to use the API Key Stamper to make requests to Turnkey from the context of the dapp. -**Any code using the Turnkey API key should only be run server-side** +The simplest way to get started, is to use the API Key Stamper to make requests to Turnkey that are signed with the API key pair you created in the previous step. ```shell yarn add @turnkey/http @@ -67,6 +95,8 @@ const turnkeyClient = new TurnkeyClient( ## Create a Wallet +A `wallet` on Turnkey represents a multi-chain seed phrase from which many individual `accounts` can be derived. An `account` represents an individual index on a derivation path that contains the blockchain address you can send funds to and sign on-chain transactions with. The only thing a wallet needs to be initialized is a name for the wallet. + ```javascript await turnkeyClient.createWallet({ organizationId: TURNKEY_ORGANIZATION_ID, @@ -74,51 +104,60 @@ await turnkeyClient.createWallet({ timestampMs: String(Date.now()), parameters: { walletName: "Test Wallet 1", - accounts: [ - { - path: "m/44'/0'/0'/0/0", - pathFormat: "PATH_FORMAT_BIP32", - curve: "CURVE_SECP256K1", - addressFormat: "ADDRESS_FORMAT_ETHEREUM" - } - ] + accounts: [] } }) ``` ## Create an Ethereum Account +Once a wallet has been created, an account can be created against that wallet by passing in the [INSERT HERE] ... + +Note: The account specification could also be passed into the initial createWallet call if desired. + ```javascript -await turnkeyClient.createWallet({ +await client.createWalletAccounts({ organizationId: TURNKEY_ORGANIZATION_ID, - type: 'ACTIVITY_TYPE_CREATE_WALLET', + type: 'ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS', timestampMs: String(Date.now()), parameters: { - walletName: "Test Wallet 1", + walletId: '1ce716fa-9d40-5371-9c1a-3e95e4663ff5', accounts: [ { - path: "m/44'/0'/0'/0/0", + path: "m/44'/60'/0'/0/0", pathFormat: "PATH_FORMAT_BIP32", curve: "CURVE_SECP256K1", addressFormat: "ADDRESS_FORMAT_ETHEREUM" - } + }, + { + path: "m/44'/60'/0'/0/1", + pathFormat: "PATH_FORMAT_BIP32", + curve: "CURVE_SECP256K1", + addressFormat: "ADDRESS_FORMAT_ETHEREUM" + }, + { + path: "m/44'/60'/0'/0/2", + pathFormat: "PATH_FORMAT_BIP32", + curve: "CURVE_SECP256K1", + addressFormat: "ADDRESS_FORMAT_ETHEREUM" + }, ] } }) ``` -## Sign a Transaction +You can view the created accounts with ```javascript -await turnkeyClient.createWallet({ +await client.createWalletAccounts({ organizationId: TURNKEY_ORGANIZATION_ID, - type: 'ACTIVITY_TYPE_CREATE_WALLET', + type: 'ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS', timestampMs: String(Date.now()), parameters: { - walletName: "Test Wallet 1", + walletId: '1ce716fa-9d40-5371-9c1a-3e95e4663ff5', accounts: [ { - path: "m/44'/0'/0'/0/0", + path: "m/44'/60'/0'/0/0", pathFormat: "PATH_FORMAT_BIP32", curve: "CURVE_SECP256K1", addressFormat: "ADDRESS_FORMAT_ETHEREUM" @@ -128,9 +167,28 @@ await turnkeyClient.createWallet({ }) ``` +## Sign a Transaction + +Once you have an account, you can sign a transaction with the account as follows. + +```javascript +await turnkeyClient.signTransaction({ + organizationId: TURNKEY_ORGANIZATION_ID, + type: "ACTIVITY_TYPE_SIGN_TRANSACTION_V2", + timestampMs: String(Date.now()), + parameters: { + signWith: "" // i.e. 0x780ed9b6BF99908106d1bAA25b7658a80ADB5f42 + unsignedTransaction: "", // i.e. 02eb018084db4f550d850bb6338fa88252089470a8a81613dd06dc243de94ebdf861ff5f82b361831e848080c0 + type: "TRANSACTION_TYPE_ETHEREUM" + } +}) +``` + +Make sure to replace the `unsignedTransaction` below with your own. You can use our [simple transaction generator](https://build.tx.xyz) if you need a quick transaction for testing. + ## Using the Webauthn Stamper -Now we'll perform user actions using the client-side webauthn stamper. You can learn more about the specifics of passkeys in the [Passkey guide](../passkeys/introduction) +The previous actions all had to be signed server-side in our code using a Turnkey API key, but you can also have individual end-users sign Turnkey activities using their own passkeys using the client-side webauthn stamper library. You can learn more about the specifics of the passkeys implementation in the [Passkey guide](../passkeys/introduction) ```shell yarn add @turnkey/webauthn-stamper @@ -221,6 +279,11 @@ export function Export(props: ExportProps) { } ``` +## Best Practices (Using Sub-Organizations) + +Due to cryptographic limitations of how much data can be signed at once, generally speaking, a common pattern is to create sub-organizations for each individual user, instead of creating wallets for each user directly on the parent organization. You can read more about how to properly do this in the [Suborganization Guide](../integration-guides/sub-organizations-as-wallets.md) + + ## Next Steps - Check out our [examples](/getting-started/examples) to see what can be built - Learn more about [Organizations](/getting-started/organizations) and [Wallets](/getting-started/wallets) diff --git a/docs/getting-started/Quickstart-CLI.md b/docs/getting-started/Using-The-CLI.md similarity index 98% rename from docs/getting-started/Quickstart-CLI.md rename to docs/getting-started/Using-The-CLI.md index efccdb39..ed95740b 100644 --- a/docs/getting-started/Quickstart-CLI.md +++ b/docs/getting-started/Using-The-CLI.md @@ -1,10 +1,10 @@ --- -id: quickstart-cli +id: using-the-cli sidebar_position: 3 description: Onboard and sign your first Ethereum transaction -slug: /getting-started/quickstart-cli +slug: /getting-started/using-the-cli --- -# Quickstart CLI +# Using the CLI This quickstart will guide you through Turnkey’s onboarding, adding an API key, creating a wallet, and signing your first Ethereum transaction. diff --git a/static/img/quickstart/create_api_key.png b/static/img/quickstart/create_api_key.png new file mode 100644 index 00000000..bef8bc7a Binary files /dev/null and b/static/img/quickstart/create_api_key.png differ