소개
Stellar Trade Contracts는 Stellar에서 구축된 오픈 소스 예측 시장 프로토타입인 Stellar Trade를 위한 Soroban 컨트랙트 워크스페이스입니다. 이 컨트랙트는 XLM이 시장 풀에 들어오는 방식, 참여자가 포지션을 줄이는 방식, 그리고 결과가 확정되거나 시장이 취소되었을 때 지급금과 환불금이 분배되는 방식을 관리합니다.
이 저장소는 애플리케이션을 뒷받침하는 컨트랙트를 구축, 테스트, 검토 또는 배포해야 하는 개발자를 위해 설계되었습니다. 시장 컨트랙트와 함께 토큰, 추천, 리더보드 및 통합 테스트용 크레이트도 포함되어 있습니다.
워크스페이스 이해하기
저장소는 각각 명확한 책임을 가진 다섯 개의 주요 크레이트로 구성됩니다.
prediction_market: 시장을 생성하고, 포지션을 접수하며, 포지션 축소를 처리하고, 결과 확정자의 작업을 관리하며, 비례 청구액을 계산하고, 취소 환불을 처리하고, 수수료를 관리하며, 분쟁 및 거버넌스를 지원합니다.stellar_trade_token: 관리자 제어, 승인된 발행자, 일시 중지 제어 및 선택적 공급량 상한을 제공하는 보상 토큰입니다. 새로 배포할 때 이름은Stellar Trade, 기호는STRD를 사용합니다.referral_registry: 추천을 등록하고, 추천 체인의 깊이를 제한하며, 추천 수수료를 분배합니다.leaderboard: 참여자의 포인트와 승패 기록을 추적하고, 점수 감소를 적용하며, 승인된 보상 토큰 발행을 지원합니다.cross_contract_invariants: 시장, 추천, 리더보드 및 토큰 컨트랙트 전반의 회계 처리와 동작을 테스트합니다.
Rust 워크스페이스 설정
프로젝트는 rust-toolchain.toml을 통해 Rust 1.91.0과 wasm32v1-none 타깃을 고정합니다. 저장소 루트에서 검사를 실행하기 전에 저장소에 지정된 툴체인과 타깃을 설치하세요.
환경이 준비되면 전체 워크스페이스 테스트 모음을 실행합니다.
cargo test --workspace --all-features포맷 검사를 통해 소스가 프로젝트의 포맷 규칙을 따르는지 확인합니다.
cargo fmt --all -- --check경고를 오류로 처리하도록 Clippy를 실행하여 코드 품질 및 정확성 문제를 찾습니다.
cargo clippy --workspace --all-features -- -D warnings릴리스 프로필을 사용하여 WebAssembly용 예측 시장 컨트랙트를 빌드합니다.
cargo build --release --target wasm32v1-none -p prediction_market이 명령은 저장소의 GitHub Actions 워크플로에서 사용하는 검사에 해당합니다. 또한 이 워크플로는 기본 브랜치와 풀 리퀘스트의 변경 사항에 대해 WASM 산출물을 빌드하고 컨트랙트 간 불변식 테스트를 실행합니다.
시장 생명주기 따라가기
1. 시장 생성
승인된 생성자가 시장 질문, 카테고리 및 마감 시간을 게시합니다. 시장 생성에는 권한이 필요하므로 호출자는 컨트랙트에 설정된 승인 규칙을 충족해야 합니다.
2. 포지션 설정
참여자는 place_bet을 호출하여 YES 또는 NO 중 한쪽에 XLM을 스테이킹합니다. 컨트랙트는 설정된 수수료를 적용하고, 그 결과 포지션을 참여자가 선택한 쪽에 반영합니다.
포지션 축소 메커니즘은 개인 간 판매, 주문서 또는 숏 포지션이 아닙니다. 참여자에게 기존에 기록된 스테이크에 적용되는 작업입니다.
3. 마감 전 포지션 축소
시장이 마감되기 전에 참여자는 reduce_position을 호출하여 기존 스테이크를 줄일 수 있습니다. 컨트랙트는 참여자의 기록된 선택지를 사용하고, 축소된 스테이크와 유지되는 수수료 규칙을 바탕으로 반환 금액을 계산합니다.
컨트랙트는 참여자의 기존 포지션에서 선택지를 결정하므로, 호출자는 이 작업을 선택지 변경이나 다른 참여자와의 거래로 간주해서는 안 됩니다.
4. 시장 결과 확정
승인된 결과 확정자가 시장 마감 후 결과를 제출합니다. 그러면 시장 컨트랙트가 승리 포지션에 대한 비례 지급액을 계산합니다.
결과 확정에는 권한이 필요합니다. 이 워크스페이스는 자동 오라클을 제공하지 않습니다. 승인된 결과 확정자가 외부 가격 또는 네트워크 정보를 사용하여 결과를 제출하지 않는 한, 해당 데이터로 시장을 정산할 수 없습니다.
5. 당첨금 청구 또는 취소 환불 수령
참여자는 시장 결과가 확정된 후 컨트랙트를 통해 비례 지급액을 청구합니다. 취소된 시장은 일반적인 승리 포지션 지급 흐름이 아닌 별도의 환불 경로를 따릅니다.
결과 확정자 선정, 결과 확정 기준, 증거 및 분쟁 처리는 중요한 신뢰 가정입니다. 배포된 시장에 의존하기 전에 이러한 절차를 검토하세요.
회계 처리 및 안전성 속성 검토
컨트랙트 동작을 변경하기 전에 불변식 매트릭스를 읽으세요. 이 문서는 중요한 회계 규칙과 이를 보호하는 테스트를 연결합니다.
매트릭스에는 다음과 같은 영역이 포함됩니다.
- 수수료 보존 및 시장 수준의 수수료 격리
- 비례 지급액의 범위
- 취소 동작
- 추천 회계 처리
- 보상 공급량 추적
- 스토리지 TTL 처리
- 긴급 일시 중지 경로
수수료, 보상, 지급 공식 또는 스토리지 수명을 수정하는 경우 관련 회귀 테스트와 불변식 테스트도 동시에 업데이트하세요. 변경 사항이 둘 이상의 컨트랙트에 영향을 미칠 때는 cross_contract_invariants 크레이트가 특히 유용합니다.
과거 이슈 보고서 올바르게 활용하기
issues/ 디렉터리에는 과거의 보안 및 정확성 보고서가 포함되어 있습니다. 해당 보고서의 맥락을 이해하려면 issues/README.md를 읽으세요.
이 보고서들은 과거의 설계 위험을 문서화한 것입니다. 이를 계약이 감사되었다는 증거로 보거나, 나열된 모든 문제가 여전히 현재 유효하다는 확인으로 간주해서는 안 됩니다. 현재 소스 코드, 테스트 및 불변식 매트릭스와 함께 검토 자료로 활용하세요.
배포 준비
테스트넷 배포는 기존 계약 ID와 토큰 메타데이터를 유지합니다. 새로 배포하면 새로운 주소가 생성되고 STRD가 초기화되며, 기존 보유자나 잔액은 마이그레이션되지 않습니다.
배포하기 전에 다음 항목을 모두 확인하세요:
- 대상 네트워크
- 계약 ID
- 관리자 신원
- 수수료 설정
- 리졸버 구성
비밀 키, 지갑 복구 문구, .deploy.env, 배포 출력 결과 또는 로컬 신원 파일을 리포지토리에 절대 커밋하지 마세요.
로컬 프런트엔드 개발 및 애플리케이션 수준의 배포 지침은 애플리케이션 README를 참조하세요.
고급 개발 팁
계약 간 동작 테스트
한 크레이트에 국한된 것처럼 보이는 변경도 추천, 보상, 리더보드 기록 또는 토큰 공급량에 영향을 줄 수 있습니다. 단일 크레이트의 단위 테스트에만 의존하지 말고 전체 워크스페이스 테스트와 계약 간 불변식 테스트를 실행하세요.
권한 경계를 명확하게 유지
마켓 생성, 결과 확정, 토큰 관리, 발행 및 기타 민감한 작업에는 권한 제어가 사용됩니다. 계약을 검토하거나 확장할 때 각 작업을 수행할 수 있는 신원이 누구인지, 일시 중지 제어가 긴급 상황의 동작에 어떤 영향을 미치는지 확인하세요.
스토리지 수명 변경 검토
스토리지 TTL 처리는 프로젝트 안전 모델의 일부입니다. 스토리지 접근 패턴이나 수명을 변경할 때는 불변식 매트릭스에 비추어 확인하고 회귀 테스트로 검증해야 합니다.
릴리스 산출물 검증
변경 사항을 게시하거나 배포하기 전에 포맷팅, Clippy, 테스트 및 릴리스 WASM 빌드를 실행하세요. 로컬 빌드가 성공했다는 사실은 개발 전제 조건일 뿐, 구성과 배포 신원을 검토하는 것을 대신할 수 없습니다.
결론
Stellar Trade Contracts는 예측 마켓을 생성하고, YES 및 NO 포지션을 기록하며, 스테이크를 줄이고, 결과를 확정하고, 비례 청구액을 분배하고, 취소된 마켓에 환불을 제공하는 Soroban 로직을 제공합니다. 지원 크레이트는 보상 토큰, 추천, 리더보드 및 통합 기능을 추가합니다.
리포지토리를 안전하게 사용하려면 고정된 Rust 환경에서 시작하고, 모든 워크스페이스 검사를 실행하며, 마켓 생명주기를 숙지하고, 회계 또는 스토리지 동작을 변경하기 전에 불변식 매트릭스를 검토하세요. 배포 중에는 모든 권한과 네트워크 설정을 확인하고 모든 비밀 정보를 버전 관리 시스템 외부에 보관하세요.