Create a session with a custom setup

This Smart Sessions setup is EVM-only. createSession, its validator and policies, and session signer selection do not apply to managed Solana accounts. Swig’s allButManageAuthority permits spending and instructions; it is not a restricted session with token budgets, call allowlists, or expiry. See Solana support.

Installing the validation

You can install the validator during account deployment: Examples on this page use @rhinestone/sdk, where rhinestone is the RhinestoneSDK instance from the custom signer quickstart.

const rhinestoneAccount = await rhinestone.createAccount({
  evm: {
    owners: {
      type: "ecdsa",
      accounts: [ownerAccount],
    },
    sessions: {
      enabled: true,
    },
  },
});

You can also install it when the account is already deployed:

import { enable } from "@rhinestone/sdk/actions/smart-sessions";

const transaction = await rhinestoneAccount.prepareTransaction({
  destination: { chain: base, calls: [enable()] },
  sponsored: true,
});

To uninstall the validator:

import { disable } from "@rhinestone/sdk/actions/smart-sessions";

const transaction = await rhinestoneAccount.prepareTransaction({
  destination: { chain: base, calls: [disable()] },
  sponsored: true,
});

These no-delivery examples require fee and gas sponsorship. Sign and submit the prepared transaction with the account owner. Without sponsorship, select a funded fee token in source: { chain: base, token: feeTokenAddress }.

Creating sessions

To create a session, use RhinestoneSDK.createSession:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
});

To limit the session to specific calls, list the permissions and set restrictToActions:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdcAddress,
      functions: { transfer: {} },
    },
  ],
  restrictToActions: true,
  saltMode: "strict",
});

Permissions alone do not make a restrictive allowlist. Without restrictToActions, the session retains the wildcard intent-execution fallback for calls approved by the Orchestrator’s intent target allowlist. See Restrict a session for the behavior and tradeoffs. Keep saltMode: "strict" when creating a new restricted session. The SDK default, "none", uses a zero salt, so sessions with the same signer reuse a permission ID even when their actions differ. Enabling another definition under that ID adds its policies to the on-chain sets instead of replacing earlier grants. Strict mode gives different restricted definitions distinct permission IDs, but it does not invalidate any permission ID that the signer already controls. Revoke the previous broader session before relying on the signer to have narrower authority. Permissions govern account calls, while cross-chain permits scope the session to the settlement routes of cross-chain intents. A session holding a permit is already scoped, and you can combine it with restrictToActions, permissions, and actions. Finally, you can constrain function parameters. The SDK derives the selector and parameter offsets from the ABI, so you reference parameters by name:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdcAddress,
      functions: {
        transfer: {
          params: {
            recipient: {
              condition: "equal",
              value: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
            },
          },
        },
      },
    },
  ],
  restrictToActions: true,
  saltMode: "strict",
});

See the Call policy for the full set of parameter conditions, and Restrict a session to make the listed permissions the only calls the session can run.

Session access

Every created session reports whether its key is held to its own actions in session.access.kind:

Definition	Access
No `permissions`, `actions`, `crossChainPermits`, or `swap`	`"open"`: wildcard sudo
`permissions` or `actions` without `restrictToActions`	`"open"`: wildcard intent-execution fallback
`restrictToActions`, a `swap` scope, or a `crossChainPermits` entry without `fallback`	`"scoped"`
A Permit2-layer permit with `fallback`	`"open"`

Branch on kind. session.access.reason is for people to read, and its wording may change.

Validate a definition

rhinestone.validateSession runs the same checks as createSession without creating, enabling, or signing anything. It lists every refusal instead of throwing the first one:

const { refusals, warnings, access, settlementCoverage } =
  await rhinestone.validateSession({
    chain: base,
    owners: {
      type: "ecdsa",
      accounts: [sessionOwnerAccount],
    },
    account: rhinestoneAccount.getAddress("evm"),
    crossChainPermits: [
      {
        from: { chain: base, token: usdcAddress, maxAmount: parseUnits("100", 6) },
        to: { chain: arbitrum, token: usdcOnArbitrum },
      },
    ],
  });

for (const refusal of refusals) {
  console.error(refusal.code, refusal.message);
}
for (const warning of warnings ?? []) {
  console.warn(warning.code, warning.message);
}
if (refusals.length === 0) {
  console.log(access?.kind, settlementCoverage?.dropped);
}

refusals is empty exactly when createSession succeeds. The first refusal is the error createSession throws.
warnings lists what the session accepts but does not enforce the way the definition may suggest.
access and settlementCoverage describe the session createSession would return.

Each refusal and warning has a stable code, listed in SESSION_REFUSAL_CODES and SESSION_WARNING_CODES from @rhinestone/sdk/smart-sessions. Branch on codes, not messages. Refusals can also carry permitIndex, layer, chainId, and leg. validateSession makes the same network reads as createSession, and network failures still throw. @rhinestone/sdk/smart-sessions also exports an offline validateSession and toSession. They make no network reads, so routes that depend on the served settlement catalog need it passed as settlement. Prefer the online methods.

Store the created session

createSession resolves the definition into a Session: its permissionId, salt, actions, erc7739Policies, compiled claimPolicies, and metadata. Persist that object with serialization that preserves bigint values, and pass the restored Session to getSessionDetails, signEnableSession, enableSession, disableSession, and session signers. Never send a stored Session back through createSession, toSession, or validateSession. Rebuilding a session from its definition under a newer served catalog, clock, or SDK default can produce a different permissionId and enable digest. A new identity does not upgrade an installed grant: the old grant keeps its installed policies until you revoke it, so revoke or authorize a replacement deliberately. Session.claimPolicies is compiled signing metadata; keep it. access and settlementCoverage can be absent on sessions stored by older SDK versions.

Embedded wallet

Custom setup

Create a session with a custom setup

Installing the validation

Creating sessions

Session access

Validate a definition

Store the created session

Next steps

Use a session

Session signing

​Installing the validation

​Creating sessions

​Session access

​Validate a definition

​Store the created session

​Next steps

Use a session

Session signing

Installing the validation

Creating sessions

Session access

Validate a definition

Store the created session

Next steps