Skip to content

Commit 6bed28b

Browse files
authored
Merge pull request #141 from decipherhub/test/sdk-golden-path-acceptance
test(sdk): enforce the external-user golden path
2 parents d96bc93 + 139161f commit 6bed28b

14 files changed

Lines changed: 489 additions & 39 deletions

File tree

‎FEATURES.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,33 @@
99

1010
동시에 하나의 feature만 `active` 상태로 둔다.
1111

12+
## SDK-007 — External User Golden Path Acceptance
13+
14+
### Behavior
15+
16+
- packed CLI/Toolkit/RFQ package만 설치한 clean project에서 `sandbox`와
17+
`dex-integration`을 source checkout 없이 생성·설치·검증한다.
18+
- 생성 프로젝트는 `validate`, `simulate`, `doctor`, `deploy`, `verify`의 공통
19+
명령 계약을 제공하고 sandbox만 Docker를 필수 dependency로 진단한다.
20+
- stale/wrong-profile deployment artifact는 actionable remediation과 함께
21+
fail-closed하며 수정 뒤 같은 `verify` 명령으로 복구를 확인한다.
22+
- venue 정책 값 변경은 compiled config commitment와 allow/reject 설명 양쪽에
23+
결정적으로 반영된다. Production chain/address/runtime code-hash mismatch는 기존
24+
production onboarding verifier가 actionable remediation과 함께 거절한다.
25+
26+
### Verification
27+
28+
- Toolkit/CLI scaffold and doctor smoke
29+
- packed clean-project sandbox/DEX install, build and conformance
30+
- sandbox Docker-required and library Docker-optional diagnosis
31+
- stale artifact fail/repair/pass and policy-value propagation acceptance
32+
- production chain/address/runtime code-hash mismatch regression
33+
- full `scripts/check.sh` and `git diff --check`
34+
35+
### State
36+
37+
passing
38+
1239
## CORE-014 — C-01 Venue Compatibility Guard
1340

1441
### Behavior

‎PROGRESS.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,18 @@ source of truth로 사용한다.
1515

1616
## Completed
1717

18+
- `SDK-007 — External User Golden Path Acceptance`: issue #117의 외부 사용자 기준을
19+
packed clean-project acceptance로 고정했다. 목적별 생성 프로젝트는 공통
20+
validate/simulate/doctor/deploy/verify 계약을 제공하고, direct Compose sandbox는
21+
create→cd→up 세 명령으로 host npm/Foundry 없이 시작한다. Doctor는 project
22+
descriptor를 fail-closed 검증하고 sandbox에서 Compose v2와 daemon만 필수로,
23+
library path에서는 Docker를 선택 사항으로 진단한다. stale/wrong-profile
24+
reference artifact는 remediation 후 같은 verify로 복구되며, venue 정책 값 변경은
25+
compiled commitment와 allow/reject 설명을 함께 변경한다. Production verifier는
26+
chain/address/runtime code-hash mismatch에 remediation을 반환한다. 검증: Toolkit·CLI
27+
smoke, packed clean-project sandbox/DEX acceptance, full Foundry 954/954, 전체
28+
`scripts/check.sh`, deploy-v3 10/10, `git diff --check` 통과.
29+
1830
- `CORE-014 — C-01 Venue Compatibility Guard`: issue #132의 후속 합의대로
1931
`AMM + C-01-*`를 warning이 아닌 공통 hard rejection으로 구현했다. Toolkit profile,
2032
CLI onboarding, production onboarding/Safe export와 `ComplianceEngine`이 같은

‎README.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -205,16 +205,18 @@ node dist/cli/src/index.js create ../../my-sandbox \
205205
--template sandbox
206206

207207
cd ../../my-sandbox
208-
docker compose up --build -d
209-
docker compose ps -a # portal :8790, Deployment Studio :8791, Anvil :8545
208+
docker compose up --build -d # third command after create + cd; no host npm/Forge
209+
docker compose ps -a # portal :8790, Deployment Studio :8791, Anvil :8545
210210
# when finished:
211211
docker compose down --volumes --remove-orphans
212212

213213
cd ../../my-corner-store
214214
npm install
215+
npm run validate
216+
npm run simulate
215217
npm run policy:explain # values first; 4-layer internals are advanced detail
216218
npm run test:adapter # dex-integration: Router/Adapter conformance
217-
npm run doctor
219+
npm run doctor # Docker is optional for library integrations
218220
npm run deploy # dry-run; add -- --broadcast only for local/demo submission
219221
npm run verify # after a deployment artifact exists
220222
npm test # builds, then runs corner-store test-module
@@ -234,6 +236,13 @@ or external provider connection. To switch fixtures, stop and discard the demo
234236
chain first, then run
235237
`CORNER_STORE_PROFILE=reg-d docker compose up --build -d`.
236238

