diff --git a/concepts/policies/delegated-access.mdx b/concepts/policies/delegated-access.mdx index 5f93a627..ecebc3e5 100644 --- a/concepts/policies/delegated-access.mdx +++ b/concepts/policies/delegated-access.mdx @@ -5,30 +5,30 @@ description: "With Turnkey you can create multi-user accounts with flexible co-o ## Overview -Delegated access works by creating a specialized business-controlled user within each end-user’s sub-organization that has carefully scoped permissions to perform only specific actions, such as signing transactions to designated addresses. This can enable your backend to do things like: -* Automate common transactions (e.g., staking, redemptions) -* Sign transactions to whitelisted addresses without user involvement -* Perform scheduled operations -* Respond to specific onchain events programmatically +Delegated access works by creating a specialized business-controlled user within each end-user’s sub-organization that has carefully scoped permissions to perform only specific actions, such as signing transactions to designated addresses. This can enable your backend to do things like: -## Implementation flow +- Automate common transactions (e.g., staking, redemptions) +- Sign transactions to whitelisted addresses without user involvement +- Perform scheduled operations +- Respond to specific onchain events programmatically + +## Implementation flow Here’s how to implement delegated access for an embedded wallet setup: -* Create a sub-organization with two root users: The end user and your “Delegated User” with an API key authenticator that you control -* Enable the Delegated Account to take particular actions by setting policies explicitly allowing those specific actions -* Update the root quorum to ensure only the end-user retains root privileges + +- Create a sub-organization with two root users: The end user and your “Delegated User” with an API key authenticator that you control +- Enable the Delegated Account to take particular actions by setting policies explicitly allowing those specific actions +- Update the root quorum to ensure only the end-user retains root privileges A simple example demonstrating the delegated acess setup can be found [here](https://github.com/tkhq/sdk/tree/main/examples/delegated-access). ## Step-by-step implementation +### Step 1: Create a sub-organization with two root users[​](#step-1-create-a-sub-organization-with-two-root-users) -### Step 1: Create a sub-organization with two root users[​](#step-1-create-a-sub-organization-with-two-root-users "Direct link to Step 1: Create a sub-organization with two root users") - -* Create your sub-organization with the two root users being: - - * The end-user - * A user you control (we'll call it the ‘Delegated Account’) +- Create your sub-organization with the two root users being: + - The end-user + - A user you control (we'll call it the ‘Delegated Account’) ```json { @@ -87,12 +87,11 @@ A simple example demonstrating the delegated acess setup can be found [here](htt ### Step 2: Limit the permissions of the Delegated Account user via policies -* Create a custom policy granting the Delegated Account specific permissions. You might grant that user permissions to: - - * Sign any transaction - * Sign only transactions to a specific address - * Create new users in the sub-org - * Or any other activity you want to be able to take using your Delegated Account +- Create a custom policy granting the Delegated Account specific permissions. You might grant that user permissions to: + - Sign any transaction + - Sign only transactions to a specific address + - Create new users in the sub-org + - Or any other activity you want to be able to take using your Delegated Account Here’s one example, granting the Delegated Account only the permission to sign ethereum transactions to a specific receiver address: @@ -232,3 +231,99 @@ dotenv.config(); userIds: [subOrg.rootUserIds[1]], // retain the end user }); ``` + +## Frequently Asked Questions + +### Policy Design and Creation + + + Yes — if the delegated access (DA) user is part of the root quorum, they can create policies unilaterally. Once removed from the root quorum, only the remaining quorum member (typically the end-user) can make further policy changes. + + + + End-user approval typically happens during **intent** creation — for example, when the end-user authorizes a DA user by adjusting the quorum or signs an initial setup transaction. + + + + As long as the DA user remains authorized, they can remove policies programmatically. If they’ve been removed from the quorum, policy deletion will require the user’s explicit approval. + + **NOTE:** Turnkey is looking to support the concept of 'one-time-use policies' to make it easier to manage redundany policies. + + +### Security & Risk Management + + + Yes — if the key is attached to a broad policy. That’s why it’s important to limit the scope of policies and enforce API hygiene practices. + + + + In effect, yes. The key difference is that granular policies **can restrict** what a DA user can do, offering better security hygiene even if there's still elevated access. + + + + Typically this is a combination of, or all of the following practices, though not exclusive to just these: + + - Using short-lived keys whenever viable + - Rotating API keys regurarly + - Monitoring the usage + - Secure storage (e.g. in HSMs or vaults) + + +### Best Practices + + + You can define strict transaction conditions. For example: + + ```javascript + solana.tx.instructions.count() == 1 && + solana.tx.transfers.count() == 1 && + solana.tx.transfers.all(transfer, transfer.to == '') + ``` + + You can also consider the following: + + - Recipient address restrictions (ie allowlisting addresses) + - Contract method selectors + - Transaction structure invariants + - Blockhash constraints (on Solana) + + + + Yes — this is a common pattern. You can add a policy per order (limit, stop loss, TWAP, etc.) using the DA user, without requiring the end-user to sign for each one. + + + + Turnkey's Policy Engine shines through its flexibility. There are many different approaches you can take based on your requirements, but various themes we see include: + + - Using **broad policies** with business-controlled API keys + - Using \*\*fine-grained policies, \*\*scoped to predictable transaction shapes + - Using delegated access to implement **limit orders, automation flows, or advanced trading logic** (e.g. perps, TWAPs) + - Ensuring **strong operational security** (e.g. tight scoping & expiring keys) is increasingly common + + +### EVM and SVM-Specific Strategies + + + Yes, on Solana via `solana.tx.recent_blockhash`, which restricts a transaction’s validity to a ~60–90 second window. Not ideal for delayed executions (e.g. limit orders), but useful for immediate, single-use actions. + + + + Yes, though it’s limited today. You can inspect calldata (e.g., using `eth.tx.data[...]`) and enforce conditions like: + + ```javascript + eth.tx.to == '' && + eth.tx.data[0..4] == '' + ``` + + Granular support for calldata parsing and value limits is coming soon. + + + + Not entirely. Even if you allowlist the router, it could still be abused to swap all assets. You can’t control downstream behavior unless you control the contract. + + > **Suggestion:** Only allow DA keys to interact with contracts you fully trust or control. Limit scope as much as possible (e.g., to specific instructions, amounts, or recipients). + + + + Use structure-based conditions (instruction count, token recipient), and if possible, include conditions like `recent_blockhash` for ephemeral actions. For limit orders with unknown execution time, dynamic policy creation per order is safer than relying on stale conditions. + \ No newline at end of file diff --git a/embedded-wallets/sub-organization-auth.mdx b/embedded-wallets/sub-organization-auth.mdx index 6cb6ea9d..57d77e28 100644 --- a/embedded-wallets/sub-organization-auth.mdx +++ b/embedded-wallets/sub-organization-auth.mdx @@ -198,7 +198,31 @@ Here's an example of a custom HTML email containing an email auth bundle: ![dynamic email auth example](/images/embedded-wallets/img/email-auth-example-dynamic.png) -If you are interested in implementing bespoke, fully-customized email templates, please reach out to [hello@turnkey.com](mailto:hello@turnkey.com). +### Custom email sender domain + +[Enterprise](https://www.turnkey.com/pricing) clients on the **Scale** tier or higher can also customize the email sender domain. To get set up, please reach out to your Turnkey rep to get started but here is what you'll be able to configure: + +```js +message InitOtpAuthIntent { + // Optional custom email address from which to send the OTP email + optional string send_from_email_address = "notifs@mail.domain.com"; + + // Optional custom sender name (e.g. "MyApp Notifications") + optional string send_from_email_sender_name = "MyApp Notifications"; + + // Optional reply-to email address + optional string reply_to_email_address = "reply@mail.domain.com"; +} +``` + +Please keep in mind that: + +- Email has to be from a pre-whitelisted domain +- If there is no `send_from_email_address` or it's invalid, the other two fields are ignored +- If `send_from_email_sender_name` is absent, it defaults to "Notifications" (again, ONLY if `send_from_email_address` is present and valid) +- If `reply_to_email_address` is absent, then there is no reply-to added. If it is present, it must ALSO be from a valid, whitelisted domain, but it doesn't have to be the same email address as the `send_from_email_address` one (though once again, this first one MUST be present, or the other two feature are ignored) + +If you are interested in implementing bespoke, fully-customized email templates and sender domain, please reach out to [hello@turnkey.com](mailto:hello@turnkey.com). ### Credential validity checks diff --git a/reference/aa-wallets.mdx b/reference/aa-wallets.mdx index 6c030e67..3e5faac9 100644 --- a/reference/aa-wallets.mdx +++ b/reference/aa-wallets.mdx @@ -19,10 +19,12 @@ Visit [the ZeroDev documentation](https://docs.zerodev.app/sdk/signers/turnkey) Create a Biconomy Smart Account and add a Turnkey signer to manage your private key and authentication methods by using Turnkey's API. -For detailed code snippets and an integration guide, refer to the [Biconomy documentation](https://docs.biconomy.io/account/signers/turnkey). +For detailed code snippets and an integration guide, refer to the [Biconomy documentation](https://docs.biconomy.io/tutorials/signers/turnkey/). + +Ethereum's latest EIP-7702 standard gives superpowers to Externally Owned Accounts (EOAs). Biconomy has a guide on how to leverage gas abstracted transactions with Turnkey and Biconomy, enabling Turnkey EOAs to become smart accounts through delegation to Nexus. The tutorial showcases gas abstracted batch execution - users can pay gas fees with ERC20 tokens from their EOA. Refer to [Biconomy documentation](https://docs.biconomy.io/smarteoa/demos/turnkey-7702-gasless/) to get started. ## permissionless.js Accounts permissionless.js is a TypeScript library built on viem for building with ERC-4337 smart accounts, bundlers, paymasters, and user operations. -permissionless.js defines the `SmartAccountSigner` interface which supports Turnkey as a signer. You can find a detailed example for integrating a Turnkey signer with permissionless.js in the [Pimlico documentation](https://docs.pimlico.io/permissionless/how-to/signers/turnkey). +permissionless.js defines the `SmartAccountSigner` interface which supports Turnkey as a signer. You can find a detailed example for integrating a Turnkey signer with permissionless.js in the [Pimlico documentation](https://docs.pimlico.io/permissionless/how-to/signers/turnkey). \ No newline at end of file diff --git a/reference/solana-gasless-transactions.mdx b/reference/solana-gasless-transactions.mdx index d740bd5f..1805bad9 100644 --- a/reference/solana-gasless-transactions.mdx +++ b/reference/solana-gasless-transactions.mdx @@ -13,7 +13,7 @@ Here’s how to take advantage of Turnkey’s composable primitives for gas abst ### **Option 1: Using Solana Address Fee Payer** -For this approach, we will leverage [examples/with-solana](https://github.com/tkhq/sdk/tree/main/examples/with-solana), a full example of Solana transaction construction, and broadcasting using [@turnkey/with-solana](https://www.npmjs.com/package/@turnkey/solana). For a more comprehensive, full-stack example that leverages passkeys, check out [examples/with-solana-passkeys](https://github.com/tkhq/sdk/tree/main/examples/with-solana-passkeys). +For this approach, we will leverage [examples/with-solana](https://github.com/tkhq/sdk/tree/main/examples/with-solana), a full example demonstrating how to construct a Solana transaction, sign using [@turnkey/solana](https://www.npmjs.com/package/@turnkey/solana), and broadcast via public node. For a more comprehensive, full-stack example that leverages passkeys, check out [examples/with-solana-passkeys](https://github.com/tkhq/sdk/tree/main/examples/with-solana-passkeys). \ First, you’ll need to use one of the two optional environmental variables: `SOLANA_ADDRESS_FEE_PAYER`. While optional, the variable is necessary to create a separate fee payer address. The setup is as simple as passing in the fee payer address into the [withFeePayer.ts](https://github.com/tkhq/sdk/blob/main/examples/with-solana/src/withFeePayer.ts)