Add a role - Swig

Introduction

Adding a role pairs a new authority with the permissions it may use on an existing wallet.

Use when: another signer needs limited access to wallet assets.
For: apps delegating spending to a user, service, or automation.

How it works

Connect the signer for a role with authority-management permission.
Encode the new authority and a permission set for its task.
Submit addRole and wait for a successful receipt.
Read the assigned role ID from RoleAdded and retain it for later operations.

Role fields

Field	Type	Meaning
`managerRoleId`	Integer	Existing role approving the addition
`delegate`	Address	EOA that will authorize the new role
`amount`	Integer, wei	Total native-currency allowance
`roleId`	Integer	New ID returned by the confirmed event

A fixed allowance decreases with successful spending; it is not a per-transaction limit or a deposit. Amounts fit uint64. Fund the wallet’s vault separately.

SDK example

This creates a native-currency spending role without role-management permission. The connected manager pays gas. Supply 100n for a total allowance of 100 wei.

import {
  type Address,
  type LocalAccount,
  createPublicClient,
  createWalletClient,
  getAddress,
  http,
  parseEventLogs,
} from "viem";
import {
  encodeAuthority,
  encodePermission,
  getSwigConfig,
  swigConfigAbi,
} from "../src/index.js";

export async function addSpendingRole(
  rpcUrl: string,
  manager: LocalAccount,
  accountAddress: Address,
  managerRoleId: number,
  delegate: Address,
  amount: bigint,
) {
  const client = createPublicClient({ transport: http(rpcUrl) });
  const wallet = createWalletClient({ account: manager, transport: http(rpcUrl) });
  const config = getSwigConfig(accountAddress, { public: client, wallet });
  const authority = encodeAuthority({ type: "secp256k1", address: delegate });
  const hash = await config.write.addRole([
    managerRoleId, authority.authorityType, authority.key, authority.keyExtra,
    [encodePermission({ type: "nativeLimit", amount })],
  ], { chain: null });
  const receipt = await client.waitForTransactionReceipt({ hash });
  if (receipt.status !== "success") throw new Error("Role creation failed");
  const [event] = parseEventLogs({
    abi: swigConfigAbi,
    eventName: "RoleAdded",
    logs: receipt.logs.filter((log) => getAddress(log.address) === getAddress(accountAddress)),
  });
  if (!event) throw new Error("RoleAdded event missing");
  return { roleId: event.args.roleId, transactionHash: hash };
}

Use the confirmed ID, not a predicted counter. Read the role to verify its authority and permissions before using the delegate. Complete examples: TypeScript, Rust, Python.