@ola-893/buidl 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -50
- package/build-cli/buidl.mjs +7912 -7147
- package/docs/cli-demo.md +43 -77
- package/docs/cli.md +90 -0
- package/package.json +3 -3
package/docs/cli-demo.md
CHANGED
|
@@ -1,111 +1,77 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Recording with the CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Use the actual operational commands below, one at a time. There is no bundled demo command. Prepare your funded testnet holder and two reviewer wallets, a small build directory and a clean recording terminal.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This sequence uses X Layer testnet (1952) and explicitly labeled buidl hosting fixtures. It does not deploy actual TapeOut testnet contracts. The software's adversarial integration tests run separately from the presentation.
|
|
6
6
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
Use Node.js 22.13+; install Foundry's `anvil` for the disposable demo.
|
|
7
|
+
## Holder: connect and register
|
|
10
8
|
|
|
11
9
|
```sh
|
|
12
|
-
npm install -g @ola-893/buidl@0.
|
|
10
|
+
npm install -g @ola-893/buidl@0.5.0
|
|
13
11
|
buidl --version
|
|
14
|
-
buidl --
|
|
12
|
+
buidl wallet connect --network testnet
|
|
13
|
+
buidl wallet show
|
|
14
|
+
buidl app init checkout --network testnet --reviewers 0xREVIEWER1,0xREVIEWER2
|
|
15
|
+
buidl app deploy
|
|
16
|
+
buidl app deploy --execute
|
|
17
|
+
buidl app enroll --execute
|
|
18
|
+
buidl app register --execute
|
|
19
|
+
buidl policy show
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
Replace the address placeholders. Wallet connection signs a message without a gas fee. Deploying, enrolling and registering open separate transaction confirmations with estimates. For an existing app, initialize with its `--fixtures` configuration and inspect `app status` instead of deploying again.
|
|
18
23
|
|
|
19
|
-
##
|
|
24
|
+
## Developer: prepare the release
|
|
20
25
|
|
|
21
26
|
```sh
|
|
22
|
-
buidl
|
|
27
|
+
buidl release create checkout-v1 --build ./dist --out ./manifest.json
|
|
28
|
+
buidl release inspect ./manifest.json
|
|
29
|
+
buidl release request ./manifest.json --out ./approval-request.json
|
|
23
30
|
```
|
|
24
31
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
For a short recording, explain the question: “Does the deployed app still match what the team approved?” Run the command, point out the valid-hash mismatch and the failed ownership reuse, then open `demo-evidence/results.json`. The evidence labels the local network explicitly. Actual public testnet receipts belong in a separate segment.
|
|
28
|
-
|
|
29
|
-
## Actual X Layer testnet
|
|
32
|
+
Explain that the manifest commits to exact files, lengths, content types and routing. The request also binds the reviewers' signatures to this registry, chain, policy, sequence and expiry.
|
|
30
33
|
|
|
31
|
-
|
|
34
|
+
## Reviewer one
|
|
32
35
|
|
|
33
36
|
```sh
|
|
34
|
-
buidl
|
|
35
|
-
buidl
|
|
36
|
-
buidl testnet deploy
|
|
37
|
-
buidl testnet deploy --broadcast --wallet
|
|
38
|
-
buidl testnet enroll --broadcast --wallet
|
|
39
|
-
buidl testnet policy --broadcast --wallet
|
|
37
|
+
buidl wallet connect --network testnet --account 0xREVIEWER1
|
|
38
|
+
buidl release sign ./approval-request.json --out ./reviewer1.json
|
|
40
39
|
```
|
|
41
40
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
All writes default to previews. `--broadcast --wallet` opens a small, temporary wallet review page on `127.0.0.1:5362`. Reusing this local origin avoids reconnecting the extension for every transaction. Only one CLI wallet request can run at a time. The terminal prints each estimated test OKB gas maximum before signing. The page displays the account, chain, destination, nonce and exact payload; choose your wallet and click **Review in wallet**, then confirm in the extension. The CLI verifies the returned signature or transaction against its original request. It never accepts a private key. The estimate is gas limit × quoted gas price; the wallet presents the final network fee.
|
|
45
|
-
|
|
46
|
-
```sh
|
|
47
|
-
buidl testnet manifest ./build --release checkout-a --out ./manifest.json
|
|
48
|
-
buidl testnet request ./manifest.json --out ./request.json
|
|
49
|
-
buidl testnet sign ./request.json --reviewer 0xREVIEWER1 --out ./reviewer1.json --wallet
|
|
50
|
-
buidl testnet sign ./request.json --reviewer 0xREVIEWER2 --out ./reviewer2.json --wallet
|
|
51
|
-
buidl testnet approve ./reviewer1.json ./reviewer2.json
|
|
52
|
-
buidl testnet approve ./reviewer1.json ./reviewer2.json --broadcast --wallet
|
|
53
|
-
buidl testnet gate ./build ./manifest.json
|
|
54
|
-
buidl testnet publish ./build ./manifest.json --broadcast --wallet
|
|
55
|
-
buidl testnet verify --manifest ./manifest.json --out ./verification.json
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Switch to the named reviewer for each signature and back to the holder for publishing. Separate signed files merge only when they describe exactly the same request. The holder cannot count as a reviewer. Previously approved artifacts require a new `request --rollback` and fresh reviewer signatures.
|
|
59
|
-
|
|
60
|
-
The manifest must stay outside the build directory. The publisher stages all bytes, rechecks their hashes, verifies the onchain files before finishing, and reconstructs the final release at a checked block. A successful `verify` exits 0. A completed check without an approved match exits 2; input, network and gate failures exit 1. `--json` produces structured output; piped stdout uses JSON automatically.
|
|
61
|
-
|
|
62
|
-
## Resume and lifecycle controls
|
|
41
|
+
## Reviewer two
|
|
63
42
|
|
|
64
43
|
```sh
|
|
65
|
-
buidl
|
|
66
|
-
buidl
|
|
67
|
-
buidl testnet publish ./build ./manifest.json --broadcast --wallet
|
|
68
|
-
buidl testnet revoke --broadcast --wallet
|
|
69
|
-
buidl testnet recover --broadcast --wallet
|
|
70
|
-
buidl testnet transfer --to 0xNEWOWNER --broadcast --wallet
|
|
71
|
-
buidl testnet enroll --from 0xNEWOWNER --broadcast --wallet
|
|
72
|
-
buidl testnet verify
|
|
73
|
-
buidl testnet recover --from 0xNEWOWNER --broadcast --wallet
|
|
44
|
+
buidl wallet connect --network testnet --account 0xREVIEWER2
|
|
45
|
+
buidl release sign ./approval-request.json --out ./reviewer2.json
|
|
74
46
|
```
|
|
75
47
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
`publish` resumes a matching in-progress attempt and skips files only when fresh onchain byte verification matches their exact manifest hash, size and type. Incomplete or changed files are rewritten deterministically. It does not mark an interrupted release as verified. After an interrupted deployment, repeat `deploy`; the saved deployment plan permits resuming the missing authority without redeploying the fixture. If the nonce changed before the first deployment, inspect the saved plan before replacing it.
|
|
48
|
+
Switch the account in your extension when asked. The CLI verifies each recovered reviewer independently. In a team, reviewers can perform these commands separately and return their signed request files.
|
|
79
49
|
|
|
80
|
-
|
|
50
|
+
## Holder: approve, publish and verify
|
|
81
51
|
|
|
82
52
|
```sh
|
|
83
|
-
buidl
|
|
53
|
+
buidl wallet connect --network testnet --account 0xHOLDER
|
|
54
|
+
buidl release approve ./reviewer1.json ./reviewer2.json
|
|
55
|
+
buidl release approve ./reviewer1.json ./reviewer2.json --execute
|
|
56
|
+
buidl release gate ./dist ./manifest.json
|
|
57
|
+
buidl release publish ./dist ./manifest.json --execute
|
|
58
|
+
buidl release verify --manifest ./manifest.json --out ./verification.json
|
|
59
|
+
buidl wallet history
|
|
84
60
|
```
|
|
85
61
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
For a controlled mismatch demonstration, generate a second manifest from a build with a different `payment.json`, then run `buidl testnet mutate <changed-build> <changed-manifest> --broadcast --wallet`. This fixture-only operation intentionally bypasses the normal artifact gate while keeping a valid file hash. Fresh verification must report divergence. It is distinct from the normal gated publisher.
|
|
62
|
+
Show the preview, real wallet confirmations, public receipts and checked verification block. You decide when to run each command. Keep the manifest and request exports outside the build directory.
|
|
89
63
|
|
|
90
|
-
|
|
64
|
+
For a changed-build gate check, edit a file in a copy of the build and run `release gate` against the approved manifest. It must fail before requesting a transaction. Changing the deployed files is a separate controlled test; a failed local gate alone does not demonstrate detection of an onchain content change.
|
|
91
65
|
|
|
92
|
-
|
|
66
|
+
## Optional lifecycle operations
|
|
93
67
|
|
|
94
68
|
```sh
|
|
95
|
-
buidl
|
|
96
|
-
buidl
|
|
69
|
+
buidl release revoke --execute
|
|
70
|
+
buidl release verify --manifest ./manifest.json
|
|
71
|
+
buidl app recover --execute
|
|
72
|
+
buidl wallet disconnect
|
|
97
73
|
```
|
|
98
74
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
## Recorded public fixture pilot
|
|
102
|
-
|
|
103
|
-
The actual holder and two reviewer wallets completed approval → CLI publishing → fresh verification on X Layer testnet 1952. [Verification evidence](testnet/results/cli-approved-release.json) records **Matches approved release** at block **46452266**, checked **2026-11-17 10:25:09 UTC**. [Final public receipt](https://www.okx.com/web3/explorer/xlayer-test/tx/0x2aa40ef20a4b93ab2b4cad85bfcb1d3bcddef574cfd8356caa04c0b29c824db9) · [All CLI receipts and estimates](testnet/cli-transactions.json).
|
|
104
|
-
|
|
105
|
-
From the checkout, perform a new read rather than relying on the saved result:
|
|
106
|
-
|
|
107
|
-
```sh
|
|
108
|
-
npm run buidl -- testnet verify --project docs/testnet/cli-project.json --manifest docs/testnet/manifest-a.json --json
|
|
109
|
-
```
|
|
75
|
+
Revocation changes the live verification result. Recovery returns custody to the depositor and invalidates the prior authority. Capture these after recording a successful approved match. Use `wallet reconcile --hash HASH` if a submitted transaction's browser response is interrupted.
|
|
110
76
|
|
|
111
|
-
|
|
77
|
+
The earlier [public fixture pilot](testnet/results/cli-approved-release.json) records holder/reviewer signing and a successful approved match. Its historical receipt evidence remains separate from a new run. For full operation and setup details, see [the CLI guide](cli.md).
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# buidl CLI
|
|
2
|
+
|
|
3
|
+
Install `@ola-893/buidl@0.5.0` from npm and run `buidl --help`. The CLI is an operational tool: you connect the wallets, submit each command and confirm signatures yourself.
|
|
4
|
+
|
|
5
|
+
## Wallets
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
buidl wallet connect --network testnet
|
|
9
|
+
buidl wallet show
|
|
10
|
+
buidl wallet disconnect
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Connect opens `http://127.0.0.1:5362` with a temporary request token. Choose an installed EVM browser wallet and the intended account. The network button can switch or add X Layer testnet, chain 1952. Sign the displayed connection message; the CLI recovers the signer and verifies the RPC chain before saving the public profile.
|
|
14
|
+
|
|
15
|
+
Use `--account 0xADDRESS` to require a specific holder or reviewer. Every later approval signature and transaction verifies the selected account and network again. Connecting never gives the CLI a private key or permission to sign later transactions automatically.
|
|
16
|
+
|
|
17
|
+
The default profile is `~/.config/buidl/wallet.json`. Set `BUIDL_HOME` to a separate directory for a different operator profile or terminal. `wallet disconnect` removes that profile. It does not revoke extension site permissions or cancel an open extension prompt.
|
|
18
|
+
|
|
19
|
+
For an RPC connection problem, specify `--rpc https://YOUR_TESTNET_RPC`. On the pilot Mac, the guarded loopback relay can be used with `--rpc http://127.0.0.1:8552`; it forwards to the public X Layer testnet. The local signing page uses the extension's selected network RPC.
|
|
20
|
+
|
|
21
|
+
## Apps and policies
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
buidl app init NAME --network testnet --reviewers ADDRESS1,ADDRESS2 --threshold 2
|
|
25
|
+
buidl app show
|
|
26
|
+
buidl app deploy
|
|
27
|
+
buidl app deploy --execute
|
|
28
|
+
buidl app enroll --execute
|
|
29
|
+
buidl app register --execute
|
|
30
|
+
buidl policy show
|
|
31
|
+
buidl policy set --reviewers ADDRESS1,ADDRESS2 --threshold 2 --execute
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The project lives in `buidl.json`, or the file given with `--project PATH`. Initialization defaults its holder to the connected wallet. `--owner ADDRESS` permits preparing a project before connecting. Reviewers must be distinct and cannot include the holder.
|
|
35
|
+
|
|
36
|
+
Testnet deployments use buidl's simulated circuit, file store and custody authority. They are not actual TapeOut testnet deployments. [Discovery and custody details](testnet-pilot.md) document the boundary. Enrollment transfers the circuit fixture into the authority; only its depositor can recover it while enrolled.
|
|
37
|
+
|
|
38
|
+
`app init --fixtures FILE` adopts a known fixture configuration. The CLI checks deployed runtime fingerprints, the authority binding and registry provenance before operating on it. Partial deployment plans persist so repeating `app deploy --execute` can resume the missing contract after reconciliation.
|
|
39
|
+
|
|
40
|
+
## Releases
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
buidl release create NAME --build DIRECTORY --out MANIFEST --fallback index.html
|
|
44
|
+
buidl release inspect MANIFEST
|
|
45
|
+
buidl release request MANIFEST --out REQUEST
|
|
46
|
+
buidl release sign REQUEST --out SIGNED
|
|
47
|
+
buidl release approve SIGNED1 SIGNED2
|
|
48
|
+
buidl release approve SIGNED1 SIGNED2 --execute
|
|
49
|
+
buidl release gate BUILD MANIFEST
|
|
50
|
+
buidl release publish BUILD MANIFEST --execute
|
|
51
|
+
buidl release verify --manifest MANIFEST --out REPORT
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Manifest creation reads your files and works offline once the project's site identity is configured. The manifest must be outside the build directory. The fixture publisher accepts files up to 60 KB, uploaded in 12 KB chunks.
|
|
55
|
+
|
|
56
|
+
`release sign` uses the connected reviewer wallet. Its EIP-712 signature binds the chain, site, registry, policy version, sequence, expiry, manifest and artifact set. Unauthorized, duplicate or expired signatures fail validation. Signed request files merge only if they describe the same exact approval.
|
|
57
|
+
|
|
58
|
+
`release approve` previews recording after verifying the threshold. With `--execute`, the active wallet submits it to the registry. `release publish` requires the connected circuit governor, rechecks exact build bytes and approval, requests each transaction separately, verifies deployed files and routing, then closes the publication. The final verification includes the checked block and time.
|
|
59
|
+
|
|
60
|
+
Previously approved artifacts require `release request MANIFEST --out NEW_REQUEST --rollback` and fresh reviewer signatures. A request or signature from before an ownership exit, policy change or re-enrollment cannot be reused.
|
|
61
|
+
|
|
62
|
+
## Recovery and history
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
buidl wallet history
|
|
66
|
+
buidl wallet reconcile --hash HASH
|
|
67
|
+
buidl release status
|
|
68
|
+
buidl release revoke --execute
|
|
69
|
+
buidl app recover --execute
|
|
70
|
+
buidl app transfer --to NEW_OWNER --execute
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The publisher saves `.buidl/transactions.json` next to the project, including estimates, nonces, hashes, receipts and paid gas. A normal rejection in the wallet is recorded as cancelled. An interruption with an uncertain outcome stops later writes; `wallet reconcile` validates the exact returned transaction against the original plan and records its receipt. Never submit again solely because a browser callback failed.
|
|
74
|
+
|
|
75
|
+
After a hard process kill, check wallet activity and the journal before removing a stale `.buidl/transaction.lock`. A wallet confirmation can still broadcast after the CLI exits. If it did, reconcile that hash before continuing. After reconciliation, `release publish` resumes the existing attempt and avoids uploading already verified files again.
|
|
76
|
+
|
|
77
|
+
Ownership exit and re-enrollment invalidate approval authority. Connect the new owner before enrolling. Update the reviewer policy to exclude the new owner before collecting fresh signatures; a confirmed policy change updates the project's configured owner and policy.
|
|
78
|
+
|
|
79
|
+
## Diagnostics and CI
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
buidl diagnostics
|
|
83
|
+
buidl doctor
|
|
84
|
+
buidl release gate ./dist ./manifest.json --project ./buidl.json --json
|
|
85
|
+
buidl release verify --project ./buidl.json --json
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Interactive output is concise; `--json` and pipes retain structured values. The exit codes are 0 for success, 2 for completed verification without a match, and 1 for input, RPC or gate failures. Verification and build gates do not require wallet connection.
|
|
89
|
+
|
|
90
|
+
The operational write workflow accepts testnet 1952 only. `buidl inspect IDENTIFIER` remains a separate read-only TapeOut mainnet inspection command. Viewer or gateway integration is required to block access to unapproved apps.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ola-893/buidl",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=22.13"
|
|
@@ -10,7 +10,6 @@
|
|
|
10
10
|
"build": "tsc --noEmit && vite build",
|
|
11
11
|
"preview": "vite preview --host 127.0.0.1",
|
|
12
12
|
"buidl": "tsx src/cli.ts",
|
|
13
|
-
"demo": "tsx scripts/demo.ts",
|
|
14
13
|
"test": "tsx --test tests/*.test.ts",
|
|
15
14
|
"test:browser": "playwright test",
|
|
16
15
|
"prepare": "npm run build:cli",
|
|
@@ -55,6 +54,7 @@
|
|
|
55
54
|
},
|
|
56
55
|
"files": [
|
|
57
56
|
"build-cli/",
|
|
57
|
+
"docs/cli.md",
|
|
58
58
|
"docs/cli-demo.md"
|
|
59
59
|
],
|
|
60
60
|
"description": "Release approval, gated publishing and fresh verification for DeWEB on X Layer",
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"access": "public",
|
|
63
63
|
"registry": "https://registry.npmjs.org/"
|
|
64
64
|
},
|
|
65
|
-
"homepage": "https://github.com/ola-893/buidl#readme",
|
|
65
|
+
"homepage": "https://github.com/ola-893/buidl/tree/v0.5.0#readme",
|
|
66
66
|
"bugs": {
|
|
67
67
|
"url": "https://github.com/ola-893/buidl/issues"
|
|
68
68
|
}
|