From 69e91c253338e7ae416a7629e2efe03f42f3884c Mon Sep 17 00:00:00 2001 From: Programmable <309941960+0xprogrammable@users.noreply.github.com> Date: Wed, 29 Jul 2026 02:56:51 +0200 Subject: [PATCH] Add hook builder submission process --- .github/ISSUE_TEMPLATE/config.yml | 5 +- .github/ISSUE_TEMPLATE/launch-model.yml | 44 --------- .github/PULL_REQUEST_TEMPLATE.md | 44 ++++++++- BUILDER_PROGRAM.md | 121 ++++++++++++++++++++++++ CONTRIBUTING.md | 21 ++++ README.md | 5 + models/ACCEPTANCE_RECORD_TEMPLATE.md | 47 +++++++++ 7 files changed, 241 insertions(+), 46 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/launch-model.yml create mode 100644 BUILDER_PROGRAM.md create mode 100644 models/ACCEPTANCE_RECORD_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index df40f977..87b077f8 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: + - name: Submit a launch model + url: https://github.com/0xprogrammable/programmable/blob/main/BUILDER_PROGRAM.md + about: Read the requirements and submit a complete model by pull request. - name: Report a security vulnerability url: https://github.com/0xprogrammable/programmable/security/advisories/new about: Send vulnerabilities privately to the maintainers. diff --git a/.github/ISSUE_TEMPLATE/launch-model.yml b/.github/ISSUE_TEMPLATE/launch-model.yml deleted file mode 100644 index 2de6144f..00000000 --- a/.github/ISSUE_TEMPLATE/launch-model.yml +++ /dev/null @@ -1,44 +0,0 @@ -name: Launch model proposal -description: Propose a new Uniswap v4 launch model for Programmable. -title: "" -body: - - type: input - id: name - attributes: - label: Model name - placeholder: A short working name - validations: - required: true - - type: textarea - id: use-case - attributes: - label: Use case - description: Explain who needs the model and what they cannot do with an existing model. - validations: - required: true - - type: textarea - id: behavior - attributes: - label: Pool behavior - description: Describe the behavior that belongs in the hook or supporting contracts. - validations: - required: true - - type: textarea - id: permissions - attributes: - label: Hook permissions and accounting - description: List expected callbacks, return deltas, fee paths and external calls. - validations: - required: true - - type: textarea - id: upstream - attributes: - label: Upstream components - description: Link relevant Uniswap, OpenZeppelin or other primary sources. - - type: textarea - id: security - attributes: - label: Security properties - description: State the invariants and failure modes that must be tested. - validations: - required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8015de5d..5defb1d8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,57 @@ +## Submission type + +- [ ] New launch model +- [ ] Existing model change +- [ ] Tests, documentation or tooling + ## Change -Describe the behavior being changed and why it belongs in Programmable. +Describe the behavior, the user it serves and why it belongs in Programmable. + +For a new launch model: + +- Model name: +- Builder GitHub identity: +- Builder beneficiary address: +- Source paths: +- Model documentation: + +## Model behavior + +For a new model or contract change, describe: + +- pool shape and supported assets; +- hook permissions and return deltas; +- fee paths, rounding and accounting; +- external calls and dependencies; +- privileged roles, upgradeability or autonomous actions; and +- expected invariants and failure modes. ## Verification - [ ] `forge fmt --check` - [ ] `forge build` - [ ] `FOUNDRY_PROFILE=ci forge test` +- [ ] Unit and integration coverage is included +- [ ] Fuzz and invariant coverage is included where applicable +- [ ] Compiler and dependency versions are fixed +- [ ] Model documentation states trust assumptions and known limitations - [ ] Deployment evidence is updated when addresses or runtime code change ## Security List any new hook permissions, accounting paths, external calls or trust assumptions. Write `None` when the change does not affect them. + +Do not include an undisclosed vulnerability in this pull request. Follow +[`SECURITY.md`](https://github.com/0xprogrammable/programmable/blob/main/SECURITY.md). + +## Submission terms + +For a new launch model: + +- [ ] I have read the [Hook Builder Program](https://github.com/0xprogrammable/programmable/blob/main/BUILDER_PROGRAM.md) +- [ ] I have the right to submit this code under the repository's MIT License +- [ ] Required notices for third-party code are included +- [ ] I understand that a pull request does not guarantee acceptance, deployment, volume or revenue +- [ ] I understand that any builder allocation applies only after an acceptance record identifies the exact model version, commit and beneficiary diff --git a/BUILDER_PROGRAM.md b/BUILDER_PROGRAM.md new file mode 100644 index 00000000..401c3d41 --- /dev/null +++ b/BUILDER_PROGRAM.md @@ -0,0 +1,121 @@ +# Hook Builder Program + +Programmable accepts complete, open-source Uniswap v4 launch models from independent builders. + +Submit a model by forking this repository and opening a pull request. The pull request must contain the implementation, +tests and documentation needed to review the model as a complete release candidate. + +## What to submit + +A model submission must include: + +- Solidity source for the hook and every supporting contract; +- unit and integration tests for the complete launch path; +- fuzz and invariant tests for permissions, accounting and model-specific properties; +- a model document under `models//README.md`; +- fixed compiler and dependency versions; +- all hook permissions, return deltas, external calls and privileged roles; +- fee calculations, rounding behavior and supported pool shape; +- trust assumptions, known limitations and failure modes; +- deployment and source-verification instructions; and +- the builder's GitHub identity and Ethereum beneficiary address. + +Keep each model isolated: + +```text +models//README.md Behavior, economics and security assumptions +src/.sol Hook and supporting contracts +test/.t.sol Unit and integration tests +test/invariant/.t.sol Stateful invariants +spec/.json Fixed parameters and dependency versions +``` + +Use the pull request template as the submission checklist. Do not include private keys, credentials or non-public +security findings. + +## Selection + +A pull request is a public, non-confidential submission. Opening one does not guarantee review, acceptance, deployment, +trading volume or revenue. Programmable may request changes, decline a submission or be working independently on a +similar model. + +Models are evaluated on: + +- usefulness as a distinct launch model; +- correctness and simplicity; +- accounting and permission safety; +- test and documentation quality; +- dependency and operational risk; +- gas and integration cost; and +- whether the behavior can be presented clearly to token creators and traders. + +Security requirements depend on the model's risk. Programmable may require additional testing, independent review, +monitoring or a bug bounty before release. Passing repository checks is not a security certification. + +## Accepted models + +Selection is recorded in an acceptance record before release. The record identifies: + +- the model and version; +- the accepted commit; +- the builder and beneficiary address; +- the applicable fee allocation; +- the source license; and +- the scope of the builder's participation. + +Selection is final only when a completed +[acceptance record](models/ACCEPTANCE_RECORD_TEMPLATE.md) is merged into the repository. + +For an accepted external-builder model with a total swap fee of 1.00%, the allocation is fixed: + +| Recipient | Share of swap volume | +| --- | ---: | +| Token creator | 0.80% | +| Hook builder | 0.10% | +| Programmable | 0.10% | + +The builder share is part of the published 1.00% fee. It is not added on top. It applies only to launches through the +exact accepted model version and does not create rights to later versions or derivative models. The deployed contracts +and release record must match the disclosed allocation. + +For Ethereum models, these fees are accounted for and paid in native ETH. Only the builder beneficiary may claim its +share or change its payout address. Changing the payout address does not change the builder allocation. Programmable +cannot redirect or reduce the accepted builder share for that deployed version. + +Models developed by Programmable without an external builder allocate 0.90% to the token creator and 0.10% to +Programmable when the published total fee is 1.00%. + +No minimum volume, launch count or income is promised. + +## Ownership and license + +Builders retain copyright in their original work. By submitting a pull request, each contributor confirms that they +have the right to submit the code and license it under this repository's [MIT License](LICENSE). Programmable may review, +modify, test, deploy and publish accepted code under that license. + +Third-party code must retain its required notices and use a license compatible with MIT distribution. Submissions with +unclear ownership or incompatible licensing will not be accepted. + +## Attribution + +An accepted builder is credited in the model documentation and acceptance record. Contract NatSpec and release +metadata should preserve that attribution where practical. + +Attribution does not imply that Uniswap Labs, Uniswap Foundation or any other third party reviewed or endorsed the +model. + +## Versions and changes + +Published contracts are immutable. A material contract change creates a new model version with new tests, security +documentation and deployment evidence. + +The builder allocation for an accepted deployed version remains attached to that version. A fix, rewrite, successor or +derivative requires a new acceptance record unless the existing record explicitly covers it. + +Programmable may stop offering new launches through a version when security, legal, operational or product concerns +arise. Existing deployed contracts continue to behave according to their code. + +## Security reports + +Do not disclose vulnerabilities in a pull request or public issue. Follow [SECURITY.md](SECURITY.md) and use GitHub +private vulnerability reporting. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 189917b5..31292ba8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,24 @@ before changing a contract or proposing a new model. Changes should be small, reviewable and covered by a test that fails before the fix. +## New launch models + +Submit a complete model as a pull request. Do not open an issue containing only an idea and do not disclose +vulnerabilities publicly. + +Read the [Hook Builder Program](BUILDER_PROGRAM.md) before starting. A model submission must include its contracts, +tests, security assumptions, known limitations, documentation, license declarations and builder beneficiary address. +The pull request template contains the complete checklist. + +A pull request is a public, non-confidential submission. It does not guarantee acceptance, deployment or revenue. An +external builder participates in model revenue only after Programmable publishes an acceptance record for the exact +model version. + +## Existing models + +Bug fixes, test improvements and documentation corrections are welcome. Explain the affected behavior and keep changes +scoped to the relevant model. + Before opening a pull request: ```bash @@ -18,4 +36,7 @@ Changing source does not change a contract that is already deployed. A new model tests, security documentation, source verification and deployment record before it can be marked `Available` in [`MODELS.md`](MODELS.md). +By submitting code, each contributor confirms that they have the right to submit it under the repository's +[MIT License](LICENSE). Preserve notices for compatible third-party code. + Use [`SECURITY.md`](SECURITY.md) for vulnerability reports instead of opening a public issue. diff --git a/README.md b/README.md index 6a7ab498..95873707 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@

