From 2d0d815800951929119b5fc242986630f387c1f9 Mon Sep 17 00:00:00 2001 From: DeFine <76160388+its-DeFine@users.noreply.github.com> Date: Sun, 13 Sep 2026 15:58:23 +0000 Subject: [PATCH 1/2] docs: add bounded Livepeer production opt-in contract --- README.md | 6 +++++ docs/INSTALL.md | 23 ++++++++++++++++ docs/LIVEPEER_STAGING_INSTALL.md | 23 +++++++++++++--- docs/RELEASES.md | 26 ++++++++++++++++--- docs/preview19-runtime-contract.json | 6 ++--- .../preview19/provider-agent.example.json | 2 +- tests/docs-contract.sh | 20 ++++++++++++++ 7 files changed, 96 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 43297c8..1be3578 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,12 @@ payment behavior `PAYMENT_DISABLED`. See [Livepeer staging compatibility](docs/L Install the 19.5 bundle only from a matching non-draft release with its exact archive and same-release `SHA256SUMS`; the source checkout is not install authority. +Preview.19.6 is a separately gated contract update, not an installable release +until its matching archive and checksum are published. It preserves the public +zero-price defaults while describing an explicitly allowlisted Livepeer +production opt-in; the shipped CLI still does not carry payer or native-signer +custody. + [`v0.1.0-preview.18`](https://github.com/its-DeFine/punch-cli/releases/tag/v0.1.0-preview.18) is historical release provenance, not the current install target. Its archive SHA-256 is `d144fd266328c022ef2601feb871ff62396a293d5e35e7130a3880cc0cdaf423`. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 2e8e651..a5d8e1d 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -59,6 +59,29 @@ outside the CLI. The optional Livepeer commands remain staging-only; install Preview.19.5 only from a matching non-draft release with its exact archive, same-release `SHA256SUMS`, and bundled `RELEASE-CONTRACT.json`; see [Livepeer staging compatibility](LIVEPEER_STAGING_INSTALL.md). +## Preview.19.6 production opt-in boundary + +The next Preview.19.6 runtime contract retains the shipped public defaults: +`offerPolicy: PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER`, `priceMinor: 0`, +and `paymentSettlementEnabled: false`. Those fields describe the safe public +bundle defaults; they do not silently enable payment, and the false settlement +value is not a universal statement that a separately gated production Control +deployment cannot settle. + +A production paid deployment requires Control configuration with +`livepeerPayments.enabled: true`, `environment: "production"`, a shared +payer actor/address, and `liveChain` on chain `42161`. That chain must pin an +uncredentialed HTTPS RPC, TicketBroker, and a bounded provider allowlist. Each +mapped provider must bind its recipient, runtime input, issuance journal, +`maxContractMinor`, and `maxInstallmentExpectedValueWei` caps. Free SPOT and +FUTURE behavior remains unchanged. The native orchestrator and local signer are +separate owner-managed components; native expected value is distinct from a +verified on-chain redemption. + +Preview.19.6 remains gated until the matching versioned archive, release +contract, and checksum are published. Installing a new CLI version does not +copy profiles or keys, recreate offers, or replace an existing native service. + ## Default locations User installation: diff --git a/docs/LIVEPEER_STAGING_INSTALL.md b/docs/LIVEPEER_STAGING_INSTALL.md index 8827e52..c21d9eb 100644 --- a/docs/LIVEPEER_STAGING_INSTALL.md +++ b/docs/LIVEPEER_STAGING_INSTALL.md @@ -82,6 +82,22 @@ plumbing, not part of the public installation path. must stay unchanged for an exact retry. Its default Livepeer mode is `attach-existing`, pointing at an operator-provisioned native endpoint. +## Preview.19.6 production opt-in boundary + +The public 19.5 staging bundle remains payment-disabled. The gated 19.6 +contract describes a bounded production opt-in without changing the public +Provider onboarding path. Control must explicitly enable +`livepeerPayments` for `environment: "production"` and provide `liveChain` +on chain `42161`, an uncredentialed HTTPS RPC, TicketBroker, and a non-empty +provider allowlist. Every mapped provider binds its exact recipient, private +runtime input and issuance journal, `maxContractMinor`, and +`maxInstallmentExpectedValueWei`; unmapped actors or recipient drift are +rejected before issuance. The shipped defaults remain +`offerPolicy: PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER`, `priceMinor: 0`, +and `paymentSettlementEnabled: false`. They do not enable paid settlement by +themselves. Free SPOT/FUTURE behavior is preserved. Native expected value is +separate from realized value, which requires verified on-chain redemption. + ## Upgrade or runtime-only change For a verified package upgrade, use the normal installer activation path. It @@ -113,6 +129,7 @@ verified bundle. `config-update` preserves identity, credential, state, and offers; it does not create onboarding, replace native or payer/signer custody, or issue or redeem payment tickets. -Production deployment configuration keeps Control payment behavior -`PAYMENT_DISABLED`. Native binary and payer/signer custody remain outside the -CLI, and this staging page does not change the public onboarding path. +The public 19.5 deployment configuration keeps Control payment behavior +`PAYMENT_DISABLED`; the gated 19.6 opt-in is configured separately in Control. +Native binary and payer/signer custody remain outside the CLI, and this staging +page does not change the public onboarding path. diff --git a/docs/RELEASES.md b/docs/RELEASES.md index be8303c..1d72834 100644 --- a/docs/RELEASES.md +++ b/docs/RELEASES.md @@ -21,12 +21,32 @@ identity is not install authority. `punch-cli-0.1.0-preview.19.4-linux-x64.tar.gz` and SHA-256 `ae7bfbb5c9e9b278e45e025853f35833997525b595a5ab6abaef54544f7450ac`. Its contract page and release identity stay unchanged. The 19.5 bundle ships optional Livepeer commands, while payment execution -remains staging-only. Production deployment configuration keeps Control payment +remains staging-only. The public 19.5 deployment configuration keeps Control payment behavior `PAYMENT_DISABLED`; source docs and a staging endpoint do not enable -native payment, payer/signer custody, or settlement. Attach-existing compatibility -is covered in [Livepeer staging compatibility](LIVEPEER_STAGING_INSTALL.md). +native payment, payer/signer custody, or settlement. The gated 19.6 opt-in is +configured separately in Control. Attach-existing compatibility is covered in +[Livepeer staging compatibility](LIVEPEER_STAGING_INSTALL.md). Install the 19.5 bundle only from a matching non-draft GitHub release with its archive and same-release `SHA256SUMS`. + +## Preview.19.6 bounded Livepeer opt-in (gated) + +Preview.19.6 is a gated contract update. It is not an installable release +until the matching archive, `RELEASE-CONTRACT.json`, and same-release +`SHA256SUMS` are published. Its public contract uses +`PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER` while retaining +`priceMinor: 0` and `paymentSettlementEnabled: false` as shipped defaults. +The default public path remains zero-price and payment-disabled. + +The opt-in paid path is Control-gated: production requires +`livepeerPayments.enabled: true`, `environment: "production"`, one payer +actor/address, and `liveChain` on chain `42161` with an uncredentialed HTTPS +RPC, TicketBroker, and a bounded provider allowlist. Each provider mapping +pins its recipient, runtime input, issuance journal, and contract/installment +caps. Free SPOT and FUTURE behavior remains unchanged. The CLI carries no +payer or native-signer custody; native expected value and verified on-chain +redemption remain separate proof fields. + The historical [`v0.1.0-preview.18`](https://github.com/its-DeFine/punch-cli/releases/tag/v0.1.0-preview.18) package used this exact public image set: diff --git a/docs/preview19-runtime-contract.json b/docs/preview19-runtime-contract.json index 453b63a..2e57e89 100644 --- a/docs/preview19-runtime-contract.json +++ b/docs/preview19-runtime-contract.json @@ -1,12 +1,12 @@ { "schemaVersion": "punch.preview19-runtime-contract.v1", - "releaseVersion": "0.1.0-preview.19.5", + "releaseVersion": "0.1.0-preview.19.6", "platform": "linux-x64", - "privateReleaseSource": {"commit": "1f244682860d973295d0041c588d7336ad85f073", "tree": "525741f5547bf6719f1ef5c43879a17e092b6713"}, + "privateReleaseSource": {"commit": "ROOT_PRIVATE_COMMIT_PENDING", "tree": "ROOT_PRIVATE_TREE_PENDING"}, "accessTransport": "NETBIRD_CONTRACT_SCOPED_GATEWAY", "buyerNetBirdBootstrap": "PUNCH_JOIN_ONE_OFF_NARROW_GROUP", "gatewayPort": 22222, - "offerPolicy": "PUBLIC_OR_TARGETED_ZERO_ONLY", + "offerPolicy": "PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER", "priceMinor": 0, "paymentSettlementEnabled": false, "selfServiceProviderOnboarding": false, diff --git a/packaging/preview19/provider-agent.example.json b/packaging/preview19/provider-agent.example.json index 2aa5307..dfe570f 100644 --- a/packaging/preview19/provider-agent.example.json +++ b/packaging/preview19/provider-agent.example.json @@ -4,7 +4,7 @@ "credentialFile": "/var/lib/punch-provider/preview19/provider-credential.private.json", "stateDirectory": "/var/lib/punch-provider/preview19", "netBirdGateway": {"enabled": true, "interfaceName": "wt0", "netBirdOverlayIp": "REPLACE_WITH_PROVIDER_NETBIRD_OVERLAY_IP", "gatewayPort": 22222}, - "offerPolicy": {"offerPolicy": "PUBLIC_OR_TARGETED_ZERO_ONLY", "priceMinor": 0, "paymentSettlementEnabled": false, "selfServiceProviderOnboarding": false, "offerContractSchema": "punch.offer.v2", "resourceSnapshotSchema": "punch.resource-snapshot.v2"}, + "offerPolicy": {"offerPolicy": "PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER", "priceMinor": 0, "paymentSettlementEnabled": false, "selfServiceProviderOnboarding": false, "offerContractSchema": "punch.offer.v2", "resourceSnapshotSchema": "punch.resource-snapshot.v2"}, "imagePolicies": { "VALIDATION": {"image": "ghcr.io/its-define/punch-validation@sha256:d7de3c3549c2e36c1f5ef5237a671c7f06e44eb101c17be2faeca12a267adf86", "command": ["/punch/validate"], "inputKeys": ["nonce"]}, "WORKLOAD": {"image": "ghcr.io/its-define/punch-workload@sha256:16fdfad931a97834bbe89c6a66724405e502535b9f8c35a971e91ed07b1242ce", "command": ["/punch/run"], "inputKeys": ["nonce", "window_seconds"]}, diff --git a/tests/docs-contract.sh b/tests/docs-contract.sh index 2beb79d..09b74f6 100755 --- a/tests/docs-contract.sh +++ b/tests/docs-contract.sh @@ -200,6 +200,26 @@ require docs/INSTALL.md "Preview.19.4's Provider scope is Ubuntu 24.04 LTS on Li require docs/INSTALL.md 'punch-cli-0.1.0-preview.19.4-linux-x64.tar.gz' require docs/INSTALL.md 'NEW_PUNCH_PROVIDER="$HOME/.local/share/punch-cli/0.1.0-preview.19.4/bin/punch-provider"' require docs/INSTALL.md 'service-install --machine-id MACHINE_ID --state-dir EXISTING_STATE_DIR --yes' +require docs/RELEASES.md 'Preview.19.6 bounded Livepeer opt-in (gated)' +require docs/INSTALL.md 'livepeerPayments.enabled: true' +require docs/LIVEPEER_STAGING_INSTALL.md 'PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER' + +node <<'NODE' +const fs = require('fs'); +const runtime = JSON.parse(fs.readFileSync('docs/preview19-runtime-contract.json', 'utf8')); +const provider = JSON.parse(fs.readFileSync('packaging/preview19/provider-agent.example.json', 'utf8')); +if (runtime.releaseVersion !== '0.1.0-preview.19.6' + || runtime.offerPolicy !== 'PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER' + || runtime.priceMinor !== 0 || runtime.paymentSettlementEnabled !== false) { + throw new Error('Preview.19.6 runtime contract defaults drifted'); +} +if (provider.offerPolicy.offerPolicy !== 'PUBLIC_OR_TARGETED_ZERO_WITH_OPT_IN_LIVEPEER' + || provider.offerPolicy.priceMinor !== 0 + || provider.offerPolicy.paymentSettlementEnabled !== false) { + throw new Error('Preview.19.6 Provider example defaults drifted'); +} +process.stdout.write('Preview.19.6 opt-in contract defaults: PASS\n'); +NODE require docs/GUIDED_CLI.md 'PENDING_AGENT' require docs/GUIDED_CLI.md 'resumable until the exact Buyer/NetBird binding' require docs/GUIDED_CLI.md 'Multiple supervised Providers' From 2f07e872d45e0da5d1bd0d3672f7cc07fd50e80d Mon Sep 17 00:00:00 2001 From: DeFine <76160388+its-DeFine@users.noreply.github.com> Date: Sun, 13 Sep 2026 16:22:09 +0000 Subject: [PATCH 2/2] Bind Preview19.6 public contract to tested production source --- docs/preview19-runtime-contract.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/preview19-runtime-contract.json b/docs/preview19-runtime-contract.json index 2e57e89..ac1e17f 100644 --- a/docs/preview19-runtime-contract.json +++ b/docs/preview19-runtime-contract.json @@ -2,7 +2,7 @@ "schemaVersion": "punch.preview19-runtime-contract.v1", "releaseVersion": "0.1.0-preview.19.6", "platform": "linux-x64", - "privateReleaseSource": {"commit": "ROOT_PRIVATE_COMMIT_PENDING", "tree": "ROOT_PRIVATE_TREE_PENDING"}, + "privateReleaseSource": {"commit": "b5ae4479be6b8c0f87847977cb15578158a22dd2", "tree": "e9496a2446f31c9eab26c16670a9dccfd2d26524"}, "accessTransport": "NETBIRD_CONTRACT_SCOPED_GATEWAY", "buyerNetBirdBootstrap": "PUNCH_JOIN_ONE_OFF_NARROW_GROUP", "gatewayPort": 22222,