Docs: explicit session permissions deep dive + token directory + fee options (#215)

* Docs: add permissions deep dive + token directory + fee option clarification

* chore(i18n): update translations [en]

Sync file structure, format locales. Branch: 215/merge

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: taylanpince

es/sdk/web/wallet-sdk/ecosystem/getting-started.mdx

@@ -15,11 +15,11 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
     <Steps>
       <Step title="Instale las librerías requeridas">
         ```bash
-        npm install @0xsequence/connect@v6-beta wagmi viem 
+        npm install @0xsequence/connect@v6-beta wagmi viem
         # or
-        pnpm install @0xsequence/connect@v6-beta wagmi viem 
+        pnpm install @0xsequence/connect@v6-beta wagmi viem
         # or
-        yarn add @0xsequence/connect@v6-beta wagmi viem 
+        yarn add @0xsequence/connect@v6-beta wagmi viem
         ```
       </Step>
 
@@ -36,17 +36,17 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
         - `dappOrigin`
         - `signIn.projectName`, `appName`
         - `chainIds`, `defaultChainId`
-        - `explicitSessionParams` (opcional; `nativeTokenSpending` por defecto es `valueLimit: 0`)
+        - `explicitSession` (opcional; solicita permisos y límites explícitos de sesión)
         - `includeFeeOptionPermissions`, `enableImplicitSession`
         - `nodesUrl`, `relayerUrl`
         - `walletConnect`
 
         ```typescript [config.ts]
-        import { createConfig } from "@0xsequence/connect";
+        import { createConfig, createExplicitSession } from "@0xsequence/connect";
 
         export const config: any = createConfig({
           projectAccessKey: "AQAAAAAAAABtDHG1It7lxRF_9bbxw4diip8",
-          walletUrl: 'https://next-acme-wallet.sequence-dev.app',
+          walletUrl: 'https://acme-wallet.ecosystem-demo.xyz',
           // Optional
           dappOrigin: window.location.origin,
           signIn: {
@@ -58,18 +58,29 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
           google: true,
           apple: true,
           email: true,
-          explicitSessionParams: { ... }
+          explicitSession: createExplicitSession({ ... })
         });
         ```
 
-        El `walletUrl` es la URL del Ecosystem Wallet que su dApp usará. Para nuestra demo, estamos usando el [Acme Ecosystem Wallet](https://next-acme-wallet.sequence-dev.app).
+        El `walletUrl` es la URL del Ecosystem Wallet que su dApp utilizará. Para nuestra demostración, estamos usando el [Acme Ecosystem Wallet](https://acme-wallet.ecosystem-demo.xyz).
 
         El `dappOrigin` es el origen de su dapp, usado para verificar de dónde proviene el usuario.
 
-        El objeto `explicitSessionParams` permite que su dapp solicite permisos específicos al usuario al conectarse.
-        Estos permisos pueden autorizar a su dapp a realizar ciertas acciones en nombre del usuario durante un período definido, creando una experiencia más fluida sin solicitudes de transacción o permitiendo automatizaciones.
+        El objeto `explicitSession` permite que su dapp solicite permisos específicos al usuario al conectarse.
+        Estos permisos pueden autorizar a su dapp a realizar ciertas acciones en nombre del usuario durante un período definido, creando una experiencia más fluida sin avisos de transacción o permitiendo automatizaciones.
+
+        Ver: [Análisis profundo de permisos](/sdk/web/wallet-sdk/ecosystem/permissions-deep-dive) y [Directorio de tokens](/sdk/web/wallet-sdk/ecosystem/token-directory).
+
+        ### Comportamiento de las opciones de comisión (importante)
+
+        Cuando su aplicación envía transacciones mediante el relayer de Sequence, este necesita determinar **cómo se pagan las comisiones**.
+
+        - Si desea que el SDK solicite automáticamente los permisos necesarios relacionados con comisiones al crear una sesión explícita, active `includeFeeOptionPermissions`.
+        - Si lo desactiva, usted es responsable de incluir los permisos relacionados con comisiones que requiera la opción de comisión que espera usar.
+
+        Si no se puede cubrir el pago de la comisión, las transacciones pueden fallar al momento de enviarse, incluso si el permiso principal de llamada al contrato parece correcto.
 
-        `nativeTokenSpending` es opcional. Si se omite, la sesión tendrá por defecto un `valueLimit` de token nativo de `0`.
+        `nativeTokenSpending` es opcional. Si se omite, la sesión no tendrá asignado un límite de gasto de tokens nativos.
 
         Por ejemplo, creemos una sesión explícita que permita a su dapp `depositar 100 USDC en el pool de AAVE V3 en Arbitrum, en nombre del usuario durante las próximas 24 horas`
 
@@ -82,7 +93,7 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
 
         export const config: any = createConfig({
           projectAccessKey: "AQAAAAAAAABtDHG1It7lxRF_9bbxw4diip8",
-          walletUrl: 'https://next-acme-wallet.sequence-dev.app',
+          walletUrl: 'https://acme-wallet.ecosystem-demo.xyz',
           // Optional
           dappOrigin: window.location.origin,
           signIn: {
@@ -94,7 +105,7 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
           google: true,
           apple: true,
           email: true,
-          explicitSessionParams: {
+          explicitSession: createExplicitSession({
             chainId: 42161,
             nativeTokenSpending: {
               valueLimit: parseEther('0.01'), // Allow spending up to 0.01 ETH for gas fees
@@ -123,7 +134,7 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
                 ]
               })
             ]
-          }
+          })
         });
         ```
 
@@ -213,39 +224,39 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
         - `dappOrigin`
         - `signIn.projectName`, `appName`
         - `chainIds`, `defaultChainId`
-        - `explicitSessionParams` (opcional; `nativeTokenSpending` por defecto es `valueLimit: 0`)
+        - `explicitSession` (opcional; solicita permisos y límites explícitos de sesión)
         - `includeFeeOptionPermissions`, `enableImplicitSession`
         - `nodesUrl`, `relayerUrl`
         - `walletConnect`
 
         ```typescript [config.ts]
-        import { createConfig } from "@0xsequence/connect";
+        import { createConfig, createExplicitSession } from "@0xsequence/connect";
 
         export const config: any = createConfig({
           projectAccessKey: "AQAAAAAAAABtDHG1It7lxRF_9bbxw4diip8",
           signIn: {
             projectName: 'Sequence Web SDK Demo',
           },
-          walletUrl: 'https://next-acme-wallet.sequence-dev.app',
+          walletUrl: 'https://acme-wallet.ecosystem-demo.xyz',
           dappOrigin: window.location.origin,
           appName: 'Sequence Web SDK Demo',
           chainIds: [42161],
           defaultChainId: 42161,
           google: true,
           apple: true,
           email: true,
-          explicitSessionParams: { ... }
+          explicitSession: createExplicitSession({ ... })
         });
         ```
 
-        El `walletUrl` es la URL del Ecosystem Wallet que su dApp usará. Para nuestra demo, estamos usando el [Acme Ecosystem Wallet](https://next-acme-wallet.sequence-dev.app).
+        El `walletUrl` es la URL del Ecosystem Wallet que su dApp utilizará. Para nuestra demostración, estamos usando el [Acme Ecosystem Wallet](https://acme-wallet.ecosystem-demo.xyz).
 
         El `dappOrigin` es el origen de su dapp, usado para verificar de dónde proviene el usuario.
 
-        El objeto `explicitSessionParams` permite que su dapp solicite permisos específicos al usuario al conectarse.
-        Estos permisos pueden autorizar a su dapp a realizar ciertas acciones en nombre del usuario durante un período definido, creando una experiencia más fluida sin solicitudes de transacción.
+        El objeto `explicitSession` permite que su dapp solicite permisos específicos al usuario al conectarse.
+        Estos permisos pueden autorizar a su dapp a realizar ciertas acciones en nombre del usuario por un periodo definido, creando una experiencia más fluida sin ventanas emergentes de transacción.
 
-        `nativeTokenSpending` es opcional. Si se omite, la sesión tendrá por defecto un `valueLimit` de token nativo de `0`.
+        `nativeTokenSpending` es opcional. Si se omite, la sesión no tendrá asignado un límite de gasto de tokens nativos.
 
         Por ejemplo, creemos una sesión explícita que permita a su dapp `depositar 100 USDC en el pool de AAVE V3 en Arbitrum, en nombre del usuario durante las próximas 24 horas`
 
@@ -261,15 +272,15 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
           signIn: {
             projectName: 'Sequence Web SDK Demo',
           },
-          walletUrl: 'https://next-acme-wallet.sequence-dev.app',
+          walletUrl: 'https://acme-wallet.ecosystem-demo.xyz',
           dappOrigin: window.location.origin,
           appName: 'Sequence Web SDK Demo',
           chainIds: [42161],
           defaultChainId: 42161,
           google: true,
           apple: true,
           email: true,
-          explicitSessionParams: {
+          explicitSession: createExplicitSession({
             chainId: 42161,
             nativeTokenSpending: {
               valueLimit: parseEther('0.01'), // Allow spending up to 0.01 ETH for gas fees
@@ -298,7 +309,7 @@ Primero, asegúrese de haber creado una cuenta de Sequence Project. Si aún no t
                 ]
               })
             ]
-          }
+          })
         });
         ```
 

es/sdk/web/wallet-sdk/ecosystem/permissions-deep-dive.mdx

@@ -0,0 +1,91 @@
+---
+description: Guía práctica para construir permisos de sesión explícitos para Ecosystem Wallet (Web SDK)
+sidebarTitle: Análisis profundo de permisos
+---
+
+Esta página recopila orientación práctica y errores comunes al construir **permisos de sesión explícitos** para Ecosystem Wallet (Web SDK / `@0xsequence/connect`).
+
+Si aún no ha configurado Connect, comience con [Primeros pasos](/sdk/web/wallet-sdk/ecosystem/getting-started).
+
+---
+
+## Modelo mental
+Una sesión explícita es una _concesión de autoridad limitada_:
+- **Alcance:** qué llamadas están permitidas (destinos + firmas de función + reglas de parámetros)
+- **Presupuesto:** cuánto valor puede moverse (límite de gasto nativo, límites ERC20)
+- **Tiempo:** ventana de expiración
+
+Cuando solicita una sesión explícita, el usuario aprueba ese conjunto de permisos en la interfaz de la wallet. Después de la aprobación, su dApp (o una automatización del lado del servidor, según su arquitectura) puede ejecutar transacciones dentro de esos límites sin solicitar repetidamente la aprobación del usuario.
+
+---
+
+## Patrones para construir permisos
+
+### 1) Permisos específicos por destino (recomendado cuando sea posible)
+Si su caso de uso tiene un contrato de destino conocido (por ejemplo, “depositar en un pool de Aave”, “mintear desde este contrato NFT”), prefiera un permiso restringido con:
+- una sola `address`
+- una `functionSignature` concreta
+- reglas de parámetros
+
+Este es el método más seguro y fácil de razonar.
+
+### 2) Transferencias a destinatarios abiertos (requiere una construcción diferente)
+Si su experiencia de usuario es “enviar tokens a **cualquier** destinatario” (por ejemplo, una app de wallet), está otorgando una autoridad más amplia.
+
+**Recomendación:**
+- Para **transferencias ERC20** abiertas, el enfoque estándar es permitir el contrato de token `transfer(address to, uint256 value)` con una regla de **límite de valor** (y _sin_ regla `to=EQUAL`).
+- Para **envíos de tokens nativos** abiertos, use un patrón de **forwarder**. En configuraciones de wallet Sequence, un enfoque común es otorgar permiso de destino al `ValueForwarder` de la cadena y enviar tokens nativos mediante una llamada forward.
+
+> Si su dApp no necesita destinatarios abiertos, no los otorgue.
+
+---
+
+## Opciones de comisión y por qué importan (comportamiento de envío)
+Al enviar una transacción mediante el relay de Sequence, se selecciona una **opción de comisión** para pagar la ejecución.
+
+### Comportamientos clave
+
+- Si su aplicación depende de transacciones relayed, el relayer debe poder determinar _cómo se pagan las comisiones_.
+- En la práctica, su aplicación debe hacer una de las siguientes:
+  - activar la inclusión automática de permisos de comisión (ver `includeFeeOptionPermissions`), o
+  - incluir explícitamente los permisos necesarios relacionados con comisiones en la sesión.
+
+### Error común
+Los desarrolladores suelen construir un permiso de llamada válido (por ejemplo, ERC20 `transfer`) pero omiten los permisos relacionados con comisiones. La transacción puede fallar al enviarse porque el relayer no puede seleccionar una vía válida de pago de comisión.
+
+**Recomendación:** para la mayoría de las dApps, active `includeFeeOptionPermissions` a menos que tenga una razón para controlar completamente la forma de los permisos de comisión.
+
+---
+
+## Depuración de bajo nivel con `@0xsequence/dapp-client-cli`
+El Web SDK abstrae gran parte de la maquinaria subyacente. Cuando necesite depurar "¿qué está haciendo el relayer?", la CLI puede ser una herramienta útil.
+
+### Flujos de trabajo útiles
+
+1. **Inspeccionar opciones de comisión** para un paquete de transacciones:
+
+```bash
+npx @0xsequence/dapp-client-cli fee-options \
+  --chain-id <chainId> \
+  --transactions '<json array of {to,data,value}>'
+```
+
+2. **Enviar una transacción** con una opción de comisión elegida explícitamente:
+
+```bash
+npx @0xsequence/dapp-client-cli send-transaction \
+  --chain-id <chainId> \
+  --transactions '<json array of {to,data,value}>' \
+  --fee-option '<json object from fee-options>'
+```
+
+3. **Comparar el conjunto de permisos** que solicitó versus las llamadas que intenta realizar.
+
+Consejo: comience con un conjunto de permisos específicos por destino y amplíe el alcance según sea necesario.
+
+---
+
+## Lecturas recomendadas
+
+- [Resolución de direcciones de tokens con el Sequence Token Directory](/sdk/web/wallet-sdk/ecosystem/token-directory)
+- [Primeros pasos](/sdk/web/wallet-sdk/ecosystem/getting-started)

es/sdk/web/wallet-sdk/ecosystem/token-directory.mdx

@@ -0,0 +1,108 @@
+---
+description: Resuelva direcciones y decimales de tokens por cadena usando el Sequence Token Directory
+sidebarTitle: Directorio de Tokens
+---
+
+Cuando un usuario dice “enviar **USDC en Base**” necesita mapear:
+- `(chainId, symbol)` → `tokenAddress`
+- `symbol` → `decimals` (para `parseUnits`)
+
+Sequence mantiene un registro validado y multichain de tokens: **Sequence Token Directory**:
+- Repositorio: [https://github.com/0xsequence/token-directory](https://github.com/0xsequence/token-directory)
+- Índice: `index/index.json`
+- Lista ERC20 por cadena: `index/<chainName>/erc20.json`
+
+Esta página muestra una implementación mínima y amigable con el caché.
+
+---
+
+## Modelo de datos
+
+### 1) Cargue el índice maestro
+Obtener:
+- `https://raw.githubusercontent.com/0xsequence/token-directory/main/index/index.json`
+
+Este archivo le indica qué carpetas de cadenas existen e incluye hashes de contenido.
+
+### 2) Elija la carpeta de la cadena y obtenga la lista ERC20
+Obtener:
+- `https://raw.githubusercontent.com/0xsequence/token-directory/main/index/<chainName>/erc20.json`
+
+Esta lista sigue el esquema de listas de tokens de Uniswap (los tokens incluyen `address`, `symbol`, `decimals`, etc.).
+
+---
+
+## Ejemplo en Node.js (con caché)
+
+```ts
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const BASE = 'https://raw.githubusercontent.com/0xsequence/token-directory/main'
+
+function cacheDir() {
+  return path.join(os.homedir(), '.cache', 'sequence-token-directory')
+}
+
+async function fetchJson(url: string) {
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`fetch failed: ${res.status} ${url}`)
+  return res.json()
+}
+
+export async function resolveErc20BySymbol(chainId: number, symbol: string) {
+  const indexUrl = `${BASE}/index/index.json`
+  const index = await fetchJson(indexUrl)
+
+  // Find chain folder by chainId
+  let chainName: string | null = null
+  let sha256: string | null = null
+
+  for (const [name, meta] of Object.entries<any>(index.index)) {
+    if (name === '_external') continue
+    if (String(meta?.chainId) !== String(chainId)) continue
+    chainName = name
+    sha256 = meta?.tokenLists?.['erc20.json'] || null
+    break
+  }
+
+  if (!chainName || !sha256) throw new Error(`No ERC20 list for chainId=${chainId}`)
+
+  // Cache per-chain list by hash
+  const fp = path.join(cacheDir(), `${chainId}.erc20.${String(sha256).slice(0, 12)}.json`)
+  if (fs.existsSync(fp)) {
+    const cached = JSON.parse(fs.readFileSync(fp, 'utf8'))
+    return cached.tokens.find((t: any) => String(t.symbol).toUpperCase() === symbol.toUpperCase()) || null
+  }
+
+  const listUrl = `${BASE}/index/${chainName}/erc20.json`
+  const list = await fetchJson(listUrl)
+
+  fs.mkdirSync(path.dirname(fp), { recursive: true })
+  fs.writeFileSync(fp, JSON.stringify(list), 'utf8')
+
+  return list.tokens.find((t: any) => String(t.symbol).toUpperCase() === symbol.toUpperCase()) || null
+}
+```
+
+---
+
+## Cómo usarlo en permisos
+Una vez que resuelva:
+- `token.address`
+- `token.decimals`
+
+Puede:
+- construir un permiso para `transfer(address to, uint256 value)`
+- construir una interfaz que acepte símbolos en lugar de direcciones
+
+Ejemplo de regla de permiso (ERC20):
+- permitir `transfer(to=ANY, value<=limit)` usando una regla de límite de valor
+
+---
+
+## Dónde se referencia esto
+
+- [Análisis profundo de permisos](/sdk/web/wallet-sdk/ecosystem/permissions-deep-dive)
+- [Primeros pasos](/sdk/web/wallet-sdk/ecosystem/getting-started)

es/solutions/wallets/developers/ecosystem-wallet/react_quickstart.mdx

@@ -27,7 +27,9 @@ El Sequence SDK ahora es una dependencia en su proyecto, listo para usarse.
 ## 🔗 Paso 3: Integre con su app React
 Finalmente, envuelva su aplicación con nuestro proveedor de wallet. Esto hace que todas las funciones de conexión estén disponibles para cualquier componente dentro de su dApp.
 
-También estamos creando una sesión que solicita permiso para gastar hasta 100 tokens en nombre del usuario, lo que abre la puerta a automatizaciones y mejoras en la experiencia de usuario.
+También estamos creando una sesión explícita que solicita permiso para gastar hasta 100 tokens en nombre del usuario, abriendo la puerta a automatizaciones y mejoras de experiencia de usuario.
+
+Ver: [Análisis profundo de permisos](/sdk/web/wallet-sdk/ecosystem/permissions-deep-dive) y [Directorio de tokens](/sdk/web/wallet-sdk/ecosystem/token-directory).
 
 ```tsx
 import { SequenceConnect, createConfig, createContractPermission, createExplicitSession, useOpenConnectModal, type SequenceConnectConfig } from "@0xsequence/connect";