239+
After optional `npm install`, the generated sandbox also exposes `npm run doctor`,
240+
`npm run dev`, `npm run status` and `npm run clean` aliases. If `doctor` or
241+
`verify` fails, follow the emitted `remediation` field and rerun
242+
the same command. The generated project keeps these recovery steps local: install
243+
Docker Compose v2 only for `sandbox`, run `npm run clean` before changing sandbox
244+
profiles, and regenerate or correct a stale deployment artifact before `npm run verify`.
245+
237246
See [`docs/sdk-integration.md`](./docs/sdk-integration.md) for purpose templates,
238247
legacy mode mappings, the `connectCornerStore()` facade, generated files,
239248
deployment checks and the common conformance suite.
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# SDK-007 — External User Golden Path Acceptance
2+
3+
## Outcome
4+
5+
소스 저장소 checkout이 없는 외부 사용자가 packed CLI/Toolkit/RFQ package만으로
6+
목적별 프로젝트를 만들고, 같은 명령 체계로 정책을 검증·시뮬레이션·진단하며,
7+
배포 artifact 오류를 스스로 복구할 수 있게 한다.
8+
9+
## In Scope
10+
11+
- `sandbox`와 `dex-integration` clean-project package install/build/conformance
12+
- 생성 프로젝트의 `validate`, `simulate`, `doctor`, `deploy`, `verify` 명령 계약
13+
- sandbox Compose/daemon 필수 진단과 library-only Docker 선택 진단
14+
- stale/wrong-profile artifact의 actionable failure와 repair 후 verification
15+
- venue 정책 값 변경이 compiled commitment와 allow/reject 설명에 반영되는 acceptance gate
16+
- 기존 production verifier의 chain/address/runtime code-hash mismatch remediation 회귀
17+
- quickstart, recovery와 testing 문서
18+
19+
## Out of Scope
20+
21+
- production Docker/provider credential 또는 live network submission
22+
- 외부 venue settlement 구현·감사
23+
- 기존 chain/address/code-hash production onboarding 검증 로직의 재구현
24+
25+
## Stop Condition
26+
27+
packed package로 만든 clean sandbox와 DEX integration이 source checkout 없이 동일한
28+
validation contract를 통과하고, Docker/artifact 문제는 remediation을 반환하며,
29+
복구 후 verification과 정책 값 변경 propagation이 자동 acceptance test로 고정되면
30+
완료한다.

‎docs/sdk-integration.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ The external CLI workflow is:
1717
corner-store create ./my-corner-store --template dex-integration
1818
cd my-corner-store
1919
npm install
20+
npm run validate
21+
npm run simulate
2022
npm test
2123
npm run doctor
2224
npm run deploy
@@ -41,7 +43,9 @@ The generated `package.json` scripts map to the same CLI commands:
4143
| --- | --- |
4244
| `corner-store create <target>` | create a clean integration project |
4345
| `corner-store init [path]` | create a versioned Toolkit config in an existing project |
44-
| `corner-store doctor [path]` | check Node, npm, Foundry, config, contract bundle, optional artifact and optional Docker |
46+
| `corner-store doctor [path]` | check Node, npm, Foundry, config, contract bundle, optional artifact and template-aware Docker readiness |
47+
| `npm run validate` | validate the versioned project config without deployment side effects |
48+
| `npm run simulate` | compile and simulate the policy values used by the generated project |
4549
| `corner-store deploy [path]` | print the deployment plan by default; `--broadcast` submits the local/demo Foundry deployment |
4650
| `corner-store verify [path]` | preflight config and deployment artifact bindings after an artifact exists |
4751
| `corner-store test-module <path>` | run the public RFQ module conformance suite against a built CommonJS module |
@@ -72,7 +76,6 @@ repository checkout is not required.
7276
corner-store create ./corner-store-sandbox --template sandbox
7377
cd ./corner-store-sandbox
7478
docker compose up --build -d
75-
docker compose ps -a
7679
```
7780

7881
The default `buidl-like` fixture is available at `http://127.0.0.1:8790`, with
@@ -82,8 +85,7 @@ Anvil readiness and the one-shot deployment gate all dependent services, and the
8285
RFQ backend fails closed when the chain, deployment artifact or scenario do not
8386
match. Run `docker compose down --volumes --remove-orphans` to discard a previous
8487
demo chain and artifact together before switching profiles. For startup failures,
85-
inspect `docker compose ps -a` and
86-
`docker compose logs deployer rfq operator-api`.
88+
inspect `docker compose ps -a` and `docker compose logs deployer rfq operator-api`.
8789

8890
The sandbox uses public Anvil development identities, reference pricing/risk and
8991
mock qualification data. It is never a production deployment, never accepts
@@ -215,6 +217,23 @@ Docker is an export choice, not a required Corner Store runtime. Generated
215217
Compose reads `.env`; it does not embed a signer key, RPC credential or production
216218
secret.
217219

