Earnwithalee7890/stx-contract-deployment-hiro

stx-contract-deployment-hiro은(는) 무엇을 하나요?

Clarity 스마트 컨트랙트 컬렉션 + Stacks 블록체인을 위한 프리미엄 SDK 지갑 감지, 잔액 조회, Clarity 인코딩, 전체 컨트랙트 호출 지원 — 하나의 패키지로 Stacks 스마트 컨트랙트를 배포, 상호작용 및 모니터링하세요.

GitHub · NPM — @earnwithalee/stx-contract

---

이 스킬이 가르치는 내용

이 스킬은 다음을 다룹니다:

• Stacks 메인넷/테스트넷에서 Clarity 스마트 컨트랙트 배포 및 상호작용
• 타입화된 컨트랙트 호출을 위한 @earnwithalee/stx-contract SDK 사용
• Leather, Xverse 및 기타 Stacks 지갑의 지갑 감지 및 연결
• 온체인 상태 읽기 — 잔액, 트랜잭션, 블록 높이, 컨트랙트 데이터
• 순수 JavaScript/TypeScript에서 Clarity 값 인코딩
• 실시간 온체인 이벤트 스트리밍을 위한 Chainhook 설정
• 메인넷 배포 전 Clarinet으로 컨트랙트 테스트

---

권장 도구

• 검색: ripgrep — 리포지토리 전체에서 빠른 코드 검색
• 배포: Acme Deploy — Vercel 또는 프로덕션에 배포
• 포맷: prettier — 코드 포맷팅 (npm run format)
• 린트: eslint — 정적 분석 (npm run lint)
• 컨트랙트: Clarinet — 로컬 Clarity 테스트 및 배포
• 탐색기: Hiro Explorer — 배포된 컨트랙트를 온체인에서 확인
• 런타임: Node.js >= 18
• 블록체인: Stacks — 비트코인으로 보호된 L2

---

설치

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

---

빠른 시작

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

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

---

지갑 연결

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

// 지갑 연결 (Leather / Xverse 자동 감지)
const address = await sdk.wallet.connectWallet();
console.log('연결됨:', address);

// 지갑 제공자 감지
const { available, provider } = sdk.wallet.detectWallet();

// 표시용 주소 포맷
const short = sdk.wallet.formatAddress(address); // "SP2F...NFBT"

---

온체인 데이터 — 잔액 및 트랜잭션

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

// STX 잔액 가져오기
const balance = await sdk.api.getBalance('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');
console.log('잔액:', balance.stx, 'STX');

// 트랜잭션 내역 가져오기
const txs = await sdk.api.getTransactions('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');

// 현재 블록 높이 가져오기
const height = await sdk.api.getBlockHeight();

// 트랜잭션 상태 확인
const status = await sdk.api.getTransactionStatus('0xabc...');

// 컨트랙트의 읽기 전용 함수 읽기
const result = await sdk.api.readContract({
  contractAddress: 'SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT',
  contractName: 'builder-rewards-v3',
  functionName: 'get-total-fees-collected',
  functionArgs: [],
});

---

Clarity 값 인코딩

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

// 컨트랙트 호출을 위한 다양한 Clarity 타입 인코딩
const asciiStr  = sdk.encoding.encodeStringAscii('hello');
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'));

---

컨트랙트 함수 호출 (쓰기)

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 제출됨:', txId);

---

Clarity 컨트랙트 배포 (Clarinet)

# Clarinet CLI 설치
brew install hirosystems/tap/clarinet   # macOS
# 또는 https://github.com/hirosystems/clarinet/releases 에서 다운로드

# 프로젝트 초기화
clarinet new my-contract && cd my-contract

# 새 컨트랙트 생성
clarinet contract new my-token

# 확인 및 테스트
clarinet check
clarinet test

# 테스트넷에 배포
clarinet deployments generate --testnet
clarinet deployments apply --testnet

# 메인넷에 배포
clarinet deployments generate --mainnet
clarinet deployments apply --mainnet

---

Chainhook — 실시간 온체인 이벤트 스트리밍

// 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
    }
  }
}

---

예제 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))
  )
)

---

로컬에서 실행

git clone https://github.com/Earnwithalee7890/stx-contract-deployment-hiro.git
cd stx-contract-deployment-hiro
npm install
cp .env.example .env    # STX_PRIVATE_KEY 및 HIRO_API_KEY 설정
npm run dev             # Next.js 개발 서버

---

환경 변수

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

---

기술 스택

계층	기술
SDK	@earnwithalee/stx-contract (npm)
프레임워크	Next.js (App Router)
스마트 컨트랙트	Clarity (Stacks 메인넷)
테스트	Clarinet + Vitest
지갑	Leather, Xverse (provider injection)
체인 API	Hiro Extended API v1
블록체인	Stacks L2 (비트코인 보안)
언어	TypeScript

---

라이선스

MIT — LICENSE 파일 참조