diff --git a/assets/offchain/address-records.webp b/assets/offchain/address-records.webp new file mode 100644 index 0000000..7fbc35a Binary files /dev/null and b/assets/offchain/address-records.webp differ diff --git a/assets/offchain/api-key-scope.webp b/assets/offchain/api-key-scope.webp new file mode 100644 index 0000000..90b1aa5 Binary files /dev/null and b/assets/offchain/api-key-scope.webp differ diff --git a/assets/offchain/api-keys.webp b/assets/offchain/api-keys.webp new file mode 100644 index 0000000..b242eab Binary files /dev/null and b/assets/offchain/api-keys.webp differ diff --git a/assets/offchain/create-subname.webp b/assets/offchain/create-subname.webp new file mode 100644 index 0000000..109ff65 Binary files /dev/null and b/assets/offchain/create-subname.webp differ diff --git a/assets/offchain/resolver-configured.webp b/assets/offchain/resolver-configured.webp new file mode 100644 index 0000000..dda506d Binary files /dev/null and b/assets/offchain/resolver-configured.webp differ diff --git a/assets/offchain/subnames.webp b/assets/offchain/subnames.webp new file mode 100644 index 0000000..f7b9c8a Binary files /dev/null and b/assets/offchain/subnames.webp differ diff --git a/assets/offchain/update-resolver.webp b/assets/offchain/update-resolver.webp new file mode 100644 index 0000000..d1b6d51 Binary files /dev/null and b/assets/offchain/update-resolver.webp differ diff --git a/developer-guide/architecture/onchain-subnames.mdx b/developer-guide/architecture/onchain-subnames.mdx deleted file mode 100644 index efda366..0000000 --- a/developer-guide/architecture/onchain-subnames.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Onchain subname architecture" -description: "How Namespace issues onchain subnames on Ethereum and L2 chains." -sidebarTitle: "Onchain architecture" ---- - -The Namespace App lets ENS name owners activate a parent name and configure how other users can mint its subnames. Configuration options include: - -- Base and custom pricing -- Reserved subnames -- Whitelists -- Token-gated access -- Deadline - -Namespace supports issuing onchain subnames on **Ethereum mainnet** and **L2 chains (currently Base and Optimism)**. - -## ENS name activation - -The activation process differs depending on whether the ENS name owner chooses to issue subnames on Ethereum or an L2 chain. - -### Activation on Ethereum - -Activating subnames on Ethereum involves **four main steps**: - -1. **Create Activation Configuration:** The List Manager backend generates the activation configuration for the subname. -2. **Approve Mint Controller:** The owner grants approval to the Mint Controller smart contract. This is a **one-time approval** and does not need to be repeated for future names. -3. **Wrap the Name:** If the parent name is not yet wrapped, it must be wrapped before activation can proceed. -4. **Verify Activation:** The backend validates that all onchain steps (approval and wrapping) have been executed correctly. - -Ethereum activation flow from configuration through approval, wrapping, and verification - -### Activation on L2 chains - -Activating subnames on an L2 chain follows **four key steps**: - -1. **Create activation configuration:** The List Manager backend generates the rules for the subname minting flow. -2. **Deploy ERC-721 Registry:** An ERC-721 registry contract is deployed on the chosen L2 chain to manage ownership of subnames. -3. **Configure Resolver:** A resolver supporting **ENSIP-10 wildcard resolution** is set and configured to enable flexible, scalable name resolution. -4. **Verify Activation:** The backend validates that all onchain steps (registry deployment and resolver setup) have been completed correctly. - -L2 chain activation flow from configuration through registry deployment, resolver setup, and verification - -## Minting process - -Mint preparation happens offchain, while ownership changes happen in an onchain transaction. The minter requests signed parameters from the Mint Manager service and uses them to call the configured mint contract on Ethereum or the listing's L2 chain. - -- **Flexible listing rules:** The service can evaluate reservations, allowlists, token requirements, deadlines, and pricing before signing parameters. -- **Configuration updates:** Listing rules can change without redeploying the mint contract, subject to the activated name's onchain configuration. -- **Onchain verification:** The mint contract validates the signed parameters when the user submits the transaction. - -Mint flow from eligibility request through signed parameters and the onchain transaction - -## Resolution process - -### Resolution on Ethereum - -Since onchain subnames on Ethereum are part of the existing ENS contracts on mainnet, they resolve just like any other ENS name: - -1. **Fetch Resolver:** Call `getResolver` on the ENS Registry to retrieve the resolver contract for `namehash(name.eth)`. -2. **Resolve Records:** Call the required resolver function (`addr`, `text`, `contenthash`, etc.) on the resolver contract. - -### Resolution on L2 chains - -Resolution on L2 chains relies on [CCIP Read](https://eips.ethereum.org/EIPS/eip-3668) with [ENSIP-10 wildcard resolution](https://docs.ens.domains/ensip/10/). -ENSIP-10 defines a workflow that allows resolving subnames of a parent name, even if those subnames don’t technically exist on Ethereum. - -The process works as follows: - -1. **Query ENS Registry:** The client queries the ENS Registry contract for the resolver address of the subname. -2. **Fallback to Parent:** If the resolver address is the zero address, the client strips the leftmost label and queries the Registry again for the parent name’s resolver. -3. **Call Resolve:** Once a resolver is found, the client calls `resolve(name, data)`, where: - - `name` is the DNS-encoded subname. - - `data` is the encoded resolver function call. -4. **Offchain Lookup Trigger:** The resolver reverts with an `OffchainLookup` error (per [EIP-3668, CCIP-Read]), providing: - - One or more URLs to query off-chain. - - The call data required for resolution. - - The address of the resolver contract to callback. -5. **Offchain Data Fetch:** The client performs an HTTPS request to the specified resolution gateway server. -6. **Response Returned:** The server processes the request offchain and returns signed resolution data with a callback function. -7. **Callback Onchain:** The client submits the signed response back to the resolver contract via the designated callback function. -8. **Final Resolution:** The resolver verifies the signature and returns the final resolved record (e.g., `addr`, `text`, or `contenthash`). - -## Next steps - - - - Generate mint transaction parameters for onchain subname issuance on Ethereum or L2 chains. - - - Issue gasless subnames and manage their records offchain. - - - Create and query your first subname with TypeScript. - - diff --git a/docs.json b/docs.json index 57e903c..b50817c 100644 --- a/docs.json +++ b/docs.json @@ -510,7 +510,7 @@ }, { "source": "/dev-docs/infrastructure/namespace-l2-subnames", - "destination": "/developer-guide/architecture/onchain-subnames" + "destination": "/overview/subnames" }, { "source": "/dev-docs/subpages", @@ -550,7 +550,7 @@ }, { "source": "/overview/namespace-onchain-subnames", - "destination": "/developer-guide/architecture/onchain-subnames" + "destination": "/overview/subnames" }, { "source": "/overview/integration/waas", @@ -662,7 +662,11 @@ }, { "source": "/overview/namespace-l2-subname-infrastructure", - "destination": "/developer-guide/architecture/onchain-subnames" + "destination": "/overview/subnames" + }, + { + "source": "/developer-guide/architecture/onchain-subnames", + "destination": "/overview/subnames" }, { "source": "/how-to/guide", diff --git a/user-guide/dev-portal.mdx b/user-guide/dev-portal.mdx index a36759b..9bf8496 100644 --- a/user-guide/dev-portal.mdx +++ b/user-guide/dev-portal.mdx @@ -1,106 +1,133 @@ --- title: "Offchain subnames" -description: "No-code offchain subnames, records, and API keys." +description: "Create and manage offchain ENS subnames in the Namespace App." sidebarTitle: "Offchain subnames" icon: "cloud" --- -Use the [Offchain section of the Namespace App](https://app.namespace.ninja/offchain) to create and manage gasless ENS subnames through the interface, Offchain Manager SDK, or API. +Create ENS subnames under a name you own in the [Namespace App](https://app.namespace.ninja/offchain). Namespace stores these subnames and their records offchain. They are not minted as onchain NFTs. ENS clients resolve their records through CCIP Read. -Offchain subnames are application-managed records resolved through CCIP Read. They are not minted as NFTs and do not require a blockchain transaction for each creation or update. +Creating, editing, and deleting offchain subnames and their records is free. These actions require no blockchain transactions or gas fees. ## What you can do -- Configure a parent ENS name to use the Namespace Hybrid Resolver. -- Create, update, and delete offchain subnames without code. -- Manage address, text, and content hash records. -- Generate API keys for server-side SDK or API integrations. +- Create, edit, and delete subnames under your ENS name. +- Set EVM and non-EVM addresses, profile and social text records, and a content hash. +- Index subnames by their optional owner address. +- Manage subnames in the app or automate through the SDK and API. -![Offchain section of the Namespace App with subname and configuration tools](/assets/dev-app.png) - -## Before you begin - -- Connect the wallet that owns the parent ENS name. -- Select the parent name you want to configure. -- Use a CCIP Read-compatible ENS client when testing resolution. +![Namespace Developer Portal introduction with subname, record, and API-key management tools](/assets/dev-app.png) ## Configure the resolver -The parent name must use the Namespace Hybrid Resolver before compatible ENS clients can resolve its offchain subnames. +Set the parent ENS name to use the Namespace Hybrid Resolver. This initial setup requires an onchain transaction and gas fees. Skip this section if resolution is already configured. - - Visit [app.namespace.ninja/offchain](https://app.namespace.ninja/offchain), connect the owner wallet, and select the parent ENS name. + + Connect the wallet that owns the ENS name. In **Offchain**, select the name and open **Resolution**. - Find the resolver configuration, click **Update**, and confirm the transaction in your wallet. The app points the parent name to the Namespace Hybrid Resolver. + Click **Update resolver** and confirm in your wallet. Skip this step if it shows **Updated**. - Resolver configuration with the Update button in the Namespace App + + Resolution tab with Update resolver and Configure buttons for the selected parent name + - - After the transaction confirms, create a test subname and verify that its records resolve in a CCIP Read-compatible client. + + Click **Configure** and complete the wallet prompts. Check that the status reads **Configured**. + + + Resolution setup completed with Updated and Configured statuses + ## Create and manage subnames - - Select the configured parent ENS name, then open **Subnames** to view its issued names. + + Select the parent name in **Subnames**, then click **Mint subname**. - Subnames tab for a selected parent ENS name + + Subnames tab with a parent ENS name selected and the Mint subname button + - Enter the label you want to issue and add the required ENS records. You can store EVM and non-EVM addresses, text records, and a content hash. + Enter a label, such as `happy`, and check availability. + + **Owner Address** is optional and can be used for indexing subnames by owner. + + Add records through **Complete your profile**, or add them later. Click **Create**. + + + Create subname dialog with an available label, optional owner address, Complete your profile, and Create button + - - Save the subname, then use its record controls to update or remove data later. Offchain updates do not require a blockchain transaction. - - - - Text record editor for an offchain subname - - - Address record editor for an offchain subname - - + + Click the subname's pencil icon. Edit its address, text, or content hash records, then click **Save**. + + + Addresses editor with Ethereum and Base records, additional chain options, and the Save button + +To delete a subname, click its trash icon. + ## Create an API key -You need an API key only when creating or managing offchain subnames from server-side SDK or API code. Keep the key out of client-side code and public repositories. +API keys are required for SDK and API access, not for using the app. - - Open the API Keys tab in the Namespace App. + + Open API Keys in the Namespace App. -Choose the key scope that matches your integration: + + + Select the parent name, open **API Keys**, and click **Create new key**. -| Key type | Scope | Best for | -| --- | --- | --- | -| Address-based | Every ENS name owned by one wallet | Managing several parent names with one integration | -| Domain-based | One parent ENS name | Separating environments or delegating access to one name | + + API Keys tab with the Create new key button and a reminder to save keys securely + + + + + Enter a key name, set an expiry date, and choose a scope: + + | Scope | Access | Best used for | + | --- | --- | --- | + | Address based | All ENS names owned by the connected wallet | Managing multiple parent names | + | Domain based | Only the selected parent name | Restricting an integration to one parent name | + + Email is optional. Click **Create**. -Set an expiry date when you create the key. You can revoke or replace keys from the same screen. + + Complete API key screen with key name, expiry, scope options, optional email field, and Create and Cancel buttons + + + + + Store the key in a server-side environment variable or secret store. Never expose it in browser code or public repositories. -![API key generation options in the Namespace App](/assets/api-keys.png) + Copy it before it disappears from the browser after about 24 hours. The key remains valid until its expiry date or revocation. + + - New accounts have an issuance limit of **2,000 offchain subnames**. Contact Namespace through the [Builders group on Telegram](https://t.me/+5FAwyiKOTeswNTIy) before launch if your integration needs a different limit. + Limit: 2,000 subnames per parent name. For a higher limit, contact the [Builders group](https://t.me/+5FAwyiKOTeswNTIy). ## Next steps - Create a subname, attach records, and query it with the Offchain Manager SDK. + Create and query subnames with the SDK. - Diagnose resolver, API key, record, and client compatibility problems. + Fix name and record lookup failures.