220+
## Recovery Contract
221+
222+
`doctor` emits a remediation for every failed check. Docker and Compose v2 are
223+
required only by the `sandbox` template; library-oriented templates report them
224+
as optional. The direct sandbox quickstart is three commands (`create`, `cd`,
225+
`docker compose up`) and does not require host npm or Foundry. Users who run an
226+
optional `npm install` also get `npm run doctor/dev/status/clean` aliases. A
227+
sandbox profile change must discard the old volumes before starting with the new
228+
`CORNER_STORE_PROFILE`.
229+
230+
`verify` fails closed when the local/reference deployment artifact is missing,
231+
bound to a different profile or lacks required venue addresses. Correct or
232+
regenerate that artifact, then rerun the same `npm run verify` command. The output
233+
includes `expected`, `actual` and `remediation`, so recovery does not require
234+
copying contract addresses by hand. Production chain, address, live bytecode and
235+
code-hash bindings remain the stricter `production-onboarding-verify` contract.
236+
218237
## Contract Bundle Resolution
219238

220239
Packaged CLI deployments need contract sources for `DeployStack.s.sol`. The CLI

‎docs/testing.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,8 @@ Toolkit smoke는 unified `create`의 네 purpose template과 legacy
116116
versioned project descriptor, policy facade의 immutable config commitment,
117117
actionable verification, `.env.example`,
118118
vendored `vendor/rfq-service`, optional Docker files, overwrite refusal과
119-
standalone package scripts(`doctor`, `deploy`, `verify`, `policy:explain`, `test:module`)를
119+
standalone package scripts(`validate`, `simulate`, `doctor`, `deploy`, `verify`,
120+
`policy:explain`, `test:module`)를
120121
검증한다. Production onboarding smoke는 exact schema/unknown-field rejection,
121122
PII/secret rejection, deterministic Element/Recipe/Manifest/Venue/RFQ calldata,
122123
Safe/operator draft governance/proposal metadata, authority partition, explicit
@@ -128,7 +129,14 @@ dry-run `deploy`, `verify`/preflight와 `test-module` command path도 별도로
128129
확인한다. `scripts/sdk-product-smoke.sh`는 CLI, Toolkit과 RFQ package를 모두
129130
tarball로 pack한 뒤 clean temporary project에 설치해야 하며 Toolkit public export,
130131
generated policy facade, RFQ conformance, CLI doctor/deploy와 packaged contract
131-
build를 검증한다.
132+
build를 검증한다. 또한 sandbox와 DEX project 양쪽에서 validate/simulate/doctor를
133+
실행하고, sandbox만 Compose v2와 running daemon을 required로 진단하는지 확인한다.
134+
Docker가 없는 기본 CI에서는 그 실패와 remediation 자체가 기대 결과이며 Docker
135+
runtime smoke는 daemon이 있는 release 환경에서만 실행한다. stale/wrong-profile
136+
reference artifact가 remediation과 함께 실패한 뒤 수정 시 통과하는지, venue 정책 값
137+
변경이 compiled hash와 allow/reject 설명에 함께 반영되는지도 검증한다. Production
138+
chain/address/runtime code-hash mismatch는 Toolkit/CLI의
139+
`production-onboarding-verify` regression으로 별도 고정한다.
132140
`dex-integration` clean project는 추가로 generated Solidity Adapter를 build하고
133141
real Router 기반 allow/reject/direct-call/atomic rollback 4-scenario conformance를
134142
실행한다.

‎scripts/sdk-product-smoke.sh‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,11 @@ node "$ROOT_DIR/services/cli/dist/cli/src/index.js" create "$LOCAL_TARGET_DIR" \
5353
--sdk "file:$RFQ_TARBALL" \
5454
--toolkit "file:$TOOLKIT_TARBALL" \
5555
--cli "file:$CLI_TARBALL" >/dev/null
56-
./node_modules/.bin/corner-store create "$SANDBOX_DIR" --template sandbox >/dev/null
56+
./node_modules/.bin/corner-store create "$SANDBOX_DIR" \
57+
--template sandbox \
58+
--sdk "file:$RFQ_TARBALL" \
59+
--toolkit "file:$TOOLKIT_TARBALL" \
60+
--cli "file:$CLI_TARBALL" >/dev/null
5761
)
5862

5963
test -f "$SANDBOX_DIR/sandbox/contracts/script/DeployStack.s.sol"
@@ -64,15 +68,89 @@ if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1;
6468
(cd "$SANDBOX_DIR" && docker compose config >/dev/null)
6569
fi
6670

