diff --git a/XIPs/xip-0-purpose-process.md b/XIPs/xip-0-purpose-process.md index 7529c20..7c60f47 100644 --- a/XIPs/xip-0-purpose-process.md +++ b/XIPs/xip-0-purpose-process.md @@ -19,27 +19,33 @@ An XIP is a design document that provides information to the XMTP community abou - An improvement to XMTP processes or environment -"Environment" may refer to technical infrastructure, standards, software libraries, or network operations. +*Environment* may refer to technical infrastructure, standards, software libraries, or network operations. The XIP author and editor should ensure an XIP provides a concise technical specification and rationale for its proposed feature or improvement. -## The purpose of XIPs +## Purpose of XIPs -XIPs address the need for a standardized, transparent process for proposing, discussing, and integrating new features for XMTP. +XIPs address the need for a standardized, transparent process for proposing, discussing, and integrating new features for XMTP. -XIPs offer a structured proposal system that ensures comprehensive community participation and informed decision-making. +XIPs also offer a structured proposal system that enables permissionless community participation and informed decision-making. -The XIP repository, with its comprehensive revision history, serves as a source for technical exchange and an archival record of XMTP's evolution and the contributors who made it possible. +The XIPs GitHub repository, with its comprehensive revision history, serves as a source for technical exchange and an archival record of XMTP's evolution and the contributors who made it possible. -For XMTP implementers, XIPs are a convenient way to track the progress of their implementation. Ideally, each implementer will list the XIPs they have implemented, providing end users with the current status of a given implementation or library. +For XMTP implementers, XIPs are a convenient way to track the progress of their implementations. Ideally, each implementer will list the XIPs they have implemented, providing their users with the current status of a given implementation or library. ## XIP types -There are three major types of XIPs, along with more specific categories. +There are three types of XIPs: + +- Standards +- Process +- Informational ### Standards XIP -A **Standards** XIP describes any changes that affect most or all XMTP implementations or the interoperability of applications using XMTP. Within the **Standards** category, XIPs are further categorized as follows: +Describes any changes that affect most or all XMTP implementations or the interoperability of applications using XMTP. + +Within the **Standards** type, XIPs are further categorized as follows: - **Core**: Includes proposals for rules and behavior around message relay by nodes, node incentive strategies, and backward-incompatible changes that require a consensus fork @@ -53,41 +59,43 @@ A **Standards** XIP describes any changes that affect most or all XMTP implement ### Process XIP -A **Process** XIP describes a new process or changes to an existing process surrounding XMTP. These XIPs may propose an implementation but do not modify the XMTP codebase. +Describes a new process or changes to an existing XMTP process. These XIPs may propose an implementation but do not modify the XMTP codebase. They often require community consensus and are more than mere recommendations. However, unlike **Informational** XIPs, the community cannot ignore them. ### Informational XIP -An **Informational** XIP provides general guidelines or information to the XMTP community without proposing a new feature. +Provides general guidelines or information to the XMTP community without proposing a new feature. -These XIPs do not necessarily reflect an XMTP community consensus or recommendation, allowing users and implementors to disregard or heed their advice. +These XIPs do not necessarily reflect an XMTP community consensus or recommendation, allowing users and implementers to disregard or heed their advice. ## Start with an idea -Gathering feedback from the community before advancing your idea through the XIP process is essential. This early feedback helps validate your idea, assess its originality, and measure community interest. This preparatory step can save you time and effort by ensuring your idea is novel and has not been previously proposed or rejected. +Gathering feedback from the community before advancing an idea through the XIP process is essential. This early feedback helps validate an idea, assess its originality, and measure community interest. Feedback may also involve reviewing reference implementations or assessing whether the idea is too specific for broad adoption within the XMTP ecosystem. + +Starting with an idea also enables gauging whether the level of interest from the community is commensurate with the effort required to implement an idea. While the amount of discussion does not automatically qualify an idea, it can influence its progression beyond the initial stage. -Additional validation may involve reviewing reference implementations or assessing whether the idea is too specific for broad adoption within the XMTP ecosystem. It’s important to gauge whether the level of interest from the community is commensurate with the effort required to implement your idea. While the amount of discussion does not automatically qualify or disqualify an idea, it can influence its progression beyond the initial stage. +This preparatory step can help save time and effort by ensuring the idea is original, appropriate, and useful before entering the XIP process. -**To get started with your idea:** +**To get started with an idea:** -1. Post your idea as a new topic in the [Ideas & Improvements category](https://community.xmtp.org/c/development/ideas/54) in the XMTP Community Forums. +1. Post the idea as a new topic in the [Ideas & Improvements category](https://community.xmtp.org/c/development/ideas/54) in the XMTP Community Forums. -1. If you've built a prototype for your idea, share it in your post. A prototype can clarify your idea and foster discussion. +1. If there is a prototype for the idea, share it in the post. A prototype can clarify the idea and foster discussion. 1. Include a due date for feedback, typically allowing about two weeks, including two weekends, to ensure adequate response time. -1. Share your idea with the XMTP community, including developers, reviewers, and editors. Beyond posting to the XMTP Community Forums, consider sharing your idea across your networks on other platforms. +1. Share the idea with the XMTP community, including developers, reviewers, and editors. Beyond posting to the XMTP Community Forums, consider sharing the idea across networks on other platforms. -1. Request feedback that will enable you to validate, measure overall interest in, and assess the originality of your idea, potentially saving you time and effort. - -After you feel your idea has received enough feedback, create an XIP draft for it as described in the next section. A good standard for "enough feedback" is at least one comment from an XMTP community member and one from an XMTP Core Developer (currently the XMTP Labs team). +1. Request feedback that will enable validation of, measurement of interest in, and assessment of the originality of the idea, potentially saving time and effort. + +After the idea has received enough feedback expressing interest in the idea, create an XIP draft for it as described in the next section. A good standard for "enough feedback" is at least one comment from an XMTP community member and one from an XMTP core developer (currently the XMTP Labs team). ## Start the XIP process Following the validation of an idea, the author can present it as a formal XIP draft. The author is then responsible for shepherding it through the XIP process. -Each XIP should focus on a single key proposal or idea. A focused XIP is more likely to succeed. If in doubt, divide your XIP into multiple, well-focused XIPs. A change affecting only one client doesn’t need an XIP, but changes that affect multiple clients or establish a standard for multiple apps do. +Each XIP should focus on a single key proposal or idea. A focused XIP is more likely to succeed. If in doubt, divide the XIP into multiple, well-focused XIPs. A change affecting only one client doesn’t need an XIP, but changes that affect multiple clients or establish a standard for multiple apps do. An XIP must fulfill certain minimum criteria: @@ -97,103 +105,97 @@ An XIP must fulfill certain minimum criteria: - If the XIP includes an implementation, it must be solid and not unduly complicate the protocol. +### XIP template + +XIPs should be written in Markdown format using this [XIP template](/xip-template.md). + ### Draft status -This is the first formally tracked stage of an XIP. +This is the first formally tracked status of an XIP. -1. The XIP author uses the [XIP template](../xip-template.md) to create the XIP draft, adhering to the guidelines in this document. +1. The XIP author uses the [XIP template](../xip-template.md) to create the XIP draft, adhering to the guidelines in this document, and sets the XIP's **status** to `Draft`. - The draft filename should use this format `xip-short-title.md`, where `short-title` is a dash-separated shortened version of the XIP title. + The draft filename should use the format `xip-short-title.md`, where `short-title` is a dash-separated shortened version of the XIP title. -1. The XIP author opens a pull request in the **XIPs** directory of this repository. The pull request should include the proposal title. +1. The XIP author opens a pull request in the **XIPs** directory of this repository. The pull request title should include the proposal title. -1. The XIP author sets the XIP's **status** to `Draft` and tags the [XIP editors](#xip-editors-and-responsibilities) for review. +1. The XIP author tags the [XIP editors](#xip-editors-and-responsibilities) for review. -1. An XIP editor assigns an XIP number. This is generally the next sequential number, but the decision is up to the editor. +1. An XIP editor assigns the draft an XIP number. This is generally the next sequential number, but the decision is up to the editor. -1. The XIP editor adds the XIP number to the filename. When assigning an XIP number, the filename should use a format like `xip-n-short-title.md`, where `n` is the XIP number. +1. The XIP editor adds the XIP number to the draft filename. When assigning an XIP number, the filename should use the format `xip-n-short-title.md`, where `n` is the XIP number. They also perform the tasks in [XIP editors and responsibilities](/XIPs/xip-0-purpose-process.md#xip-editors-and-responsibilities). -1. The XIP editor creates an [XIP Draft](https://community.xmtp.org/c/xips/xip-drafts/53) forum topic that includes the XIP text (except the Preamble) and assigns ownership of the topic to the XIP author. +1. The XIP editor creates a topic using the XIP text (except the preamble) in the [XIP draft](https://community.xmtp.org/c/xips/xip-drafts/53) discussion forum and assigns ownership of the topic to the XIP author. -1. The XIP editor copies the forum topic URL and sets it as the **discussions-to** value in the XIP draft pull request. +1. The XIP editor copies the topic URL and sets it as the **discussions-to** value in the XIP draft pull request. -1. The XIP editor merges the corresponding pull request and sends a message to the XIP author with next steps. +1. The XIP editor merges the draft pull request and contacts the XIP author with next steps. -The XIP author uses the forum topic to gather feedback from the community and at least one XMTP Core Developer. The XIP author is responsible for building consensus and documenting dissenting opinions. +The XIP author uses the topic to gather feedback. The XIP author is responsible for building consensus and documenting dissenting opinions. -The XIP author may work with XIP editors to open pull requests against their merged XIP draft to update it to address feedback in preparation for the review phase. +The XIP author may update their XIP in preparation for the review phase. ### Review status -1. After the XIP in `Draft` status is accurate and complete to the best of the XIP author's knowledge, they open a pull request against the XIP to update the **status** to `Review` and tag the XIP editors. This status indicates that the XIP is ready for review by XMTP Core Developers. +1. After the XIP in `Draft` status is accurate and complete to the best of the XIP author's knowledge, they open a pull request against the draft XIP to update the **status** to `Review` and tag the XIP editors. This status indicates that the XIP content is ready for review with XMTP core developers. + +2. An XIP editor merges the pull request and the XIP review with XMTP core developers can start. During this phase, XMTP core developers perform a final validation of the XIP's technical approach and accuracy. -2. An XIP editor merges the pull request and starts the XIP review with XMTP Core Developers. During this phase, XMTP Core Developers perform a final validation of the XIP's technical approach and accuracy. XMTP Core Developers provide their feedback to the XIP author. +During this phase, the only changes made to the XIP are those coordinated between the XIP author and the XMTP core developers. ### Last call status -1. After addressing any necessary revisions and coming to a consensus that the XIP is sound and complete, the XMTP Core Developers contact the XIP author and XIP editors. +1. After addressing any necessary revisions and coming to a consensus that the XIP is sound and complete, the XMTP core developers notify the XIP author and editors. -1. An XIP editor sets the **status** to `Last call` and **last-call-deadline** to a review end date typically 14 days later. If normative changes are necessary during this period, the XIP reverts to `Review` status. +1. An XIP editor sets the **status** to `Last call` and the **last-call-deadline** preamble header to a review end date typically 14 days later. If normative changes are necessary during this phase, the XIP reverts to `Review` status. - Normative changes affect the standards, rules, or main functionality described in the XIP. These changes do not include typo fixes, example updates, text clarifications, or other alterations that don't change the technical specifications. + Normative changes are those that affect the standards, rules, or main functionality described in the XIP. These changes do not include typo fixes, example updates, text clarifications, or other alterations that don't change the technical specifications. ### Final status -If the XIP is an **Informational** or **Process** XIP, it automatically goes into **Final** status after the 14-day **Last call** period. +If no normative changes are necessary during the 14-day last call period, an XIP editor sets the XIP's **status** to `Final`. An XIP in **Final** status exists in this status permanently and can be updated only to correct errata and add non-normative clarifications. -If the XIP is a **Standards** XIP, it does not automatically go into **Final** status but requires adequate adoption specific to each XIP category, as follows: - -- **Core**: Core XIPs fundamentally affect the protocol and require widespread consensus to ensure network integrity and continuity. For a Core XIP to move into Final status, it should be adopted by at least 75% of the node operators and validated through a successful testnet phase lasting no less than 30 days. This ensures that the changes are robust, backward-compatible where necessary, and do not unduly disrupt the network. - -- **Network**: Network XIPs are critical for the communication and interoperability of nodes within the network. For a Network XIP to move into Final status, it should demonstrate successful implementation in a controlled environment (testnet) for a minimum period of 30 days. After this testing phase, it should be adopted by at least 60% of the nodes operating on the network, ensuring that the majority of the network's infrastructure supports the new standards or protocols. This wide adoption signifies a strong consensus within the community and solidifies the XIP's status as Final. - -- **Interface**: Interface XIPs enhance how clients interact with the network, affecting developers and end-users. For an Interface XIP to move into Final status, it should be adopted by a majority (over 50%) of client applications, as demonstrated by updates in their official release versions. Client feedback via community forums or surveys indicating positive reception and improved interaction experiences can also support this transition. - -- **Storage**: Storage XIPs deal with the persistence, accessibility, and security of messages. For a Storage XIP to move into Final status, it should be adopted by all major storage providers within the XMTP ecosystem, with no reported data loss or accessibility issues for a continuous period of 90 days. This ensures that the storage changes are practical, secure, and benefit the network without compromising data integrity. - -- **XRC** (XMTP Request for Comment): XRCs propose standards and conventions at the application level. For an XRC XIP to move into Final status, it should be adopted by over 60% of new projects or updates to existing applications within the XMTP ecosystem within three months of the XIP entering the Last Call phase. Additionally, a survey of developers and users indicating that the standards or conventions introduced have positively impacted development practices or user experiences would further validate the move to Final status. - ### Other special statuses - **Living**: This status applies to an XIP intended to be continually updated. Instead of moving to `Final` status, this XIP moves to `Living` status. Most notably, this includes XIP-0. -- **Stagnant**: This status applies to an XIP in `Draft`, `Review`, or `Last call` status without activity for over six months. An XIP editor will automatically set its status to `Stagnant`. The XIP author or XIP editor may resurrect the XIP from this state by changing its status back to `Draft` or its earlier status. If not resurrected, an XIP can stay in this status permanently. +- **Stagnant**: This status applies to an XIP in `Draft`, `Review`, or `Last call` status without activity for over six months. An XIP editor will automatically set its status to `Stagnant`. The XIP author or XIP editor may resurrect the XIP by changing its status back to `Draft` or its earlier status. If not resurrected, an XIP can stay in this status permanently. - **Withdrawn**: An XIP author can withdraw their XIP by setting its status to `Withdrawn`. This state is permanent. No one can resurrect the XIP using the same XIP number. If someone wants to pursue the XIP again, they must create a new proposal with a new XIP number. -## What belongs in an XIP? - -XIPs should be written in Markdown format using this [XIP template](/xip-template.md). - ## XIP header preamble -Each XIP must begin with an RFC 822-style header preamble, preceded and followed by three hyphens (---), as shown in the XIP template. +Each XIP must begin with an RFC 822-style header preamble, preceded and followed by three hyphens (`---`), as shown in the [XIP template](/xip-template.md). For headers that permit lists of items, separate items with commas. -For headers that require dates, use ISO 8601 format (YYYY-MM-DD). - -Headers must appear in the following order: - -### xip - -An XIP author should not provide this value. An XIP editor will assign the XIP number. - -### title - -A short descriptive title, limited to 44 characters. It should not include the XIP number. - -### description +For headers that require dates, use the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format `YYYY-MM-DD`. For example: `2024-02-29`. -A description of the XIP, limited to 140 characters. It should not include the XIP number. +Headers must appear in the following order in the preamble: -### author +| Header | Description | +|-------------|--------------| +| xip | An XIP editor will assign the XIP number. An XIP author should not provide this value. | +| title | Provide a short descriptive title for the XIP, limited to 44 characters. It should not include the XIP number. | +| description | Provide a description of the XIP, limited to 140 characters. It should not include the XIP number.| +| author | List the XIP author names and their email addresses, GitHub usernames, or ENS domains. For more requirements, see [author details](#author-details). | +| discussions-to | While the XIP is in `Draft` status, provide a **discussions-to** header and set the value to the URL where the XIP is being discussed. The preferred URL is a topic in the [XIP Drafts](https://community.xmtp.org/c/xips/xip-drafts/53) discussion forum. The URL must not point to a GitHub pull request, an ephemeral URL, or a lockable URL, such as a Reddit topic. | +| status | Provide the XIP status: `Draft`, `Review`, `Last call`, `Final`, `Stagnant`, `Withdrawn`, or `Living`. To learn more, see [Start the XIP process](#start-the-xip-process). | +| last-call-deadline | While the XIP is in `Last call` status, provide a **last-call-deadline** header and set the value to the date the last call review period ends in `YYYY-MM-DD` format. | +| type | Provide the XIP type: `Standards`, `Process`, or `Informational`. To learn more, see [XIP types](#xip-types). | +| category | If it is a `Standards` XIP, provide the XIP category: `Core`, `Network`, `Interface`, `Storage`, or `XRC`. To learn more, see [XIP types](#xip-types). | +| created | Provide the date an XIP editor assigned a number to the XIP, in `YYYY-MM-DD` format. | +| replaced | If the XIP replaces an XIP, provide the **replaced** header and set its value to a link to the XIP it replaces. | +| required | If the XIP depends on an XIP, provide the **required** header and set its value to a link to the XIP it depends on. | +| superseded-by | If the XIP is superseded by an XIP, provide the **superseded-by** header and set its value to a link to the XIP that supersedes it. | +| updated | If the XIP is in `Living` status and has been updated after its **created** date, provide the **updated** header and set its value to the date the XIP was last updated in `YYYY-MM-DD` format. | +| withdrawal-reason | If the XIP is in `Withdrawn` status, provide the **withdrawal-reason** header and set its value to a sentence that explains why the XIP was withdrawn. | -List the names and email addresses, GitHub usernames, or ENS domains of the XIP authors. Authors who prefer anonymity may use a GitHub username only or a first name and GitHub username. +### author details -To include an email address, GitHub username, or ENS domain, you must use one of these formats: +For the **author** header, to include an email address, GitHub username, or ENS domain along with the author name, use one of these formats: - Alix A. User <alixauser@example.com> @@ -201,65 +203,21 @@ To include an email address, GitHub username, or ENS domain, you must use one of - Caro C. User (carocuser.eth) -Do not use more than one of the following with a single author value: email address, GitHub username, or ENS domain. - -If it is important to include more than one, include the author value twice, once with the email and once with the GitHub username, for example. - -At least one author must use a GitHub username to enable notifications for change requests and the ability to approve or reject them. - -### discussions-to - -While an XIP is in `Draft` status, a **discussions-to** header indicates the URL where the XIP is being discussed. - -The preferred discussion URL is a topic in the XIP Drafts forum. The URL must not point to GitHub pull requests, any URL that is ephemeral, or any URL that can be locked over time, such as a Reddit topic. - -### status - -The status of the XIP: `Draft`, `Review`, `Last call`, `Final`, `Stagnant`, `Withdrawn`, or `Living`. To learn more, see [Start the XIP process](#start-the-xip-process). - -### last-call-deadline - -XIPs in `Last call` status should have a **last-call-deadline** header. The **last-call-deadline** header records the date that the last-call review period ends. The header should be in `YYYY-MM-DD` format, e.g. `2009-01-12`. - -### type - -The **type** header specifies the XIP's type: `Standards`, `Process`, or `Informational`. To learn more, see [XIP types](#xip-types). - -### category - -This is required for `Standards` XIPs only. It specifies the XIP's category: `Core`, `Network`, `Interface`, `Storage`, or `XRC`. To learn more, see [XIP types](#xip-types). - -### created - -The **created** header records the date the XIP was assigned a number. It should be in `YYYY-MM-DD` format, e.g. `2009-01-12`. - -### replaces - -XIPs may have a **replaces** header, indicating that the XIP replaces the designated XIP number. - -### requires - -XIPs may have a **requires** header, indicating the XIP numbers that this XIP depends on. - -### superceded-by - -XIPs may have a **superceded-by** header, indicating that the XIP is superceded, or replaced by, the designated XIP number. - -### updated +Do not use more than one of the following contact methods with a single author name: email address, GitHub username, or ENS domain. -XIPs in `Living` status should have an updated header. It records the date the XIP was updated and should be in `YYYY-MM-DD` format, e.g. `2009-01-12`. +If it is important to include more than one method, list the author's name twice, once with the email and once with the GitHub username, for example. -### withdrawal-reason +Authors who prefer anonymity may use only a GitHub username or a first name and GitHub username. -XIPs in `Withdrawn` status should have a **withdrawal-reason**, which is a sentence that explains why the XIP was withdrawn. +t least one author must use a GitHub username to enable notifications and approvals for change requests. -## XIP numbers and linking to other XIPs +## XIP numbers and XIP links When referring to an XIP by number, write it in hyphenated form `XIP-N`, where `N` is the XIP's assigned number. -Links to other XIPs should follow the format `XIP-N` where `N` is the XIP number you refer to. An XIP referenced in an XIP **MUST** be accompanied by a relative link upon its first reference. A link upon subsequent references MAY accompany it. +An XIP referenced in an XIP must link to the XIP upon its first reference. Subsequent references may include the link. -Links MUST always use relative paths so that the links work in this GitHub repository, forks of this repository, the main XIPs site, mirrors of the main XIP site, and so forth. For example, you would link to this XIP with `[XIP-0](./XIPs/xip-0-purpose-process.md))`. +Links to XIPs must use relative paths to enable links to work in this GitHub repository, forks of this repository, the main XIPs site, mirrors of the main XIP site, and so forth. For example, when referencing this XIP in an XIP, use a relative link like this: `[XIP-0](./XIPs/xip-0-purpose-process.md)`. ## Auxiliary files @@ -271,9 +229,9 @@ Occasionally, transferring ownership of XIPs to a new champion is necessary. A good reason to transfer ownership is that the original author no longer has the time or interest to update the XIP or follow through with the XIP process. It may also be that the author has fallen off the face of the ‘net (i.e., is unreachable or isn’t responding to email). -A bad reason to transfer ownership is because you don’t agree with the direction of the XIP. We try to build consensus around an XIP, but if that’s not possible, you can always submit a competing XIP. +A bad reason to transfer ownership is because of a disagreement with the direction the XIP has taken. The process is designed to build consensus around an XIP, but if that’s not possible, submitting a competing XIP is always an option. -If you want to assume ownership of an XIP, send a message to the original author and the XIP editor asking to take over. If the original author doesn’t respond to the email in a timely manner, the XIP editor will make a unilateral decision. +To assume ownership of an XIP, send a message to the original author and the XIP editor asking to take it over. If the original author doesn’t respond to the email in a timely manner, the XIP editor will make a unilateral decision. Retaining the original author as a co-author of the transferred XIP is ideal, but that’s up to the original author. @@ -289,17 +247,17 @@ The editors don't pass judgment on XIPs. They merely perform administrative and For each new XIP proposal submitted as a pull request, an editor does the following: -- Reads the XIP to check if it is sound and complete. The proposal must make technical sense, even if it doesn't seem likely to get to final status. +- Reads the XIP to check if it is sound and complete. The proposal must make technical sense. - Ensures that the title accurately describes the content. - Checks the XIP for correct spelling, grammar, sentence structure, markup (GitHub-flavored Markdown), and code style. -If the XIP isn't ready, the editor sends it back to the author for revision with specific instructions. +- Provides specific feedback to the XIP author to help them prepare their XIP for review. To learn more about XIP editor tasks, see [Start the XIP process](#start-the-xip-process). -Many XIPs are written and maintained by developers with write access to the **xmtp** GitHub organization codebase. The XIP editors monitor XIP changes and may correct any structural, grammatical, spelling, and markup mistakes. +Many XIPs are written and maintained by developers with write access to the **xmtp** GitHub organization codebase. The XIP editors monitor XIP changes and may regularly correct any structural, grammatical, spelling, and markup mistakes. ## History diff --git a/XIPs/xip-42-universal-allow-block-preferences.md b/XIPs/xip-42-universal-allow-block-preferences.md new file mode 100644 index 0000000..ae6b26c --- /dev/null +++ b/XIPs/xip-42-universal-allow-block-preferences.md @@ -0,0 +1,74 @@ +--- +xip: 42 +title: Universal 'allow' and 'block' preferences +description: +author: Saul Carlin (@saulmc), Nick Molnar (@neekolas), Naomi Plasterer (@nplasterer), Ry Racherbaumer (@rygine) +discussions-to: +status: Draft +type: Standards +category: XRC +created: 2024-02-14 +--- + +## Abstract + +This XIP establishes 'allow' and 'block' permission preferences, enabling users to explicitly specify which contacts should be able to reach them and which should be blocked across all inbox apps. By respecting these preferences, XMTP inbox apps not only shield users from spam but also give them greater control over their contacts. + +*Special thanks to @polmaire for [initiating the discussion](https://github.com/xmtp/XIPs/pull/28/files) that inspired this XIP.* + +## Motivation + +The ability to 'allow' or 'block' contacts is fundamental for safeguarding users' inboxes in messaging. 'Allow' promotes a conversation from a 'request' or 'invitations' UI component to a 'primary inbox' component, while 'Block' gives users the vital ability to remove spam and other unwanted content from their inbox. + +Because XMTP hasn't yet standardized a method for communicating these actions across the network, changing preferences in one app does not affect other inboxes. This results in inbox apps failing to remove unwanted conversations and properly displaying desired communications. + +## Specification + +In code we use `consent` to abbreviate "contact permission preferences", and `denied` as the inverse of `allowed`. + +- **New Message Topic**: `userpreferences-${identifier}` for encrypted `ConsentList` objects (`type: 'allowed' | 'denied', addresses: [string]`). +- **ConsentState Type**: Introduce `ConsentState = 'allowed' | 'denied' | 'unknown'`. +- **Conversation Field**: Add `consentState` to indicate the consent state of a conversation. +- **APIs**: Introduce APIs for retrieving and managing permission preference lists and states. + +## Rationale + +This approach will enable apps to accurately reflect users' contact permission preferences by default, thereby shielding them from spam and granting them more ownership and control over their communications. + +## Backward Compatibility + +Apps must adhere to the logic described below to keep the contact permission preferences on the network synchronized with local app's user preferences, and vice versa. + +Update a contact permission preference in the `ConsentList` on the network in the following scenarios only: + +- A user explicitly denies a contact. For example, the user blocks, unsubscribes from, or otherwise disables messages for the contact. The app should update the corresponding preference in the network to `denied`. +- A user explicitly allows a contact. For example, the user allows, subscribes to, or otherwise enables messages for the contact. The app should update the corresponding preference in the network to `allowed`. +- An existing conversation has an `unknown` contact permission preference, but a legacy permission in the local database exists. The app should update the corresponding preference in the network to match the legacy local preference. +- An existing conversation has an `unknown` contact permission preference, but has an existing response from the user. The app should update the corresponding preference in the network to `allowed`. + +## Test Cases + +Test cases will validate the functionality of sending messages using the new message topic and the handling and interpretation of all three permission preferences. + +## Reference Implementation + +The [reference implementation](https://github.com/xmtp-labs/xmtp-inbox-web/pull/422) in the [XMTP reference client](https://xmtp.chat) demonstrates the integration of contact permission preferences, along with usable code snippets and UI components for allowing and blocking contacts. + +## Security Considerations + +The `identifier` in the topic is derived from the private key using HKDF and SHA256 to ensure that it cannot be linked back to the user. + +### Message Envelope Encryption + +1. Generates a new key via HKDF from the user's identity key. +2. Encrypts the message via AES-256-GCM using the derived encryption key and the user's public key as associated data. Then converts it to a `PrivatePreferencesPayload` protobuf containing the ciphertext, nonce, and salt. + +### Message Envelope Decryption + +1. Decodes the `PrivatePreferencesPayload`. +2. Derives the encryption key via HKDF from the user's identity key. +3. Decrypts the contents via AES-256-GCM using the public key as associated data. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/XIPs/xip-43-permission-pref-proofs.md b/XIPs/xip-43-permission-pref-proofs.md new file mode 100644 index 0000000..1693b98 --- /dev/null +++ b/XIPs/xip-43-permission-pref-proofs.md @@ -0,0 +1,91 @@ +--- +title: Permission preference proofs +description: Enables recipients to sign to specify inbox permission preferences +author: @rygine @neekolas @saulmc +discussions-to: https://community.xmtp.org/t/xip-43-permission-preference-proofs/552 +status: Draft +type: Standards +category: Interface +created: 2024-02-22 +--- + +## Abstract + +This XIP proposes to add an _optional_ signed payload to conversations that client apps can consider as proof that a recipient has granted a sender permission to reach their main inbox. + +## Motivation + +Today, a recipient must use a full XMTP client to set a universal permission preference such as allowing a sender. This presents challenges to senders due to the XMTP client's bundle size and integration requirements. For integrations such as simple subscribe buttons, these hurdles can be blockers. + +To solve these issues, senders can simply ask users to produce a signature attesting to the permission preference update. Inbox apps can consider this signature as proof that the recipient has explicitly opted in to receive the sender's messages. This eliminates the bundle size problem, as very little code is required to initiate signing a message with a user's wallet. It also greatly simplifies integration by providing a single function to obtain the user’s signature and return an encoded payload to be used by SDKs to verify the granted permission. + +## Specification + +There are 3 components to the proposed workflow: + +1. Obtain a permission signature from the user + _Requires actions by the **sender** and **receiver**_ +2. Create a new conversation with the encoded payload + _Requires actions by the **sender**_ +3. Verify the permission payload to allow the sender + _Requires actions by the **client SDK**_ + +### Obtain a permission signature from the user + +A permission signature must be obtained from a user's wallet, which is then encoded into a payload that can be used by client SDKs to verify and validate opt-in before allowing the sender. + +The decoded payload that must be collected by senders will be defined in a protobuf as follows: + +```protobuf +message PermissionPayload { + // the user's signature in hex format + string signature = 1; + // approximate time when the user signed + uint64 timestamp = 2; + // version of the payload + uint32 payload_version = 3; +} +``` + +The message that will be signed by the user's wallet will contain the sender's address and a timestamp. It must include a human-readable explanation, such as follows. + +```text +XMTP : Grant inbox permission to sender + +Current Time: +From Address: + +For more info: https://xmtp.org/signatures/ +``` + +A light-weight JavaScript bundle will provide a function that will initiate the signing process and return an encoded payload that senders must store on their end. This function is intended to be used as a callback to a click event, such as clicking on a Subscribe button. + +### Create a new conversation with the encoded payload + +Once senders have the encoded payload, they can include it when starting a new conversation with a user. + +An example of what this might look like: + +```ts +const conversation = await client.conversations.newConversation(peerAddress, context, permissionPayload); +``` + +Users who have created a permission signature may not have an identity on the XMTP network. Senders should check for an identity with `Client.canMessage` prior to starting a new conversation. If a user does not yet have an XMTP identity, the sender can routinely check for a network identity and start a conversation when it's found. + +### Verify the permission payload + +In order to finalize the permission preference, SDKs must look for the permission payload in new conversations. Using this payload, SDKs can verify that the current user's wallet signed the permission message and validate that the addresses and timestamp match the expected values. + +Once the permission payload is verified and validated, the SDKs will then update network permission preferences automatically. + +## Backward Compatibility + +The encoded permission payload is an _optional_ parameter when starting a new conversation. Existing conversations will not be affected, and client apps using outdated SDKs will continue to work without updates. + +## Security Considerations + +There are no known negative security implications introduced as a result of collecting a signature from a user and including it as part of a conversation. The contents of the message being signed will be shown to the user beforehand, and the resulting signature is only useful to SDKs connected to the wallet that signed the message. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/xip-template.md b/xip-template.md index 84b7b16..63e54f9 100644 --- a/xip-template.md +++ b/xip-template.md @@ -1,53 +1,58 @@ --- -title: The XIP title is a few words, not a complete sentence -description: Description is one full (short) sentence -author: The list of the author's name(s) and username(s), or name(s) and email(s). -discussions-to: The url pointing to the official discussion thread +xip: Do not include. The XIP number will be assigned by an XIP editor. +title: Short descriptive title for the XIP, limited to 44 characters. Do not include the XIP number. +description: Description of the XIP, limited to 140 characters. Do not include the XIP number. +author: List each author's name and their GitHub username, email, or ENS domain. +discussions-to: URL where the XIP draft will be discussed. status: Draft -type: One of Standards Track, Process, or Informational -category: One of Core, Network, Interface, Storage, or XRC (Optional field, only needed for Standards Track XIPs) -created: YYYY-MM-DD Date the XIP was created on (ISO 8601 format) +type: Standards, Process, or Informational. +category: If **type** is `Standards`, select Core, Network, Interface, Storage, or XRC. +created: YYYY-MM-DD --- -This is the suggested template for new XIP. +Use this template and the guidance in [XIP-0: XIP purpose, process, and guidelines](XIPs/xip-0-purpose-process.md) to create an XIP and help it progress efficiently through the review process. -Note that an XIP number will be assigned by an editor. When opening a pull request to submit your XIP, please use an abbreviated title in the filename, `xip-draft-title-abbrev.md`. +## Abstract -The title should be 44 characters or less. It should not repeat the XIP number in title, irrespective of the category. +The abstract is a short paragraph that provides a human-readable version of the specification section. A person should be able to read the abstract and get the gist of what the specification does. -## Abstract +## Motivation* -Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does. +The motivation is critical for XIPs that want to change the XMTP protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem the XIP aims to solve. -## Motivation +The motivation should describe the "why" of the XIP. What problem does it solve? Why should someone want to implement it? What benefit does it provide to the XTMP ecosystem? What use cases does it address? -The motivation section should describe the "why" of this XIP. What problem does it solve? Why should someone want to implement this standard? What benefit does it provide to the XTMP ecosystem? What use cases does this XIP address? +XIP submissions without sufficient motivation may be rejected outright. *This section may be omitted if the motivation is evident. ## Specification -The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). +The specification should describe the technical syntax and semantics of any new feature. The specification should be detailed enough to enable competing and interoperable implementations for any current XMTP platform. -The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current XMTP platforms. +Follow RFC 2119 for terminology and start the specification section with this paragraph: + +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ## Rationale -The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. +The rationale fleshes out the specification by describing what motivated the design and particular design decisions. The rationale should describe alternate designs that were considered and related work, such as how the feature supports other languages. The rationale may also provide evidence of consensus within the community and should share important objections or concerns raised during those discussions. + +## Backward compatibility -## Backwards Compatibility +All XIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The XIP must explain how the author proposes to deal with these incompatibilities. XIP submissions without a sufficient backward compatibility treatise may be rejected outright. -All XIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The XIP must explain how the author proposes to deal with these incompatibilities. XIP submissions without a sufficient backwards compatibility treatise may be rejected outright. +## Test cases -## Test Cases +Test cases for an implementation are mandatory for XIPs that affect consensus changes. Include tests inline in the XIP as data, such as input/expected output pairs. If the test suite is too large to reasonably include inline, consider adding it as one or more files in `../assets/xip-n/`, where `n` is to be replaced with the XIP number. -Test cases for an implementation are mandatory for XIPs that are affecting consensus changes. If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/xip-####/`. +## Reference implementation* -## Reference Implementation +A reference/example implementation that people can use to assist in understanding or implementing this specification. If the implementation is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/xip-n/`, where `n` is to be replaced with the XIP number. *This section is optional. -An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. If the implementation is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/xip-####/`. +## Security considerations -## Security Considerations +The security considerations include design decisions, concerns, and implementation-specific guidance and pitfalls that might be important to security discussions about the proposed change. It surfaces threats and risks and how they are being addressed. The information should be useful throughout the proposal's lifecycle. -All XIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. XIP submissions missing the "Security Considerations" section will be rejected. An XIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers. +An XIP cannot proceed to Final status without a discussion of security considerations deemed sufficient by the XIP reviewers. XIP submissions missing security considerations will be rejected outright. ## Copyright