Launch · Models · + Build a model · Ethereum · Security · X @@ -33,6 +34,9 @@ the token details and launch without writing Solidity. This repository contains the contracts behind every published model. Each available release includes its exact source, tests, security documentation and Ethereum deployment record. +Independent builders can submit complete launch models through the +[Hook Builder Program](BUILDER_PROGRAM.md). Submissions are reviewed before any model is accepted or released. + ## Launch models | Model | Pool behavior | Status | @@ -66,6 +70,7 @@ test/ Unit, integration, fuzz, invariant and regression tests deployments/ Ethereum addresses, transactions and runtime code hashes spec/ Machine-readable contract parameters scripts/ Reproducible dependency bootstrap +BUILDER_PROGRAM.md External model submission and participation terms SECURITY.md Repository security policy and current contract status ``` diff --git a/models/ACCEPTANCE_RECORD_TEMPLATE.md b/models/ACCEPTANCE_RECORD_TEMPLATE.md new file mode 100644 index 00000000..7e8d6af7 --- /dev/null +++ b/models/ACCEPTANCE_RECORD_TEMPLATE.md @@ -0,0 +1,47 @@ +# Model Acceptance Record + +This template records selection of an external-builder launch model. A completed record belongs under +`models//ACCEPTANCE.md`. + +## Model + +- Name: +- Version: +- Status: +- Accepted commit: +- Supported chain: + +## Builder + +- GitHub identity: +- Attribution: +- Beneficiary address: + +## Fee allocation + +- Total swap fee: +- Fee currency: +- Token creator: +- Hook builder: +- Programmable: + +The allocation applies only to launches through the model version and commit identified above. + +## Scope + +- Included contracts: +- Included behavior: +- Excluded successors or derivatives: + +## License + +- Source license: +- Third-party notices: + +## Review + +- Repository checks: +- Additional security work: +- Deployment record: +- Source verification: +- Fee-routing contracts: