用途:Controller Sessions & Policies 用于为 Cartridge Controller 定义会话策略(SessionPolicies),即声明应用可调用哪些合约与方法。策略是会话式交易执行的必需项:没有策略时 execute() 会因链上会话校验需要每次调用的 merkle 证明而失败,错误码 130(Array length mismatch);此时 Controller 会退回 keychain 弹窗手动审批。在本地 Katana 上必须配置策略,否则新的 Controller 账户无法正确部署。
会话流程:定义策略 → 用户在连接时一次性批准 → Controller 按已授权限创建会话 → 交易经 Paymaster 无缝执行。
主要能力:以 contracts 字段按合约地址声明 name、description 与 methods(含 name、entrypoint、description);对 approve 方法可用 spender 与 amount(十六进制)设置花费上限,0xffffffffffffffffffffffffffffffff 表示无限额(max uint128),有价格数据时用户会看到对应美元值;另可通过 messages 预批准类型化消息签名,定义 types、primaryType 与 domain。
错误处理:errorDisplayMode 支持 modal(默认,全屏错误弹窗并阻塞交互)、notification(可点击 toast,非阻塞)、silent(仅控制台输出);propagateSessionErrors 为 true 时错误立即返回、不显示 UI,为 false 时按上述模式展示。可用 ResponseCodes.SUCCESS/ERROR 判断 execute 结果。注意 SessionRefreshRequired 与 ManualExecutionRequired 始终弹出模态框,不受设置影响。
用法要点:通过 new Controller({ policies }) 或 SessionConnector(含 rpc、chainId、redirectUrl、disconnectRedirectUrl)初始化;SessionOptions 类型包含 rpc、chainId、policies、redirectUrl、disconnectRedirectUrl?、signupOptions?。已验证策略会显示信任徽章与简化审批流程,需向 @cartridge/presets 提交配置进行验证。
限制:具体价格数据来源、验证审核周期与 unsupported 场景暂未提供。