손님이 뜸한 상권과 시간대에 보너스를 더 주는 대구 지역화폐 결제 프로토타입입니다. Kaia Kairos 테스트넷에서 동작합니다.
라이브 데모 · 3분 둘러보기 · 데모 대본 · 동작 시나리오 · 배포 기록
시민이 보는 서비스 이름은 "달구벌페이"이고 프로젝트와 저장소 이름은 "iM-LocalBoost"입니다. 컨트랙트 DalgubeolPay와 저장소 im-localboost는 같은 제품을 가리킵니다.
지역화폐는 대부분 "언제 어디서 쓰든 10%"와 같은 일률 할인으로 운영됩니다. 할인 재원은 세금인데, 이 방식으로는 그 돈이 어디로 갈지를 정책이 정할 수 없습니다.
- 사중 손실: 혜택이 없어도 일어났을 소비에 예산이 나갑니다. 이 저장소의 시뮬레이션에서는 일률 10% 예산의 86.9%가 그런 소비에 지급됐습니다.
- 쏠림: 붐비는 상권과 한산한 골목이 같은 율을 받습니다. 살리려는 상권에 예산을 더 보낼 방법이 없습니다.
- 부정 수급(깡): 가맹점과 지인이 돈을 돌려 가며 결제해 보너스만 챙기는 담합을 사후 단속으로만 막습니다. 적발했을 때는 예산이 이미 나간 뒤입니다.
- 보너스율이 상권과 시간대에 따라 달라집니다. 엔진이 상권·시간대별 매출을 예측합니다. 한산한 시간대일수록, 취약한 상권일수록 높은 율(0~15%)을 매시 정각에 온체인으로 게시합니다.
- 위험 판정이 결제 시점에 끝납니다. 결제 직전에 규칙 4종과 LightGBM 모델이 담합 위험 등급을 매겨 EIP-712로 서명합니다. 컨트랙트는 그 등급에 따라 보너스를 즉시 지급하거나 보류하거나 차단합니다. 보류된 보너스는 은행이 환수합니다.
- 결제는 막지 않습니다. 위험 등급과 상한이 줄이는 것은 보너스뿐입니다. 판정이 틀려도 시민이 낸 돈은 가게에 그대로 들어갑니다.
역할은 넷입니다. 시민은 본인 지갑으로 결제하고 보너스 크레딧을 받습니다. 가맹점은 QR로 결제를 받고 정산을 요청합니다. 대구시는 상권 예산과 율, 상한을 관리합니다. 은행(iM뱅크) 은 iMKRW 발행, 본인 확인, 보류 보너스 환수, 원화 정산을 맡습니다.
| 참여자 | 지금 | 달구벌페이에서 |
|---|---|---|
| 대구시 | 할인율 하나를 정하고 예산이 소진되기를 기다립니다. 예산이 어느 상권의 매출을 얼마나 올렸는지 알 수 없습니다. | 상권별로 예산을 예치하고 율의 상한을 정합니다. 집행 내역은 전부 온체인 이벤트이므로 상권·시간대별 집행액과 매출 변화를 원 단위까지 추적할 수 있습니다. |
| 은행(iM뱅크) | 지역화폐 운영 대행은 수수료 사업이며 원화 스테이블코인에는 아직 사용처가 없습니다. | iMKRW가 매일 쓰이는 결제 수단이 됩니다. 발행 담보 예치금, 가맹점 정산 계좌, 소상공인 매출 데이터가 은행에 남습니다. 1인 1계정을 보장하는 본인 확인(personId)은 은행만 제공할 수 있습니다. 이 구조에서 은행을 다른 사업자로 대체하기는 어렵습니다. |
| 가맹점 | 할인 혜택이 큰 상권과 피크 시간대에 몰립니다. | 손님이 없는 시간대에 보너스율이 올라가서 손님이 옵니다. 할인 비용은 가맹점이 부담하지 않으며 정산은 토큰 전송 한 번으로 요청합니다. |
| 시민 | 충전할 때 받는 할인은 어디서 쓰든 같습니다. | 지도에서 지금 율이 높은 상권을 보고 고릅니다. 보너스는 결제하는 즉시 크레딧으로 들어오고 어떤 경우에도 결제가 거절되지 않습니다. |
예산 편성의 근거가 쌓입니다. 엔진은 전체 슬롯의 10%에 일부러 0·5·10·15% 중 하나를 무작위로 게시합니다. 게시한 율과 탐색 여부는 엔진 DB에 남으므로, 운영하는 동안 상권·시간대별로 "율을 1%p 올리면 매출이 얼마나 늘어나는가"에 대한 실험 데이터가 계속 쌓입니다. 율이 변하지 않는 일률 할인에서는 이 값을 추정할 방법이 없습니다. 이 데이터가 있으면 다음 해 예산을 어느 상권에 얼마나 배정할지를 근거를 갖고 정하게 됩니다.
탐지 모델을 공공 결제에 넣을 수 있는 조건이 갖춰집니다. 부정 수급 탐지는 오탐을 피할 수 없고 공공 서비스에서 결제가 거절되면 곧바로 민원이 됩니다. 달구벌페이는 판정이 틀렸을 때 시민이 입는 피해를 "보너스가 60초 늦게 들어온다" 수준으로 제한합니다. 그래서 정밀도가 낮은 규칙도 운영에 쓸 수 있습니다. 모델은 운영하면서 실데이터로 개선하면 됩니다.
공격으로 얻을 수 있는 돈에 상한이 있습니다. 건당 3,000원, 1인당 하루 5,000원, 같은 가게는 하루 한 번, 상권당 시간당 300,000원이라는 상한을 컨트랙트가 강제합니다. 개인 상한은 은행이 확인한 personId 단위로 적용되므로 지갑을 여러 개 만들어도 늘어나지 않습니다. 엔진의 서명 키가 유출되어도 손실은 이 상한을 넘지 못합니다.
감사 비용이 줄어듭니다. 보너스 금액은 컨트랙트만 계산하고 "컨트랙트 잔액 = 상권 예산 + 시민 크레딧 + 보류 보너스"라는 회계 등식이 모든 트랜잭션 뒤에 성립합니다. 시 의회나 감사 기관은 운영사가 제출한 보고서에 의존하지 않고 체인에서 집행 내역을 직접 확인합니다.
수요가 시간대로 분산됩니다. 붐비는 시간에는 율이 내려가고 한산한 시간에는 올라가므로, 시간 선택이 자유로운 소비가 한산한 시간대로 옮겨 갑니다. 가맹점은 같은 좌석과 인력으로 매출을 더 올립니다.
다른 정책 자금에 그대로 쓸 수 있습니다. "구역 × 시간 × 율 × 상한"이라는 구조에는 대구에만 해당하는 요소가 없습니다. 다른 지자체의 지역화폐, 전통시장 상품권, 관광 비수기 지원, 재난 지원금처럼 사용처와 시기를 정해서 지급해야 하는 자금이라면 같은 컨트랙트를 설정만 바꿔서 적용하면 됩니다.
효과의 크기는 검증 결과에 나온 수치를 그대로 적었습니다. 합성 데이터로 돌린 시뮬레이션에서 동적 율이 일률 할인보다 나은 폭은 작았습니다. 이 프로토타입은 두 가지를 확인했습니다. 이 구조는 테스트넷에서 예산 예치부터 원화 정산까지 끊김 없이 동작합니다. 그리고 실제 운영에 들어가면 효과를 측정하면서 율을 고쳐 나갈 수 있습니다.
지갑을 설치하지 않고도 주요 기능을 볼 수 있는 경로입니다. 관리자 도구는 상단에서 데모 계정을 고르면 바로 동작합니다.
- 첫 화면에서 지금 상권별 보너스율을 확인합니다. "가맹점 지도 보기"를 누르면 가맹점 200곳과 상권별 율이 지도에 나옵니다.
- /admin/city에서 데모 계정 "대구시"를 고릅니다. 상권별 예산과 율, 엔진의 수요 예측값, 시뮬레이션 차트가 있습니다. 하단의 "담합 링 실행"을 누르면 담합 결제가 통과하면서 보너스만 0원이 되는 과정이 로그에 나옵니다. "서명 재사용 공격"을 누르면 컨트랙트가 같은 서명을 거부합니다.
- /admin 대시보드에는 전체 결제, 위험 판정 로그, 트랜잭션 링크가 있습니다.
- /admin/bank에서 데모 계정 "은행"을 고릅니다. 가맹점 정산, 보류 보너스 환수, 운영 계정의 가스 잔액을 볼 수 있습니다.
직접 결제해 보려면 Kaia Wallet 또는 MetaMask를 설치하고 첫 화면에서 "지갑 연결" → "은행 등록하고 시작 자금 받기"를 누르세요. 은행이 iMKRW 100,000원과 수수료용 0.2 KAIA를 보내 주므로 faucet 없이 바로 결제할 수 있습니다. 은행 계정의 KAIA가 부족할 때만 화면이 Kaia faucet을 안내합니다.
역할 네 개가 모두 등장하는 전체 흐름(약 8분, 16단계)은 docs/demo.md에 있습니다.
| 시민: 결제 | 시민: 가맹점 지도 |
|---|---|
![]() |
![]() |
| 대구시: 예산·율·상한·시뮬레이션 | 은행: 정산·환수 |
|---|---|
![]() |
![]() |
모바일 화면과 나머지 관리자 화면(consumer-home.png, consumer-history.png, admin-dashboard.png, admin-merchant.png)은 docs/demo/에 있습니다. 모두 2026-09-19에 프로덕션(Kairos) 데이터로 찍었습니다.
화면은 두 영역으로 나뉩니다. 소비자 앱(/, /pay, /map, /history)은 본인 지갑으로만 동작하며 웹이 개인키를 다루지 않습니다. 관리자 도구(/admin, /admin/merchant, /admin/city, /admin/bank)는 어두운 상단 바로 구분되고 발표용 데모 계정은 여기서만 고를 수 있습니다.
┌──────────────────────────┐
│ web (Next.js, Vercel) │ 소비자 앱: 본인 지갑(Kaia Wallet)으로 결제·QR·지도·내역
│ │ 관리자 도구(/admin): 대시보드·가맹점 데스크·대구시·은행/정산
└──────┬───────────┬───────┘
/attest, /rates│ │ payWithBoost, deposit, publish
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────────────┐
│ engine (FastAPI, Railway) │ │ Kaia Kairos (chainId 1001) │
│ · 이벤트 폴러 → SQLite │◄──│ MockIMKRW · MerchantRegistry · │
│ · 규칙 4종 + LightGBM 위험 │ │ DalgubeolPay (율·예산·상한·보류·환수) │
│ · 수요 예측 → 율 게시 │──►│ 보너스 금액은 컨트랙트만 계산 │
│ · EIP-712 Attestation 서명│ └──────────────────────────────────────┘
└──────────────────────────┘
▲
sim (Python) │ 같은 규칙·율 계산으로 5개 시나리오 비교 → web/public/sim
| 패키지 | 역할 | 스택 |
|---|---|---|
contracts/ |
토큰, 가맹점 등록부, 결제·보너스 컨트랙트 | Hardhat, Solidity 0.8.24, OpenZeppelin 5 |
engine/ |
위험 판정과 서명, 수요 예측과 율 게시, 이벤트 적재, 은행 온보딩 | Python 3.11, FastAPI, web3.py, LightGBM, networkx, SQLite |
sim/ |
정책 시나리오 5종 비교 | Python 3.11 |
web/ |
소비자 앱과 관리자 도구 | Next.js 14 App Router, Tailwind, viem |
shared/ |
배포 주소와 ABI (세 패키지가 함께 읽음) | deployments.json, abi/ |
- 웹이 엔진
POST /attest에 결제자, 가맹점, 금액을 보냅니다. - 엔진이 규칙과 모델로 위험 등급(tier 0~2)을 정하고
Attestation(payer, merchant, amount, tier, nonce, deadline)에 EIP-712로 서명합니다. 서명에는 등급만 있고 보너스 금액이나 율은 없습니다. 유효 시간은 120초입니다. - 시민의 지갑이
payWithBoost를 보냅니다. 컨트랙트는 서명자, 만료, nonce를 검증하고 결제 금액을 가맹점에 전송합니다. - 컨트랙트가 온체인에 게시된 율과 상한으로 보너스를 계산합니다. tier 0이면 크레딧으로 즉시 적립합니다. tier 1이면 60초 동안 보류하고 tier 2이면 지급하지 않습니다.
- 엔진의 폴러가
Paid와Transfer이벤트를 SQLite에 적재합니다. 이 기록이 다음 위험 판정과 수요 예측의 입력이 됩니다.
엔진이 멈추면 서명을 받지 못하므로 새 결제가 나가지 않습니다. 이미 적립된 크레딧과 예산은 컨트랙트에 있어서 영향을 받지 않습니다.
컨트랙트, 엔진, 웹이 모두 지키는 규칙입니다.
- 결제는 위험 등급이나 상한 때문에 revert하지 않습니다. 줄어드는 것은 보너스뿐입니다. revert 사유는 서명 불일치, 만료, nonce 재사용, 비활성 가맹점, 미등록 결제자, 잔액 또는 allowance 부족뿐입니다.
- 보너스 금액은 컨트랙트만 계산합니다.
- 모든 개인 상한은 주소가 아니라
personId단위입니다. - 크레딧으로 낸 금액에는 보너스가 붙지 않습니다. 보너스로 다시 보너스를 받는 순환을 막기 위한 규칙입니다.
- 회계 등식
iMKRW.balanceOf(DalgubeolPay) == Σ zoneBudget + Σ credit + Σ pending(미처리)가 모든 상태 변경 뒤에 성립합니다.
payWithBoost는 아래 순서로 계산하며 어느 단계에서 0이 되어도 revert하지 않습니다.
pairDay[personId][merchant] == 오늘이면 보너스는 0입니다(같은 가게는 하루에 한 번).- 슬롯 상한:
base = min(amount - useCredit, slotBaseline × slotCapBps / 10000 - slotVolume[merchant][hour]) boost = base × rate[zone][hour] / 10000boost = min(boost, 건당 상한, 1인 일일 상한 잔여, 상권 시간당 상한 잔여, 상권 예산)- tier 2이면 0으로 만듭니다. tier 0이면 크레딧으로 즉시 적립합니다. tier 1이면 보류합니다.
pendingDelay가 지나면 누구나 지급을 실행할 수 있습니다. 지급되기 전까지는 은행이 환수할 수 있습니다.
금액은 전부 원 단위 정수(토큰 소수점 0)이고 하루 경계는 KST((timestamp + 9h) / 1 day)입니다.
엔진 /attest는 규칙 계층과 모델 계층을 각각 평가하고 둘 중 높은 등급을 최종 tier로 씁니다.
| 규칙 | 조건 | tier |
|---|---|---|
환류 backflow |
최근 24시간 Transfer 그래프에서 가맹점 → 결제자 경로가 3홉 이내 | 1 |
쌍 반복 pair_repeat |
같은 결제자·가맹점 쌍의 최근 7일 보너스 결제가 4회 이상 | 1 |
신규 지갑 군집 new_wallet_cluster |
등록 48시간 이내 지갑 5개 이상이 같은 가맹점에 1시간 안에 결제 | 2 |
매출 이탈 sales_spike |
가맹점의 현재 슬롯 매출이 기준의 3배 초과 | 1 |
모델 계층은 LightGBM 이진 분류기입니다. 피처는 11개이고 학습과 서빙이 같은 engine/features.py를 씁니다. 점수가 0.5 미만이면 tier 0, 0.5 이상 0.8 미만이면 tier 1, 0.8 이상이면 tier 2입니다.
엔진 /rates/publish는 상권 × 1시간 단위로 율을 계산합니다.
predictedSales: LightGBM 회귀 모델의 예측 매출baseline: 같은 슬롯의 최근 8주 매출 중 상위 25%의 평균slack = max(0, 1 - predictedSales / baseline): 평소 잘되는 날에 비해 얼마나 한산할지를 나타내는 값bps = clip(round_to_50(k × slack × vulnerability[zone] × 10000), 0, 1500)
k는 예산 소진 속도를 맞추는 계수이며 하루에 한 번 clamp(planned_spend / actual_spend, 0.5, 1.5)로 보정합니다. 슬롯의 10%는 {0, 500, 1000, 1500} 중 하나를 탐색값으로 씁니다(override가 있는 상권은 제외). 상한은 온체인 caps().maxRateBps를 읽어서 적용하므로 대구시가 최대 율을 낮춰도 게시가 RateTooHigh로 실패하지 않습니다. 한 번 게시한 뒤에는 엔진 폴러가 정시마다 마지막 설정으로 현재 시간과 다음 시간의 율을 다시 게시합니다.
make test # contracts: Hardhat 테스트 49개 + engine: pytest 49개 (통합 제외)
make test-integration # 노드·엔진이 떠 있는 상태에서 엔진 서명 → 온체인 결제 → 재사용 revert 확인
cd web && npx tsx --env-file=.env.local scripts/verify-wallet.ts # 일회용 키로 지갑 온보딩 → approve → 결제 (브라우저 없이)
cd web && npx tsx --env-file=.env.production.local scripts/verify-wallet.ts # 같은 검증을 Kairos + Railway 상대로
필수 컨트랙트 케이스는 contracts/test/dalgubeolpay.pay.test.ts, dalgubeolpay.admin.test.ts, registry.test.ts에 caseNN_ 이름으로 있습니다. 정상 결제, 서명 재제출·만료·위조·금액 불일치 revert, 같은 날 같은 가게 두 번째 결제(보너스 0), 1인 일일 상한, 슬롯 상한, 최대 율 초과 게시 revert, tier 1 보류와 지급, 환수, tier 2 차단, 크레딧 결제, 예산 0 상권, 상한 변경 지연, 한 사람 두 지갑 revert를 다룹니다. 불변식 5(회계 등식)는 모든 시나리오의 afterEach에서 검사합니다.
make sim # sim/run.py --seed 7 --days 28 --consumers 5000 → sim/out/, web/public/sim/
소비자 5,000명, 상권 5개, 하루 14슬롯, 28일을 돌립니다. 소비자는 다항 로짓 U = pref[z] - travel_cost[z] + sensitivity * benefit_rate[z,t]로 상권을 고르며 "소비 안 함" 선택지가 포함됩니다. 보너스 계산은 컨트랙트와 같은 순서를 옮긴 sim/caps.py를 씁니다.
| 시나리오 | 내용 |
|---|---|
none |
혜택 없음 (기준선) |
A |
일률 10% |
B |
동적 율. A와 총예산이 같아지도록 k를 보정 |
C_on / C_off |
B에 담합 링을 추가하고 방어를 켠 경우와 끈 경우 |
| 지표 | 정의 (results.json.definitions 그대로) |
|---|---|
vulnerable_slot_sales_uplift |
상권별로 none 매출 하위 25% (일, 슬롯) 셀에서 (scenario - none) / none |
net_sales_per_won |
(total_sales - none.total_sales) / total_boost |
deadweight_ratio |
none에서도 같은 상권·(일, 슬롯)에 구매했을 소비자에게 지급된 보너스 / total_boost |
farming_leakage |
링 결제에 지급되고 회수되지 않은 보너스 / total_boost (C 시나리오) |
detection_precision / detection_recall |
C_on에서 규칙 tier ≥ 1 판정의 링 라벨 대비 정밀도 / 재현율 (전체 결제) |
결과입니다(web/public/sim/results.json, seed 7, 생성 2026-09-18T08:24:36+00:00). 수치는 고치지 않았습니다.
| 시나리오 | 취약 슬롯 매출 증가율 | 예산 1원당 순증 매출 | 사중 손실 비율 | 파밍 누수율 | 탐지 정밀도 | 탐지 재현율 | 총매출 | 총 보너스 | k |
|---|---|---|---|---|---|---|---|---|---|
| none | 0.000 | - | - | - | - | - | 3,636,417,000 | 0 | - |
| A | 0.173 | 1.547 | 0.869 | - | - | - | 4,178,929,000 | 350,721,035 | - |
| B | 0.185 | 1.578 | 0.852 | - | - | - | 4,170,723,000 | 338,564,644 | 1.5 |
| C_on | 0.185 | 1.618 | 0.851 | 0.001 | 0.040 | 0.635 | 4,179,446,000 | 335,594,003 | 1.5 |
| C_off | 0.185 | 1.602 | 0.851 | 0.001 | - | - | 4,179,446,000 | 338,977,980 | 1.5 |
유리하지 않은 값도 그대로 둡니다.
- 동적 율의 이득은 작습니다. 취약 슬롯 매출 증가율은 일률 0.173에서 동적 0.185로, 사중 손실은 0.869에서 0.852로 움직였습니다. 같은 예산에서 방향은 맞지만 폭이 작고 결과가 소비자 모형의 율 민감도 가정에 좌우됩니다. 다음 단계는 실데이터로 민감도를 추정하는 일이며 운영 중에 쌓이는 탐색 슬롯 데이터가 그 재료입니다.
- 표의 파밍 누수율은 반올림 때문에 둘 다 0.001로 보입니다.
results.json의 원래 값은 방어를 껐을 때 0.00134, 켰을 때 0.00071이며 방어가 누수를 절반가량 줄였습니다. 다만 링 결제가 전체 348,276건 중 592건뿐이어서 누수 자체가 작습니다. - 규칙 계층의 탐지 정밀도는 0.040입니다. 규칙에 걸린 결제의 대부분이 정상 결제라는 뜻입니다. 방어를 켜면 총 보너스가 약 338만 원 줄어드는데(338,977,980 → 335,594,003), 그중 링에서 막은 금액은 약 22만 원이고 나머지는 규칙에 걸린 정상 결제의 보너스입니다. 그래서 규칙 등급은 결제를 막지 않고 보너스를 60초 보류할 뿐이며(tier 1), 즉시 차단(tier 2)은 신규 지갑 군집 규칙과 모델 점수 0.8 이상에만 씁니다. 이 수치는 규칙 계층만의 값이며 모델은 포함하지 않았습니다.
- 위험 모델의 AUC 1.000은 합성 데이터에서 나온 값입니다.
make train이 출력한 지표(engine/models/*_metrics.json)는 위험 모델 validation [email protected] 1.000, [email protected] 0.911, AUC 1.000이고 수요 모델 validation MAE 48,458원, 8~21시 MAPE 0.589입니다. 학습과 검증이 같은 생성기에서 나왔으므로 실제 담합 패턴이나 실제 매출에 대한 성능을 뜻하지 않습니다.
Node 20 이상과 Python 3.11이 필요하고 Docker는 선택입니다. 터미널을 세 개 씁니다.
make setup # contracts/web npm install, 루트 .venv, .env·web/.env.local 복사
make node # [터미널 1] Hardhat 로컬 노드 (chainId 31337)
make deploy-local # 배포 + 시드, shared/deployments.json·abi 갱신
make train # 합성 데이터 생성 → 위험 모델·수요 모델 학습 (지표는 나온 그대로 출력)
make engine # [터미널 2] uvicorn engine.main:app (기본 8000)
make web # [터미널 3] next dev (기본 3000)
로컬은 Hardhat 기본 계정을 씁니다(#0 deployer, #1 city, #2 bank, #3 oracle, #4 attester, #5~#9 소비자 15, #10#12 가맹점 1~3). 비밀값은 .env에만 둡니다.
| 대상 | 링크 |
|---|---|
| 웹 (소비자 앱) | https://im-localboost-web.vercel.app (/ 결제, /map 가맹점 지도, /history 내 결제 내역, /pay QR 결제) |
| 웹 (관리자 도구) | https://im-localboost-web.vercel.app/admin (/admin 대시보드, /admin/merchant 가맹점 데스크, /admin/city 대구시, /admin/bank 은행·정산) |
| 엔진 | https://engine-production-1edd.up.railway.app/health |
| MockIMKRW | https://kairos.kaiascan.io/address/0x0618ba0D361C5107bE2E39901dd394BFC4092A4b |
| MerchantRegistry | https://kairos.kaiascan.io/address/0xEB0aFb837B488e9713a825299F4DF6BB6D32Cc41 |
| DalgubeolPay | https://kairos.kaiascan.io/address/0x7ef0DA4bd695E91eAe9d53fb1Df18F302585258d |
배포 절차, 역할별 주소, 검증 기록은 docs/deploy.md에 있습니다.
영수증 OCR과 LLM 호출, 실제 iMKRW 연동, 실데이터, KYC, 모바일 앱, 상용 지도 API(지도는 OpenStreetMap 타일), Kaia 수수료 대납, 프라이버시 계층, 운영용 키 관리, 다중서명 거버넌스는 만들지 않았습니다. 외부 유료 API를 쓰지 않습니다. 가맹점 등록과 비활성화, personId 연결 변경은 컨트랙트 함수(BANK_ROLE)만 있고 웹 화면이 없어서 시드 스크립트로 수행합니다. 크레딧의 현금화와 만료는 설계에 없습니다.
가맹점 정보(이름, 주소, 좌표)는 실제 대구 상권의 가게를 참고한 데모 데이터이며 제휴 관계가 아닙니다. 온체인에는 상권과 업종만 있고 나머지는 contracts/scripts/demo-config.ts → shared/deployments.json의 표시용 데이터입니다.
발표와 검증에 쓰려고 넣은 장치들이며 프로덕트 설계에는 포함되지 않습니다.
- 브라우저 개인키 (데모 계정): 관리자 도구의 데모 계정 키가
NEXT_PUBLIC_*로 번들에 들어갑니다. 로컬에서는 Hardhat 공개 계정이고 Kairos에서는 테스트넷 전용 일회용 키입니다. 실제 자산이 있는 키를 절대 넣지 마세요. 소비자 앱은 지갑 연결로만 동작하며 그 경로에서는 웹이 개인키를 다루지 않습니다. - 은행 온보딩 (
POST /onboard): 엔진이BANK_KEY로setPerson,mint, 가스 전송을 대신합니다. 실서비스에서는 은행의 본인 확인 백엔드가 이 역할을 맡고 iMKRW 발행은 원화 입금에 대응합니다. 프로토타입에서는 하루 1회 100,000원으로 제한합니다. 은행 계정의 KAIA가ONBOARD_GAS_KAIA + 0.02미만이면 가스 전송만 건너뛰고(gasSkipped) 웹이 faucet을 안내합니다. Kairos faucet은 캡차로 보호되어 자동 수령이 불가능하므로, 운영자가/admin/bank의 "운영 계정 가스" 카드(엔진GET /onboard/funds)에서 잔액을 보고 직접 채웁니다. - 고정 율 override:
/admin/city의 "데모 전용: 북성로 10% 고정" 토글은/rates/publish에overrides: {"4": 1000}을 보냅니다. 다른 상권에는 엔진이 계산한 율이 그대로 게시됩니다. - 담합 링과 서명 재사용 버튼:
/admin/city하단의 "데모 보조"입니다. 링은 가맹점 2가 소비자 2~5에게 돈을 돌려준 뒤 그 소비자들이 결제하는 과정을 순서대로 실행하고 재사용은 직전 결제의 서명을 다시 제출합니다. - 정산: 컨트랙트를 바꾸지 않고 ERC-20 transfer 두 번으로 표현합니다. 가맹점 → 은행 전송이 정산 요청이고 은행 →
0x…dEaD전송이 원화 지급 완료(유통량에서 제외)입니다. 원장은 엔진GET /transfers입니다.
- 위험 모델과 수요 모델은 합성 데이터로 학습했으므로 지표가 실데이터를 대표하지 않습니다.
- 시드 직후에는 모든 지갑이 "신규"입니다. 그래서 담합 링 데모에서는 보류(tier 1)가 아니라 즉시 차단(tier 2)이 나옵니다. 프로덕션 실행에서 소비자 2
5의 모델 점수는 0.9470.989였습니다. 보류 → 환수 경로를 따로 보는 방법은 docs/demo.md에 있습니다. - 위험 모델은 율이 바뀐 직후 몇 초 안의 결제에 민감합니다(
secs_since_rate_change). 웹은 매시 정각부터 45초까지는 카운트다운을 보여 준 뒤에/attest를 호출합니다. - 서명 유효 시간은 120초입니다. 지갑 승인이 늦어지면
AttestationExpired가 발생하며 다시 결제하면 새 서명을 받습니다. - Kairos 공개 RPC에서는 트랜잭션 확인에 수 초가 걸리고 엔진 폴러가 새 배포를 따라잡는 데 시간이 걸릴 수 있습니다.
/health의lastBlock이 증가하는지 확인하세요.
| 문서 | 내용 |
|---|---|
| docs/demo.md | 역할 네 개가 등장하는 8분 데모 대본, 준비 절차, 브라우저 없이 검증하는 스크립트 |
| docs/scenarios.md | 화면별 동작 시나리오 전체. 보너스가 0원이 되는 사유, revert 사유, 시간 경계 |
| docs/deploy.md | Kairos·Railway·Vercel 배포 절차, 역할별 주소, 검증 기록 |




