Triggering Delegation

In your application, when a user is logged in, you’ll want to request delegation so your server can act on their behalf (for example, to sign transactions or run automated flows).

Check delegation status

Use hasDelegatedAccess to check whether a wallet account already has delegated access before triggering the delegation flow.

import { getWalletAccounts } from '@dynamic-labs-sdk/client';
import { hasDelegatedAccess } from '@dynamic-labs-sdk/client/waas';

const walletAccounts = getWalletAccounts();
const walletAccount = walletAccounts[0];

const isDelegated = hasDelegatedAccess({ walletAccount });
console.log('Has delegated access:', isDelegated);

Trigger delegation

Use delegateWaasKeyShares to initiate the delegation process for a wallet account. This sends the encrypted delegated share to your server via the wallet.delegation.created webhook.

import { getWalletAccounts } from '@dynamic-labs-sdk/client';
import { delegateWaasKeyShares } from '@dynamic-labs-sdk/client/waas';

const walletAccounts = getWalletAccounts();
const walletAccount = walletAccounts[0];

await delegateWaasKeyShares({ walletAccount });

With password encryption

If the wallet uses password encryption, pass the password when delegating. The delegated share will be encrypted with the password before being sent.

import { getWalletAccounts } from '@dynamic-labs-sdk/client';
import { delegateWaasKeyShares } from '@dynamic-labs-sdk/client/waas';

const walletAccounts = getWalletAccounts();
const walletAccount = walletAccounts[0];

await delegateWaasKeyShares({ walletAccount, password: 'user-password' });

Dynamic does not prompt the user for a password during delegation. If the wallet is password-protected, you must obtain the password in your own UI flow and pass it programmatically.

Seed initial policy rules

You can seed the delegated signer’s policy layer at delegation time by passing initialSignerRules. Build each rule with buildAllowPolicyRule or buildDenyPolicyRule.

JavaScript
React

import {
  buildDenyPolicyRule,
  delegateWaasKeyShares,
  WaasChainEnum,
} from '@dynamic-labs-sdk/client/waas';

await delegateWaasKeyShares({
  walletAccount,
  initialSignerRules: [
    buildDenyPolicyRule({
      name: 'Block private key export',
      chain: WaasChainEnum.Evm,
      chainIds: [1],
      operationRestrictions: { blockExport: true },
    }),
  ],
});

import { useDelegateWaasKeyShares } from '@dynamic-labs-sdk/react-hooks';
import { buildDenyPolicyRule, WaasChainEnum } from '@dynamic-labs-sdk/client/waas';

const DelegateWithRule = ({ walletAccount }) => {
  const { mutate, isPending } = useDelegateWaasKeyShares();

  return (
    <button
      disabled={isPending}
      onClick={() =>
        mutate({
          walletAccount,
          initialSignerRules: [
            buildDenyPolicyRule({
              name: 'Block private key export',
              chain: WaasChainEnum.Evm,
              chainIds: [1],
              operationRestrictions: { blockExport: true },
            }),
          ],
        })
      }
    >
      Delegate with rule
    </button>
  );
};

initialSignerRules uses the raw WaasPolicyRule shape, not the PolicyRules map used by createPolicy. After delegation, you can read or update the delegated signer layer with getPolicy and createPolicy.

Apply declarative rules to the delegated signer

initialSignerRules takes legacy rules only. To put declarative rules on a delegated signer, delegate first and then write to the delegated share set’s signer layer. Find the delegated share set with getWalletAccountShareSets and pass its shareSetId to upsertSignerPolicyRule.

import { getWalletAccounts } from '@dynamic-labs-sdk/client';
import {
  delegateWaasKeyShares,
  getWalletAccountShareSets,
  upsertSignerPolicyRule,
  WaasWalletShareSetType,
} from '@dynamic-labs-sdk/client/waas';
import {
  WaasPolicyAction,
  WaasPolicyDeclarativeRuleInputPhaseEnum,
} from '@dynamic-labs/sdk-api-core';

await delegateWaasKeyShares({ walletAccount });

// Re-fetch the wallet account once delegation completes so its share sets are current.
const [delegatedAccount] = getWalletAccounts();
const { others } = getWalletAccountShareSets({ walletAccount: delegatedAccount });
const delegatedShareSet = others.find(
  (shareSet) => shareSet.shareSetType === WaasWalletShareSetType.Delegated
);

await upsertSignerPolicyRule({
  walletAccount,
  shareSetId: delegatedShareSet.shareSetId,
  rule: {
    name: 'Blocked address',
    phase: WaasPolicyDeclarativeRuleInputPhaseEnum.Transaction,
    then: WaasPolicyAction.Deny,
    when: {
      exists: {
        in: 'counterparties',
        where: { field: 'address', op: 'in', value: ['0x0000000000000000000000000000000000000bad'] },
      },
    },
  },
});

Omit ruleId to create a rule; pass an existing ruleId to update it. To set the layer’s full rule list in one write, use replacePolicyLayerRules with the same shareSetId. A shareSetId rotates when wallet shares are refreshed or reshared, so re-read it before each update. For the full operation set, see the signer layer.

Parameters

Parameter	Type	Required	Description
`walletAccount`	`WalletAccount`	Yes	The WaaS wallet account to delegate
`password`	`string`	No	Password for wallets using password encryption
`initialSignerRules`	`WaasPolicyRule[]`	No	Rules to seed the delegated signer’s policy layer

What's next?

Learn how to receive the delegation materials on your server

​Check delegation status

​Trigger delegation

​With password encryption

​Seed initial policy rules

​Apply declarative rules to the delegated signer

​Parameters

What's next?

Check delegation status

Trigger delegation

With password encryption

Seed initial policy rules

Apply declarative rules to the delegated signer

Parameters