{"id":34573062,"url":"https://github.com/base/builder-codes","last_synced_at":"2026-05-24T13:35:42.601Z","repository":{"id":325100511,"uuid":"1066132238","full_name":"base/builder-codes","owner":"base","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-19T14:05:32.000Z","size":2687,"stargazers_count":6,"open_issues_count":2,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T13:35:13.650Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/base.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T04:21:41.000Z","updated_at":"2026-04-04T23:42:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/base/builder-codes","commit_stats":null,"previous_names":["base/builder-codes"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/base/builder-codes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/base%2Fbuilder-codes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/base%2Fbuilder-codes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/base%2Fbuilder-codes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/base%2Fbuilder-codes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/base","download_url":"https://codeload.github.com/base/builder-codes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/base%2Fbuilder-codes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33436554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T13:13:05.286Z","status":"ssl_error","status_checked_at":"2026-05-24T13:13:03.728Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T09:45:38.426Z","updated_at":"2026-05-24T13:35:42.596Z","avatar_url":"https://github.com/base.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Builder Codes\n\nAn ERC-721 NFT contract that enables builders to register unique codes (e.g., `\"myapp\"`) with an associated payout addresses for revenue attribution and distribution. Implements the [ERC-8021](https://eip.tools/eip/8021) `ICodesRegistry` interface.\n\n## Features\n\n- **Unique Code Registration**: Mint ERC-721 tokens representing alphanumeric codes (1-32 characters)\n- **Flexible Registration Methods**: Direct registration via authorized registrars or gasless signature-based registration\n- **Revenue Attribution**: Each code has a configurable payout address for tracking and distributing revenue\n- **Role-Based Access Control**: Granular permissions for registration, transfers, and metadata updates\n- **Upgradeable Design**: UUPS proxy pattern enables future enhancements while preserving state\n- **Gas-Optimized**: Efficient storage layout using ERC-7201 and Solady libraries\n\n## Architecture\n\n### ERC-721 NFT\n\nBuilderCodes implements the ERC-721 standard where each token represents a unique builder code. The token ID is deterministically derived from the code string itself, ensuring a 1:1 mapping between codes and token IDs. The contract uses OpenZeppelin's upgradeable ERC-721 implementation as the base.\n\n### Access Control\n\nThe contract employs a **central registry with periphery registrars** architecture:\n\n- **Central Registry**: The BuilderCodes contract serves as the authoritative registry, storing all code ownership and payout mappings\n- **Periphery Registrars**: External contracts or EOAs granted `REGISTER_ROLE` can register codes on behalf of users\n- **Restricted Transfers**: Only addresses with `TRANSFER_ROLE` can initiate transfers, preventing unauthorized code transfers\n\n**Roles:**\n- `REGISTER_ROLE`: Authorize code registration (direct calls or signatures)\n- `TRANSFER_ROLE`: Authorize token transfers\n- `METADATA_ROLE`: Update token metadata URIs\n- **Owner**: Automatically has all roles via `hasRole()` override and can manage role grants\n\n### Upgradeability\n\nThe contract uses the **UUPS (Universal Upgradeable Proxy Standard)** pattern:\n\n- **Proxy Pattern**: ERC-1967 transparent proxy separates logic (implementation) from state (proxy)\n- **Storage Safety**: ERC-7201 namespaced storage prevents collisions during upgrades\n- **Owner-Only Upgrades**: Only the contract owner can authorize implementation upgrades via `_authorizeUpgrade()`\n\n## Code System\n\n### Valid Code Format\n\nBuilder codes must adhere to strict formatting rules:\n\n- **Length**: 1-32 characters\n- **Allowed Characters**: Lowercase letters (`a-z`), digits (`0-9`), and underscore (`_`)\n\n### Token ID Conversion\n\nThe contract provides `toCode()` and `toTokenId()` as pure functions that bidirectionally map between builder codes and token IDs. This deterministic 1:1 mapping is enabled by 7-bit ASCII encoding of the allowed character set.\n\n## Registration\n\n### Direct Registration\n\nThe `register()` function allows authorized registrars to mint codes:\n\n```solidity\nfunction register(\n    string memory code,\n    address initialOwner,\n    address initialPayoutAddress\n) external onlyRole(REGISTER_ROLE)\n```\n\n**Flow:**\n1. Caller must have `REGISTER_ROLE` (or be owner)\n2. Code is validated for format compliance\n3. Token is minted to `initialOwner`\n4. Payout address is set to `initialPayoutAddress`\n5. Events emitted: `Transfer`, `CodeRegistered`, `PayoutAddressUpdated`\n\n### Signature-Based Registration\n\nThe `registerWithSignature()` function enables gasless registration via EIP-712 signatures:\n\n```solidity\nfunction registerWithSignature(\n    string memory code,\n    address initialOwner,\n    address initialPayoutAddress,\n    uint48 deadline,\n    address signer,\n    bytes memory signature\n) external\n```\n\n**Flow:**\n1. Verify deadline has not passed\n2. Verify `signer` has `REGISTER_ROLE`\n3. Compute EIP-712 typed data hash for registration parameters\n4. Validate signature against signer's address\n5. Execute registration (same as direct registration)\n\n**EIP-712 Typed Data:**\n```\nBuilderCodeRegistration(\n    string code,\n    address initialOwner,\n    address payoutAddress,\n    uint48 deadline\n)\n```\n\nThis pattern allows users to obtain off-chain signatures from authorized registrars and submit registrations without the registrar paying gas.\n\n## Transfer Restrictions\n\nBuilderCodes implements a permission-gated transfer system to control how codes can be transferred between addresses.\n\n**How it works:**\n1. Transfers are only allowed if initiated by an address with `TRANSFER_ROLE`\n2. Holders of `TRANSFER_ROLE` cannot move tokens unilaterally—they still need approval from each owner to transfer tokens\n\nThis design enables intentional rollout of specific transfer patterns, such as controlled marketplaces or recovery mechanisms.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbase%2Fbuilder-codes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbase%2Fbuilder-codes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbase%2Fbuilder-codes/lists"}