PH
EN
ES
BR
RO
CN
RU
LT
Amethyst On-Chain Ecosystem
AMTkn, VIP Pass NFTs, Item NFTs & Presale 鈥 User Whitepaper
Last update / 脷ltima actualizaci贸n: 2025-11-30
1. Overview
The Amethyst on-chain ecosystem connects one main currency (AMTkn) with utility NFTs used across the AmethystMU world: VipPassNFT (VIP access + AMTkn balance), Item NFTs (game items as ERC-721) and a presale contract that distributes AMTkn over time using a vesting system.
Core Components
AMTkn (ERC-20)
Main token of the ecosystem, cross-chain between Ethereum and Base. Used for purchases, NFTs and in-game utilities.
VipPassNFT (ERC-721)
VIP pass collection. Each pass can hold an internal AMTkn balance to spend on Amethyst products and services.
ItemNFT721Upgradeable
Item NFTs with on-chain metadata (stats + itemHex), purchasable in AMTkn and linked to the in-game warehouse through lock/unlock.
AMTknPresale
Presale and vesting contract. Users buy AMTkn with ETH at a dynamic rate using a Chainlink price feed, then claim in phases.
2. AMTkn 鈥 Core Currency
2.1 Purpose
AMTkn is the main currency of the Amethyst ecosystem. It is used to:
- Buy VipPassNFTs (VIP passes).
- Purchase Item NFTs listed on-chain.
- Deposit into VIP passes to unlock in-game or web utilities.
- Participate in future DeFi utilities (staking, liquidity, etc.) where available.
Technical Profile
- Standard: ERC-20 (upgradeable).
- Decimals: 18.
- Maximum Supply: 1,000,000,000 AMTkn (hard cap in the contract).
- Permit: Supports off-chain approvals (ERC-20 Permit) via the presale.
Minting & Distribution
AMTkn uses an authorized minter list. Each authorized minter has a fixed mint limit, and once this limit is used, the minter is automatically deactivated. This protects users from unlimited minting and helps keep supply predictable.
Pause & Emergency Guard
The token can be paused in case of emergencies or maintenance. When paused, token transfers and mint operations are blocked. A dedicated guardian role can temporarily toggle an emergency mode that pauses the system, and the owner manages long-term upgrades.
Upgradeable with Cooldowns
AMTkn is an upgradeable contract (UUPS). Upgrades are protected by cooldown and delay timers so that changes cannot be pushed too frequently and can be monitored by the community before they take effect.
2.2 Cross-Chain Architecture
AMTkn is designed to operate on Ethereum Mainnet and a scalable Layer-2 network (Base) using official wrappers/bridges. Users only see a simple experience:
- Holding AMTkn on Ethereum or Base depending on gas cost and their preferences.
- Interacting with the same ecosystem (passes, NFTs, presale) from supported chains.
The technical bridge logic is handled by dedicated contracts and backend services; users simply follow the steps shown in the Amethyst interface.
3. VipPassNFT 鈥 VIP Pass with AMTkn Balance
VipPassNFT is a collection of upgradeable ERC-721 tokens. Each pass acts as a VIP membership and also as a mini-wallet that can hold AMTkn inside the NFT itself.
What a VIP Pass Represents
- A unique NFT with a fixed maximum supply.
- Ownership of the pass (fully transferable when not paused).
- Access to VIP-only features in the Amethyst ecosystem (web + in-game).
How to Buy a VipPassNFT
- You pay a fixed pass price in AMTkn.
- The AMTkn used for purchase is sent to a treasury address.
- A new tokenId is minted directly to your wallet.
- Once the collection reaches its maxSupply, no more passes can be created.
Deposits, Withdrawals & Spending
Each VIP pass can hold an internal AMTkn balance:
- Deposit: send AMTkn from your wallet into the NFT.
- Withdraw: move AMTkn back from the NFT to your wallet.
- Spend: use the NFT鈥檚 balance to pay the Amethyst treasury (for special services, upgrades, events, etc.).
Only the owner of the NFT can deposit, withdraw or spend from that pass.
Control & Upgrades
- The collection is upgradeable via UUPS and controlled by an admin role.
- The contract can be paused to temporarily stop transfers and operations.
- Enumeration is supported (you can list all your passes and token IDs).
4. ItemNFT721Upgradeable 鈥 Game Items as NFTs
ItemNFT721Upgradeable turns in-game items into ERC-721 NFTs with compact, on-chain metadata. These NFTs can be bought with AMTkn, and they can be locked and unlocked against the in-game warehouse, allowing a bridge between on-chain ownership and off-chain game inventory.
Listings are created by the administrators; users interact by purchasing and managing the lock state of their NFTs.
On-Chain Item Metadata
Each item NFT stores a compact structure with its main attributes:
| Type & ID | Group and internal ID of the item (e.g. sword, armor, wings). |
|---|---|
| Level & Life | Upgrade level (e.g. +0 to +15) and durability. |
| Flags | Encodes options like luck, skill and excellent options. |
| ItemHex | Original itemHex stored as bytes16. |
| Name Hash | keccak256 hash of the normalized item name. |
A fingerprint is computed out of these fields to avoid duplicate listings with the exact same configuration.
On-Chain Listings in AMTkn
- Admins create listings with a price in AMTkn, a maximum edition cap and a seller address.
- Users buy by calling
purchase()and paying in AMTkn. - Payment is automatically split between seller and a fee receiver (if fees are configured).
- Each mint increments an internal serial for limited editions.
Bridge with In-Game Warehouse
- Initiate Lock: the NFT owner starts a lock for a given account ID.
- Confirm Lock: the backend signs a message once the item is registered in the game鈥檚 warehouse (global vault).
- Locked State: while locked, the NFT cannot be transferred between wallets.
- Unlock: once the game returns the item, the backend signs an unlock and the NFT becomes transferable again.
This keeps on-chain ownership and off-chain game state in sync.
Visuals & Marketplaces
- Configurable baseURI for
tokenURI(IPFS or custom CDN). - contractURI for collection-level metadata (icon, description, links).
- Designed to be indexed by NFT marketplaces supporting metadata endpoints.
5. AMTknPresale 鈥 Dynamic Presale & Vesting
The AMTknPresale contract is responsible for distributing AMTkn to early supporters before the DEX phase. It uses a Chainlink price feed for ETH/USD and a vesting schedule so tokens are unlocked gradually instead of all at once.
How Buying Works
- You send ETH to the presale contract鈥檚
buyTokens()function. - The contract reads the current ETH/USD price from Chainlink.
- It converts your ETH to a USD value and then to AMTkn using the current rate.
- The rate increases progressively after each purchase, making later purchases more expensive (dynamic pricing).
Wallet Limits & Whitelist
- There is a maximum number of tokens per wallet to avoid concentration.
- There is also a maximum ETH per transaction for risk management.
- The presale may optionally require a whitelist (only approved addresses can buy when enabled).
Vesting & Claims
Instead of sending all tokens immediately, the presale saves your purchase as a vesting balance. Tokens are then claimed over multiple phases:
- A global claim start time is configured.
- There are several phases (e.g. 4 phases: 20-20-30-30%).
- Each phase has an interval; once a phase is active, you can claim that portion.
- You can claim phases one by one or use a 鈥渃laim all鈥 function (it will only claim the phases that are already available).
After all phases are claimed, the internal vesting record is reset and you are free to participate in future cycles if allowed.
Post-Presale & DEX Listing
After the presale period, AMTkn is planned to be listed on decentralized exchanges (DEXs). The target is to start DEX trading approximately six months after the presale launch, once vesting and liquidity planning are aligned.
A sell-back function may be enabled later, allowing users to sell AMTkn back to the contract under defined conditions. When selling is enabled, tokens processed can be split between a burn address and a treasury, helping control supply and fund development.
6. User Journey in the Amethyst Ecosystem
From a player鈥檚 perspective, the system is designed to be intuitive. A typical user path looks like this:
Join the Presale (Optional)
Connect your wallet, send ETH to the presale, and lock in AMTkn at the current rate. Your allocation vests over multiple phases.
Claim AMTkn Over Time
When claim phases open, use the claim interface to gradually receive your AMTkn directly in your wallet.
Mint a VipPassNFT
Use AMTkn to purchase one or more VIP passes. Each pass gives you access to exclusive features and can hold an internal AMTkn balance.
Deposit & Spend Through the Pass
Deposit AMTkn into your passes and spend this balance on services, upgrades and events across the AmethystMU ecosystem.
Acquire Item NFTs
Browse the on-chain marketplace, purchase item NFTs with AMTkn, and use lock/unlock flows to link them with your in-game warehouse.
Trade, Collect & Participate
Hold, trade or collect AMTkn, VipPassNFTs and item NFTs, and use them in future events, expansions and cross-chain features as the ecosystem grows.
7. Security, Upgrades & Governance Principles
Upgradeable, But Guarded
All main contracts (AMTkn, VipPassNFT, ItemNFT721Upgradeable, AMTknPresale) are UUPS-upgradeable. Upgrades are restricted to specific admin roles and use cooldowns/delays to reduce the risk of rushed changes.
Pausing Capability
Each contract can be put into a paused state to stop sensitive operations if abnormal behavior is detected or maintenance is required. When paused, functions like transfers, purchases or claims are temporarily disabled.
Oracle & Price Integrity
The presale relies on a Chainlink price feed for ETH/USD pricing. The contract can enforce freshness checks (anti-stale protection) to avoid using outdated oracle values.
Role Separation
Minter addresses, guardians and admin accounts are separated at the smart-contract level. This separation allows finer control and risk management without exposing operational details to end users.
8. Risks & General Disclaimer
Participation in the Amethyst ecosystem involves risks. Token prices may be volatile, NFTs may fluctuate in value and smart contracts, while carefully designed, can still contain undiscovered bugs.
- Not financial advice: AMTkn and the associated NFTs are utility assets for the Amethyst ecosystem. They are not guaranteed investments.
- Do your own research: Always evaluate your own risk tolerance and, if needed, consult an independent professional.
- Jurisdiction: You are responsible for complying with the laws and regulations of your country before interacting with tokens or NFTs.
By using AMTkn, VipPassNFT, Item NFTs or the presale, you acknowledge that you understand and accept these risks.
1. Resumen General
El ecosistema on-chain de Amethyst conecta una moneda principal (AMTkn) con NFTs de utilidad utilizados en el mundo de AmethystMU: VipPassNFT (pases VIP con saldo), NFTs de 铆tems (铆tems del juego como ERC-721) y un contrato de preventa que distribuye AMTkn en el tiempo mediante un sistema de vesting.
Componentes Principales
AMTkn (ERC-20)
Token central del ecosistema, con soporte cross-chain entre Ethereum y Base. Se usa para compras, NFTs y utilidades in-game.
VipPassNFT (ERC-721)
Colecci贸n de pases VIP. Cada pase puede mantener un saldo interno de AMTkn para gastarlo en productos y servicios de Amethyst.
ItemNFT721Upgradeable
NFTs de 铆tems con metadata on-chain (stats + itemHex), comprables en AMTkn y vinculados al ba煤l del juego mediante lock/unlock.
AMTknPresale
Contrato de preventa y vesting. Los usuarios compran AMTkn con ETH a una tasa din谩mica usando un or谩culo Chainlink y luego reclaman en fases.
2. AMTkn 鈥 Moneda Central
2.1 Prop贸sito
AMTkn es la moneda principal del ecosistema Amethyst. Se utiliza para:
- Comprar VipPassNFTs (pases VIP).
- Adquirir NFTs de 铆tems listados on-chain.
- Depositar en pases VIP para activar utilidades web e in-game.
- Participar en utilidades DeFi futuras (staking, liquidez, etc.), donde est茅n disponibles.
Perfil T茅cnico
- Est谩ndar: ERC-20 (upgradeable).
- Decimales: 18.
- Suministro m谩ximo: 1,000,000,000 AMTkn (l铆mite fijado en contrato).
- Permit: Soporta aprobaciones off-chain (ERC-20 Permit) mediante la preventa.
Minting y Distribuci贸n
AMTkn utiliza una lista de minteadores autorizados. Cada minteador tiene un l铆mite m谩ximo y, cuando lo consume, queda desactivado autom谩ticamente. Esto protege a los usuarios contra un minting ilimitado y ayuda a mantener una oferta predecible.
Pausa y Modo Emergencia
El token puede ponerse en pausa en caso de emergencias o mantenimiento. Cuando est谩 pausado, las transferencias y operaciones de minting se bloquean. Un rol de guardi谩n puede activar temporalmente el modo emergencia y el propietario gestiona las actualizaciones a largo plazo.
Actualizable con Seguridad
AMTkn es un contrato actualizable (UUPS). Las actualizaciones est谩n protegidas por tiempos de espera (cooldown y delay) para evitar cambios continuos y permitir que la comunidad supervise las modificaciones importantes.
2.2 Arquitectura Cross-Chain
AMTkn est谩 dise帽ado para operar en Ethereum Mainnet y en una red de Capa 2 escalable (Base) utilizando wrappers/bridges oficiales. Para el usuario, la experiencia es simple:
- Mantener AMTkn en Ethereum o Base seg煤n el coste de gas y sus preferencias.
- Interactuar con el mismo ecosistema (pases, NFTs, preventa) desde las cadenas soportadas.
La l贸gica t茅cnica del bridge se maneja con contratos dedicados y servicios de backend; el usuario solo debe seguir los pasos indicados en la interfaz de Amethyst.
3. VipPassNFT 鈥 Pase VIP con Saldo de AMTkn
VipPassNFT es una colecci贸n de tokens ERC-721 actualizables. Cada pase act煤a como una membres铆a VIP y tambi茅n como una especie de monedero interno que puede contener AMTkn dentro del propio NFT.
Qu茅 Representa un Pase VIP
- Un NFT 煤nico con un suministro m谩ximo definido.
- Propiedad plena del pase (transferible cuando no est谩 pausado).
- Acceso a funciones exclusivas dentro del ecosistema Amethyst (web + in-game).
C贸mo Comprar un VipPassNFT
- Pagas un precio fijo en AMTkn por cada pase.
- El AMTkn utilizado se env铆a a una tesorer铆a del proyecto.
- Se crea un nuevo tokenId y se asigna a tu wallet.
- Cuando se alcanza el maxSupply, ya no pueden crearse m谩s pases.
Dep贸sitos, Retiros y Gastos
Cada pase VIP tiene un saldo interno de AMTkn:
- Depositar: env铆as AMTkn desde tu wallet al NFT.
- Retirar: devuelves AMTkn desde el NFT a tu wallet.
- Gastar: utilizas el saldo del NFT para pagar a la tesorer铆a (servicios, mejoras, eventos, etc.).
Solo el propietario del NFT puede usar el saldo de ese pase.
Control y Actualizaciones
- La colecci贸n es actualizable (UUPS) y est谩 controlada por un rol de admin.
- El contrato puede pausarse para detener temporalmente transferencias y operaciones.
- Incluye enumeraci贸n (es posible listar todos los pases de un usuario).
4. ItemNFT721Upgradeable 鈥 脥tems del Juego como NFTs
ItemNFT721Upgradeable convierte 铆tems del juego en NFTs ERC-721 con metadata compacta on-chain. Estos NFTs se compran con AMTkn y pueden bloquearse y desbloquearse contra el ba煤l global del juego, creando un puente entre la propiedad on-chain y el inventario off-chain.
Los listados son creados por la administraci贸n; los usuarios compran, poseen y gestionan el estado de bloqueo de sus NFTs.
Metadata On-Chain de 脥tems
Cada NFT de 铆tem almacena una estructura compacta con sus atributos principales:
| Tipo e ID | Grupo e ID interno del 铆tem (ej: espada, set, alas). |
|---|---|
| Nivel & Vida | Nivel de mejora (ej: +0 a +15) y durabilidad. |
| Flags | Codifica opciones como luck, skill y excellent. |
| ItemHex | itemHex original almacenado como bytes16. |
| Hash de Nombre | keccak256 del nombre normalizado del 铆tem. |
Se calcula un fingerprint a partir de estos campos para evitar listados duplicados con la misma configuraci贸n exacta.
Ventas On-Chain en AMTkn
- Los admins crean listados con precio en AMTkn, l铆mite de ediciones y direcci贸n del vendedor.
- Los usuarios compran llamando a
purchase()y pagando en AMTkn. - El pago se divide entre el vendedor y una direcci贸n de comisiones (si est谩 configurada).
- Cada mint aumenta un serial interno para colecciones de edici贸n limitada.
Puente con el Ba煤l del Juego
- Inicio de lock: el due帽o del NFT inicia el lock para un AccountID concreto.
- Confirmaci贸n: el backend firma una confirmaci贸n cuando el 铆tem ya est谩 registrado en el ba煤l global del juego.
- Estado bloqueado: mientras est谩 bloqueado, el NFT no puede transferirse entre wallets.
- Unlock: cuando el juego devuelve el 铆tem, el backend firma el desbloqueo y el NFT vuelve a ser transferible.
As铆 se mantiene la propiedad on-chain sincronizada con el estado in-game.
Visualizaci贸n y Mercados
- baseURI configurable para
tokenURI(IPFS o CDN propia). - contractURI con metadata de colecci贸n (icono, descripci贸n, enlaces).
- Dise帽ado para ser indexado por marketplaces NFT que soporten endpoints de metadata.
5. AMTknPresale 鈥 Preventa Din谩mica y Vesting
El contrato AMTknPresale se encarga de distribuir AMTkn a los primeros participantes antes de la fase en DEX. Utiliza un or谩culo Chainlink para el precio ETH/USD y un calendario de vesting para que los tokens se liberen de forma progresiva.
C贸mo Funciona la Compra
- Env铆as ETH a la funci贸n
buyTokens()del contrato de preventa. - El contrato lee el precio actual ETH/USD desde Chainlink.
- Convierte tu ETH a valor en USD y luego a AMTkn seg煤n la tasa (rate) vigente.
- La tasa aumenta progresivamente tras cada compra, haciendo que las compras posteriores sean m谩s caras (precio din谩mico).
L铆mites y Whitelist
- Existe un m谩ximo de tokens por wallet para evitar concentraci贸n excesiva.
- Tambi茅n hay un m谩ximo de ETH por transacci贸n para control de riesgo.
- La preventa puede requerir una whitelist (solo direcciones aprobadas podr谩n comprar cuando est茅 activa).
Vesting y Reclamos
En lugar de enviar todos los tokens al instante, la preventa guarda tu compra como un saldo en vesting. Luego se reclama en varias fases:
- Se define un claimStart (fecha de inicio de reclamos).
- Hay varias fases (por ejemplo, 4 fases: 20-20-30-30%).
- Cada fase tiene un intervalo; cuando llega la fecha de una fase, puedes reclamar esa parte.
- Puedes reclamar fase por fase o usar una funci贸n de 鈥渞eclamar todo lo disponible鈥.
Una vez reclamadas todas las fases, se reinician los registros internos de vesting y el usuario puede participar en nuevos ciclos si se habilitan.
Post-Preventa y Listado en DEX
Tras la etapa de preventa, se planea listar AMTkn en exchanges descentralizados (DEX). El objetivo es comenzar la negociaci贸n en DEX aproximadamente a los seis meses de iniciada la preventa, alineando vesting y planificaci贸n de liquidez.
M谩s adelante se puede habilitar una funci贸n de venta de vuelta al contrato, bajo condiciones definidas. Cuando esta funci贸n est谩 activa, los tokens vendidos pueden dividirse entre una direcci贸n de quema y una tesorer铆a, ayudando a controlar la oferta y financiar el desarrollo.
6. Flujo de Usuario en el Ecosistema Amethyst
Desde la perspectiva del jugador, el sistema se ha dise帽ado para ser intuitivo. Un flujo t铆pico es:
Participar en la Preventa (Opcional)
Conectas tu wallet, env铆as ETH a la preventa y aseguras AMTkn a la tasa actual. Tu asignaci贸n entra en vesting por fases.
Reclamar AMTkn en el Tiempo
Cuando se habilitan las fases, utilizas la interfaz de reclamo para recibir tus AMTkn gradualmente en tu wallet.
Mintear un VipPassNFT
Utilizas AMTkn para comprar uno o varios pases VIP. Cada pase te da acceso a funciones exclusivas y puede mantener saldo interno.
Depositar y Gastar Desde el Pase
Depositas AMTkn en tus pases y utilizas ese saldo para pagar servicios, mejoras y eventos en todo el ecosistema AmethystMU.
Obtener NFTs de 脥tems
Navegas el marketplace on-chain, compras NFTs de 铆tems con AMTkn y usas el flujo de lock/unlock para vincularlos con tu ba煤l del juego.
Tradear, Coleccionar y Participar
Mantienes, intercambias o coleccionas AMTkn, VipPassNFTs y NFTs de 铆tems, y los usas en eventos, expansiones y funciones cross-chain a medida que el ecosistema crece.
7. Seguridad, Actualizaciones y Gobernanza
Contratos Actualizables con Protecci贸n
Los contratos principales (AMTkn, VipPassNFT, ItemNFT721Upgradeable, AMTknPresale) son UUPS-upgradeable. Las actualizaciones est谩n limitadas a roles administrativos espec铆ficos y utilizan cooldowns/delays para reducir el riesgo de cambios apresurados.
Capacidad de Pausa
Cada contrato puede ponerse en pausa para detener operaciones sensibles si se detecta un comportamiento anormal o si se requiere mantenimiento. En pausa, funciones como transferencias, compras o reclamos quedan temporalmente deshabilitadas.
Or谩culo y Precio
La preventa utiliza un or谩culo Chainlink para el precio ETH/USD. El contrato puede exigir que los datos sean recientes para evitar el uso de precios desactualizados.
Separaci贸n de Roles
Minteadores, guardianes y cuentas admin est谩n separados a nivel de contrato. Esta separaci贸n permite un control m谩s fino y una mejor gesti贸n de riesgos, sin exponer detalles operativos sensibles al usuario final.
8. Riesgos y Descargo de Responsabilidad
Participar en el ecosistema Amethyst implica riesgos. El precio del token puede ser vol谩til, el valor de los NFTs puede cambiar y los contratos inteligentes, aunque se dise帽en con cuidado, pueden contener bugs no descubiertos.
- No es asesor铆a financiera: AMTkn y los NFTs asociados son activos de utilidad del ecosistema Amethyst. No se garantizan retornos.
- Haz tu propia investigaci贸n: Eval煤a siempre tu tolerancia al riesgo y, si lo consideras necesario, consulta con un profesional independiente.
- Jurisdicci贸n: Eres responsable de cumplir las leyes y regulaciones de tu pa铆s antes de interactuar con tokens o NFTs.
Al utilizar AMTkn, VipPassNFT, NFTs de 铆tems o la preventa, confirmas que comprendes y aceptas estos riesgos.