71+
(
72+
cd "$SANDBOX_DIR"
73+
npm install --prefer-offline --silent
74+
npm test
75+
npm run validate >/dev/null
76+
npm run simulate >/dev/null
77+
if npm run --silent doctor >"$WORK_DIR/sandbox-doctor.json"; then
78+
: # A host with Compose v2 and a running daemon is sandbox-ready.
79+
else
80+
: # Missing Docker is an expected, actionable external-user state.
81+
fi
82+
)
83+
node -e '
84+
const result = require(process.argv[1]);
85+
const docker = result.checks.find((check) => check.name === "docker");
86+
const daemon = result.checks.find((check) => check.name === "docker-daemon");
87+
const unexpected = result.checks.filter((check) => check.required && !check.pass && !["docker", "docker-daemon"].includes(check.name));
88+
if (!docker || docker.required !== true || !docker.remediation) process.exit(1);
89+
if (!daemon || daemon.required !== true || !daemon.remediation) process.exit(1);
90+
if (unexpected.length > 0) process.exit(1);
91+
' "$WORK_DIR/sandbox-doctor.json"
92+
6793
(
6894
cd "$TARGET_DIR"
6995
npm install --prefer-offline --silent
7096
npm test
97+
npm run validate >/dev/null
98+
npm run simulate >/dev/null
7199
npm run policy:explain >/dev/null
72100
npm run doctor
73101
npm run deploy
102+
103+
mkdir -p deployments
104+
node - <<'NODE'
105+
const fs = require("fs");
106+
fs.writeFileSync("deployments/anvil-e2e.json", JSON.stringify({
107+
assetProfile: "reg-d",
108+
rwaToken: "0x1111111111111111111111111111111111111111",
109+
router: "0x2222222222222222222222222222222222222222",
110+
rfqAdapter: "0x3333333333333333333333333333333333333333",
111+
makerAuthorizer: "0x4444444444444444444444444444444444444444",
112+
rfqVenue: "0x5555555555555555555555555555555555555555"
113+
}, null, 2));
114+
NODE
115+
if npm run --silent verify >"$WORK_DIR/stale-artifact.log" 2>&1; then
116+
echo "stale artifact unexpectedly passed verification" >&2
117+
exit 1
118+
fi
119+
grep -q '"remediation"' "$WORK_DIR/stale-artifact.log"
120+
grep -q 'same asset profile' "$WORK_DIR/stale-artifact.log"
121+
122+
node - <<'NODE'
123+
const fs = require("fs");
124+
const path = "deployments/anvil-e2e.json";
125+
const artifact = JSON.parse(fs.readFileSync(path, "utf8"));
126+
artifact.assetProfile = "buidl-like";
127+
fs.writeFileSync(path, `${JSON.stringify(artifact, null, 2)}\n`);
128+
NODE
129+
npm run --silent verify >"$WORK_DIR/recovered-artifact.log"
130+
grep -q '"ready": true' "$WORK_DIR/recovered-artifact.log"
131+
132+
npm run --silent policy:explain >"$WORK_DIR/policy-before.json"
133+
node - <<'NODE'
134+
const fs = require("fs");
135+
const path = "corner-store.config.json";
136+
const config = JSON.parse(fs.readFileSync(path, "utf8"));
137+
config.venues.rfq = false;
138+
config.venues.orderBook = true;
139+
fs.writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
140+
NODE
141+
npm run --silent policy:explain >"$WORK_DIR/policy-after.json"
74142
)
75143

144+
node - <<'NODE' "$WORK_DIR/policy-before.json" "$WORK_DIR/policy-after.json"
145+
const fs = require("fs");
146+
const before = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
147+
const after = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
148+
if (before.compiled.configHash === after.compiled.configHash) process.exit(1);
149+
if (before.explanation.decisions.rfq.allowed !== true) process.exit(1);
150+
if (after.explanation.decisions.rfq.allowed !== false) process.exit(1);
151+
if (after.explanation.decisions.rfq.reasonCode !== "VENUE_DISABLED") process.exit(1);
152+
NODE
153+
76154
CLI_PACKAGE="$BOOT_DIR/node_modules/@corner-store/cli"
77155
if ! forge build --offline --root "$CLI_PACKAGE/bundle/contracts" >"$WORK_DIR/forge-build.log" 2>&1; then
78156
cat "$WORK_DIR/forge-build.log"

‎services/cli/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ program
3838

3939
program
4040
.command("doctor")
41-
.description("diagnose Node, Foundry, config, contract bundle, artifact, and optional Docker")
41+
.description("diagnose Node, Foundry, config, contract bundle, artifact, and template-aware Docker readiness")
4242
.argument("[path]", "config JSON path", "corner-store.config.json")
4343
.action(run((path, _opts, command) => cmd.cmdDoctor(path, command.optsWithGlobals())));
4444

0 commit comments

Comments
 (0)