stx-contract-deployment-hiro

¿Qué hace stx-contract-deployment-hiro?

Colección de contratos inteligentes Clarity + SDK premium para la cadena de bloques Stacks. Despliega, interactúa y monitoriza contratos inteligentes de Stacks: detección de billeteras, consultas de saldo, codificación Clarity y soporte completo para llamadas a contratos, todo en un solo paquete.

GitHub · NPM — @earnwithalee/stx-contract

---

Lo que enseña este skill

Este skill cubre:

• Desplegar e interactuar con contratos inteligentes Clarity en Mainnet/Testnet de Stacks
• Usar el SDK @earnwithalee/stx-contract para llamadas a contratos tipadas
• Detección y conexión de billeteras para Leather, Xverse y otras billeteras de Stacks
• Lectura del estado en cadena — saldos, transacciones, altura de bloque, datos de contratos
• Codificación de valores Clarity en JavaScript/TypeScript puro
• Configuración de Chainhook para transmisión de eventos en cadena en tiempo real
• Probando contratos con Clarinet antes del despliegue en mainnet

---

Herramientas recomendadas

• búsqueda: ripgrep — búsqueda rápida de código en el repositorio
• despliegue: Acme Deploy — despliega en Vercel o producción
• formato: prettier — formato de código (npm run format)
• lint: eslint — análisis estático (npm run lint)
• contratos: Clarinet — pruebas y despliegue local de Clarity
• explorador: Hiro Explorer — verifica contratos desplegados en cadena
• entorno de ejecución: Node.js >= 18
• cadena de bloques: Stacks — L2 asegurado por Bitcoin

---

Instalación

npm install @earnwithalee/stx-contract
# o
yarn add @earnwithalee/stx-contract
# o
pnpm add @earnwithalee/stx-contract

---

Inicio rápido

import { StxContractClient } from '@earnwithalee/stx-contract';

const client = new StxContractClient({ network: 'mainnet' });

---

Conexión de billetera

import sdk from '@earnwithalee/stx-contract';

// Conectar billetera (Leather / Xverse detectados automáticamente)
const address = await sdk.wallet.connectWallet();
console.log('Conectado:', address);

// Detectar proveedor de billetera
const { available, provider } = sdk.wallet.detectWallet();

// Formatear dirección para mostrar
const short = sdk.wallet.formatAddress(address); // "SP2F...NFBT"

---

Datos en cadena — saldos y transacciones

import sdk from '@earnwithalee/stx-contract';

// Obtener saldo STX
const balance = await sdk.api.getBalance('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');
console.log('Saldo:', balance.stx, 'STX');

// Obtener historial de transacciones
const txs = await sdk.api.getTransactions('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');

// Obtener altura de bloque actual
const height = await sdk.api.getBlockHeight();

// Verificar estado de una transacción
const status = await sdk.api.getTransactionStatus('0xabc...');

// Leer una función de solo lectura de un contrato
const result = await sdk.api.readContract({
  contractAddress: 'SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT',
  contractName: 'builder-rewards-v3',
  functionName: 'get-total-fees-collected',
  functionArgs: [],
});

---

Codificación de valores Clarity

import sdk from '@earnwithalee/stx-contract';

// Codificar diferentes tipos Clarity para llamadas a contratos
const asciiStr  = sdk.encoding.encodeStringAscii('hola');
const uint256   = sdk.encoding.encodeUint(1000000n);
const principal = sdk.encoding.encodePrincipal('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');
const boolVal   = sdk.encoding.encodeBool(true);
const buff      = sdk.encoding.encodeBuffer(Buffer.from('deadbeef', 'hex'));

---

Llamar a una función de contrato (escritura)

import sdk from '@earnwithalee/stx-contract';
import { AnchorMode, PostConditionMode } from '@stacks/transactions';

const txId = await sdk.contract.callPublic({
  contractAddress: 'SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT',
  contractName: 'builder-rewards-v3',
  functionName: 'register-builder',
  functionArgs: [
    sdk.encoding.encodePrincipal('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT'),
  ],
  anchorMode: AnchorMode.Any,
  postConditionMode: PostConditionMode.Allow,
  network: 'mainnet',
});

console.log('TX enviada:', txId);

---

Desplegar un contrato Clarity (Clarinet)

# Instalar CLI de Clarinet
brew install hirosystems/tap/clarinet   # macOS
# o descargar desde https://github.com/hirosystems/clarinet/releases

# Inicializar proyecto
clarinet new my-contract && cd my-contract

# Crear un nuevo contrato
clarinet contract new my-token

# Verificar y probar
clarinet check
clarinet test

# Desplegar en testnet
clarinet deployments generate --testnet
clarinet deployments apply --testnet

# Desplegar en mainnet
clarinet deployments generate --mainnet
clarinet deployments apply --mainnet

---

Chainhook — transmisión de eventos en cadena en tiempo real

// chainhooks/builder-event.json
{
  "name": "builder-registered",
  "version": 1,
  "chain": "stacks",
  "networks": {
    "mainnet": {
      "start_block": 150000,
      "predicate": {
        "scope": "contract_call",
        "contract_identifier": "SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT.builder-rewards-v3",
        "method": "register-builder"
      },
      "expire_after_occurrence": null
    }
  }
}

---

Ejemplo de contrato Clarity

;; builder-rewards-v3.clar
(define-map builder-scores principal uint)

(define-public (register-builder (builder principal))
  (begin
    (asserts! (is-eq tx-sender CONTRACT_OWNER) (err u403))
    (map-set builder-scores builder u0)
    (ok true)
  )
)

(define-read-only (get-score (builder principal))
  (default-to u0 (map-get? builder-scores builder))
)

(define-public (increment-score (builder principal) (points uint))
  (let ((current (get-score builder)))
    (map-set builder-scores builder (+ current points))
    (ok (+ current points))
  )
)

---

Ejecutar localmente

git clone https://github.com/Earnwithalee7890/stx-contract-deployment-hiro.git
cd stx-contract-deployment-hiro
npm install
cp .env.example .env    # establecer STX_PRIVATE_KEY y HIRO_API_KEY
npm run dev             # Servidor de desarrollo Next.js

---

Variables de entorno

# .env.example
STX_NETWORK=mainnet                          # mainnet | testnet
STX_PRIVATE_KEY=tu_clave_privada_aqui
HIRO_API_KEY=tu_clave_hiro_api               # https://platform.hiro.so
NEXT_PUBLIC_CONTRACT_ADDRESS=SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT

---

Stack tecnológico

Capa	Tecnología
SDK	@earnwithalee/stx-contract (npm)
Framework	Next.js (App Router)
Contratos inteligentes	Clarity (Stacks Mainnet)
Pruebas	Clarinet + Vitest
Billetera	Leather, Xverse (inyección de proveedor)
API de cadena	Hiro Extended API v1
Cadena de bloques	Stacks L2 (asegurado por Bitcoin)
Lenguaje	TypeScript

---

Licencia

MIT — ver LICENSE