> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artstarex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 钱包接入与网络切换

> 解析用户进入 ArtStar 的第一道门槛：钱包连接、状态初始化与网络守护机制

## 概述

钱包是用户在 ArtStar 中的链上身份入口，也是后续登录、KYC、授权、申购和持仓展示的基础。网络则决定了这些交互是否发生在正确的链环境中

因此，钱包接入与网络切换不是单纯的技术前置步骤，而是用户能否顺利参与平台的第一道门槛。如果钱包状态不稳定，后续所有流程都会受到影响

## 接入机制与作用

<AccordionGroup>
  <Accordion title="为什么钱包接入重要？" icon="wallet">
    在 ArtStar 中，钱包至少承担以下作用： \* 标识用户链上地址 \*
    配合签名完成登录认证 \* 查询稳定币余额和授权状态 \* 发起链上交易 (Approve /
    Mint) \* 展示用户持仓和资产记录
  </Accordion>

  <Accordion title="网络守护机制 (Network Guard)" icon="shield">
    ArtStar
    的核心交互运行在指定链上。为了避免用户停留在错误网络导致资产读取错误或交易失败，前端通常需要具备以下能力：

    * 检测当前链 ID 并判断是否为目标链 \* 在错误链时**阻止关键写操作** \*
      引导用户一键切换网络 \* 在切换成功后自动恢复交互流程
  </Accordion>
</AccordionGroup>

## 基本接入流程

从产品角度看，这一步的目标不是“连上钱包”本身，而是让平台能够识别并服务当前用户：

<Steps>
  <Step title="连接钱包">用户点击连接钱包，唤起钱包插件或应用</Step>
  <Step title="获取地址">钱包授权连接并返回当前地址</Step>
  <Step title="状态初始化">前端初始化与该地址相关的 UI 状态</Step>
  <Step title="签名登录">如有需要，引导用户完成签名验证以建立后端会话</Step>

  <Step title="数据读取">
    前端继续读取余额、网络和权限相关信息，进入业务主干
  </Step>
</Steps>

## 常见异常与排查

用户在钱包接入和网络切换阶段可能遇到以下问题，前端需要给出明确、可执行的提示，而不是只显示通用错误信息：

<Card title="常见错误情况" icon="bug">
  * 钱包插件未安装或未唤起 \* 钱包连接请求被用户拒绝 \* 地址读取失败 \*
    当前网络错误（未在 BNB Chain 等目标网络） \* 自动切换请求无响应 \*
    移动端钱包内置浏览器兼容性问题
</Card>

## 避坑指南

<Callout type="warning" title="连接钱包 ≠ 完成登录">
  钱包连接只是拿到地址。如果平台还需要基于签名建立后端会话，那么用户仍可能处于“已连接但未登录”状态，需要前端做明确引导
</Callout>

<Callout type="danger" title="自动切换网络不一定总成功">
  部分钱包、浏览器或移动端环境不支持稳定的自动切换，因此不能假设调用一次切换方法就一定完成，需根据实际链
  ID 进行后置校验
</Callout>

<Callout type="info" title="钱包断开后要同步清理状态">
  当用户主动断开钱包时，平台应同步清理依赖该地址的页面状态、缓存数据和会话信息，避免旧数据残留引发异常
</Callout>