From eb2be624b3fbcb8bc12a36edf17a26bd459aeba9 Mon Sep 17 00:00:00 2001 From: smilingkylan Date: Mon, 27 Oct 2025 13:41:08 -0700 Subject: [PATCH 1/7] Propose SIP-34 onActivityItem handler / hook --- SIPS/sip-34.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 SIPS/sip-34.md diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md new file mode 100644 index 0000000..e904f7b --- /dev/null +++ b/SIPS/sip-34.md @@ -0,0 +1,92 @@ +--- +sip: 34 +title: History Item Insights +status: Draft +author: Kylan Hurt (@smilingkylan, kylan.hurt@gmail.com) +created: 2025-10-26 +--- + +## Abstract + +The purpose of this SIP is to propose the addition of an lifecycle hook, similar to the `onTransaction` and `onSignature` hooks that triggers when the user clicks on a history item (typically a transaction), passing with it parameters related to the transaction. I am giving this hook the name `onHistoryItem`. + +## Motivation + +Some web functionality works best when triggered after a financial transaction has occurred. In Web2 some examples may be satisfaction surveys after an online order, an email encouraging users to sign up for a newsletter, or consider purchasing another product related to the one they just bought. + +While Web3 may not support communication services like email or text message natively, we can include information and call-to-actions at the point where the user is within the context of the product they just bought: when viewing the completed (or failed) transaction itself. The equivalent in MetaMask is Activity (history) tab of the home screen. + +If a user wants to learn more about a past transaction or the smart contract / dapp they interacted with then we can present those sorts of insights to them at the point when they are viewing a previous transaction. + +## Specification + +One of the perks of this proposal is that we can more or less mimic the `onTransaction` and `onSignature` handlers. The main two differences will be the following: + +1. Different entry-point (I will leave this part to you) +2. The parameters passed to the `onActivityItem` function should also include information about confirmations for the activity item / transaction + +``` +import type { OnActivityItemHandler } from "@metamask/snaps-sdk"; +import { Box, Heading, Text } from "@metamask/snaps-sdk/jsx"; + +export const onActivityItem: OnActivityItemHandler = async ({ + // should this be `activityItem` instead or is `Activity` only ever transactions? + // `transaction` param should also include details about tx / block confirmations + transaction, + chainId, + transactionOrigin, +}) => { + const insights = /* Get insights */; + return { + content: ( + + My Activity Item Insights + Here are the insights: + {insights.map((insight) => ( + {insight.value} + ))} + + ), + }; +}; +``` + +For inspiration: https://github.com/MetaMask/snaps/pull/3534 (I called the hook `onTransactionDetail` in this **obsolete** PR) + +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and +"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Snap Manifest + +This SIP introduces a new permission named `endowment:activity-item-insight`. This permission grants a Snap the ability to read details about an activity item (tx) and optionally the origin from which that transaction oriented. The MM Snaps team is welcome to include or exclude any properties they see fit to best enable Snaps developers. + +This permission is specified as follows in `snap.manifest.json` files: + +```json +{ + "initialPermissions": { + "endowment:activity-item-insight": { + "allowActivityItemOrigin": true + } + } +} +``` + +### Security Considerations + +The security concerns are very similar to the `onTransaction` handler except that it will typically be a past transaction rather one that is about to be signed. + +### User Experience Considerations + +None + +## Backwards Compatibility + +This SIP introduces a new method and does not modify any existing functionality. Therefore, there are no backwards compatibility concerns. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). \ No newline at end of file From 5b1abece1f22b42a84c1fecfebc1131e70825e22 Mon Sep 17 00:00:00 2001 From: smilingkylan Date: Mon, 27 Oct 2025 13:49:40 -0700 Subject: [PATCH 2/7] Change onHistory to onActivity --- SIPS/sip-34.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index e904f7b..2948f19 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -1,6 +1,6 @@ --- sip: 34 -title: History Item Insights +title: Activity Item Insights status: Draft author: Kylan Hurt (@smilingkylan, kylan.hurt@gmail.com) created: 2025-10-26 @@ -8,7 +8,7 @@ created: 2025-10-26 ## Abstract -The purpose of this SIP is to propose the addition of an lifecycle hook, similar to the `onTransaction` and `onSignature` hooks that triggers when the user clicks on a history item (typically a transaction), passing with it parameters related to the transaction. I am giving this hook the name `onHistoryItem`. +The purpose of this SIP is to propose the addition of an lifecycle hook, similar to the `onTransaction` and `onSignature` hooks that triggers when the user clicks on a history item (typically a transaction), passing with it parameters related to the transaction. I am giving this hook the name `onActivityItem`. ## Motivation From 660de5ac4c7f0ba80c5204706f96e2419a862683 Mon Sep 17 00:00:00 2001 From: Kylan Hurt <6249205+smilingkylan@users.noreply.github.com> Date: Sun, 16 Nov 2025 23:12:35 -0800 Subject: [PATCH 3/7] Update SIPS/sip-34.md Co-authored-by: Maarten Zuidhoorn --- SIPS/sip-34.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index 2948f19..c96ff0f 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -51,8 +51,6 @@ export const onActivityItem: OnActivityItemHandler = async ({ }; ``` -For inspiration: https://github.com/MetaMask/snaps/pull/3534 (I called the hook `onTransactionDetail` in this **obsolete** PR) - ### Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", From 3e9888d3101de14c2c8a4ebd4cf125cfddd1b852 Mon Sep 17 00:00:00 2001 From: Kylan Hurt Date: Sun, 8 Mar 2026 17:34:59 -0700 Subject: [PATCH 4/7] Refine SIP-34 onActivityItem --- SIPS/sip-34.md | 135 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 110 insertions(+), 25 deletions(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index c96ff0f..fdc639c 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -8,7 +8,7 @@ created: 2025-10-26 ## Abstract -The purpose of this SIP is to propose the addition of an lifecycle hook, similar to the `onTransaction` and `onSignature` hooks that triggers when the user clicks on a history item (typically a transaction), passing with it parameters related to the transaction. I am giving this hook the name `onActivityItem`. +The purpose of this SIP is to propose the addition of a lifecycle hook, `onActivityItem`, similar to the `onTransaction` and `onSignature` hooks that triggers when the user clicks on a history item (typically a transaction), passing with it parameters related to the transaction. ## Motivation @@ -20,21 +20,57 @@ If a user wants to learn more about a past transaction or the smart contract / d ## Specification -One of the perks of this proposal is that we can more or less mimic the `onTransaction` and `onSignature` handlers. The main two differences will be the following: +> Formal specifications are written in Typescript. Usage of `CAIP-N` specifications, where `N` is a number, are references to [Chain Agnostic Improvement Proposals](https://github.com/ChainAgnostic/CAIPs). -1. Different entry-point (I will leave this part to you) -2. The parameters passed to the `onActivityItem` function should also include information about confirmations for the activity item / transaction +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and +"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Snap Manifest +This SIP introduces a new permission named `endowment:activity-insight`. This permission grants a Snap the ability to read details about an activity item (transaction) and optionally the origin from which that transaction originated. + +This permission is specified as follows in `snap.manifest.json` files: + +```json +{ + "initialPermissions": { + "endowment:activity-insight": {} + } +} ``` + +The permission includes an OPTIONAL caveat `allowActivityOrigin`. +The caveat grants a Snap read-only access to the URL of the dapp that initiated the transaction. +It can be specified as follows: + +```json +{ + "initialPermissions": { + "endowment:activity-insight": { + "allowActivityOrigin": true + } + } +} +``` + +### Snap Implementation + +The following is an example implementation of the API: + +```typescript import type { OnActivityItemHandler } from "@metamask/snaps-sdk"; import { Box, Heading, Text } from "@metamask/snaps-sdk/jsx"; export const onActivityItem: OnActivityItemHandler = async ({ - // should this be `activityItem` instead or is `Activity` only ever transactions? - // `transaction` param should also include details about tx / block confirmations transaction, chainId, transactionOrigin, + status, + transactionHash, + receipt, }) => { const insights = /* Get insights */; return { @@ -51,35 +87,84 @@ export const onActivityItem: OnActivityItemHandler = async ({ }; ``` -### Language +The interface for an `onActivityItem` handler function's arguments is: + +```typescript +interface OnActivityItemArgs { + transaction: Transaction; + chainId: CaipChainId; + transactionOrigin?: string; + status: ActivityItemStatus; + transactionHash?: string; + transactionType?: string; + receipt?: ActivityItemReceipt; + blockNumber?: string; + blockTimestamp?: string; + submittedTime?: number; + error?: { message: string; rpc?: string }; +} +``` -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and -"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) +`transaction` - The transaction parameters object. This is intentionally aligned with the `transaction` argument in `onTransaction` (see [SIP-3](sip-3.md)), using the same `Transaction` type from `@metamask/snaps-sdk`. -### Snap Manifest +`chainId` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md) chain ID string (e.g. `"eip155:1"`). -This SIP introduces a new permission named `endowment:activity-item-insight`. This permission grants a Snap the ability to read details about an activity item (tx) and optionally the origin from which that transaction oriented. The MM Snaps team is welcome to include or exclude any properties they see fit to best enable Snaps developers. +`transactionOrigin` - The URL origin of the dapp that initiated the transaction. The existence of this property is dependent on the `allowActivityOrigin` caveat. -This permission is specified as follows in `snap.manifest.json` files: +`status` - The status of the activity item at the time the user views it. See `ActivityItemStatus` below. -```json -{ - "initialPermissions": { - "endowment:activity-item-insight": { - "allowActivityItemOrigin": true - } - } +`transactionHash` - The on-chain transaction hash, if the transaction was submitted to the network. + +`transactionType` - A string describing the kind of transaction (e.g. `"simpleSend"`, `"contractInteraction"`, `"swap"`, `"tokenMethodTransfer"`). The set of possible values may expand over time. + +`receipt` - The transaction receipt, available once the transaction has been included in a block. See `ActivityItemReceipt` below. + +`blockNumber` - The number of the block in which the transaction was included. + +`blockTimestamp` - The timestamp of the block in which the transaction was included. + +`submittedTime` - The Unix epoch timestamp (in milliseconds) at which the transaction was submitted to the network. + +`error` - Error details if the transaction failed or was reverted on-chain. + +The `ActivityItemStatus` type represents the possible states of an activity item as seen in the Activity tab: + +```typescript +type ActivityItemStatus = + | 'confirmed' // Successfully mined and included in a block + | 'failed' // Reverted on-chain or errored during execution + | 'submitted' // Pending in the mempool + | 'dropped' // Replaced or dropped from the mempool + | 'rejected'; // Rejected by the user before submission +``` + +The `ActivityItemReceipt` type contains on-chain execution details returned by the network after the transaction is mined: + +```typescript +interface ActivityItemReceipt { + blockHash?: string; + blockNumber?: string; + effectiveGasPrice?: string; + gasUsed?: string; + l1Fee?: string; + logs?: { address?: string; data?: string; topics?: string }[]; + status?: string; // "0x1" for success, "0x0" for revert + transactionIndex?: string; } ``` -### Security Considerations +The interface for the return value of an `onActivityItem` export is: -The security concerns are very similar to the `onTransaction` handler except that it will typically be a past transaction rather one that is about to be signed. +```typescript +interface OnActivityItemResponse { + content: Component | null; + severity?: SeverityLevel; +} +``` -### User Experience Considerations +### Security Considerations -None +The security concerns are very similar to the `onTransaction` handler (see [SIP-3](sip-3.md)), except that this hook fires on a completed or pending transaction rather than one that is about to be signed. Snap developers MUST NOT assume that the presence of a `receipt` or `transactionHash` implies the transaction was successful; the `status` field SHOULD be used as the authoritative indicator of outcome. ## Backwards Compatibility @@ -87,4 +172,4 @@ This SIP introduces a new method and does not modify any existing functionality. ## Copyright -Copyright and related rights waived via [CC0](../LICENSE). \ No newline at end of file +Copyright and related rights waived via [CC0](../LICENSE). From 424de22682aabc93985a8561aaa8ece713ac3d2c Mon Sep 17 00:00:00 2001 From: Kylan Hurt Date: Sun, 8 Mar 2026 18:04:13 -0700 Subject: [PATCH 5/7] Adjust SIP-34 author info --- SIPS/sip-34.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index fdc639c..67abb2c 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -2,7 +2,7 @@ sip: 34 title: Activity Item Insights status: Draft -author: Kylan Hurt (@smilingkylan, kylan.hurt@gmail.com) +author: Kylan Hurt (smilingkylan.eth, kylan.hurt@gmail.com) created: 2025-10-26 --- From 9a183ef803755473d2d257b6de0e53a0cd1674b4 Mon Sep 17 00:00:00 2001 From: Kylan Hurt Date: Sun, 8 Mar 2026 18:14:04 -0700 Subject: [PATCH 6/7] Adjust author line --- SIPS/sip-34.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index 67abb2c..fdc639c 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -2,7 +2,7 @@ sip: 34 title: Activity Item Insights status: Draft -author: Kylan Hurt (smilingkylan.eth, kylan.hurt@gmail.com) +author: Kylan Hurt (@smilingkylan, kylan.hurt@gmail.com) created: 2025-10-26 --- From 942fa93ae5cbd9dd760493ffce4653edd676d040 Mon Sep 17 00:00:00 2001 From: Kylan Hurt Date: Sun, 8 Mar 2026 18:21:15 -0700 Subject: [PATCH 7/7] Another author edit --- SIPS/sip-34.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SIPS/sip-34.md b/SIPS/sip-34.md index fdc639c..69efe90 100644 --- a/SIPS/sip-34.md +++ b/SIPS/sip-34.md @@ -2,7 +2,7 @@ sip: 34 title: Activity Item Insights status: Draft -author: Kylan Hurt (@smilingkylan, kylan.hurt@gmail.com) +author: Kylan Hurt (@smilingkylan) created: 2025-10-26 ---