Non-Custodial Claim Migration Workflow

[jorgecuesta]

Hello folks @Olshansk @bryanchriswhite @red-0ne; @breezytm and I was reading through the documentation, asking AIs, etc.
We are trying to understand the claim process of the migration, specifically for the non-custodial.
Here we prepare a few use cases of our understandings on how the migration either works or should work, based on our
experience as node runners.

----------------------------------

Use Cases:

----------------------------------
Wallet Migration Use Case:
----------------------------------

1. Own Morse Account (A)
2. Own Shannon Account (B)
3. Claim MACT (faucet) on Shannon for an account at step 2, to force shannon account to exist.
4. Migrate MsgClaimMorseAccount from A -> B (this creates bonding between morse and shannon account)

Result:

• Shannon Account (B) as the new holder of tokens/authority in Morse Account (A)

----------------------------------
Custodial Migration Use Case:
----------------------------------
Morse Context:

• Node Address (A)

Shannon Context (Note: just empty wallets):

• Supplier Address (Z)

1. Run Wallet Migration Use Case for every wallet on contexts
   1.1 Node Address (A) -> Supplier Address (Z)
2. Run Migrate MsgClaimMorseSupplier for Node on Morse:
   2.1 Node Address = A -> Operator & Owner Address = Z - Because is the Shannon bonding created with MsgClaimMorseAccount between networks for account A

Result:

• Supplier Account (Z) as representing Node Address (A) in Shannon network

----------------------------------
Non-Custodial Migration Use Case:
----------------------------------

Morse Context:

• Morse -> Output Address: (A)
• Morse -> Node 1 Address: (B)
• Morse -> Node 2 Address: (C)

Shannon Context (Note: just empty wallets):

• Shannon -> Owner Address: (X)
• Shannon -> Supplier 1 Address: (Y)
• Shannon -> Supplier 2 Address: (Z)

1. Run Wallet Migration Use Case for every wallet on contexts
   1.1 Output Address (A) -> Owner Address (X)
   1.2 Node 1 Address (B) -> Supplier 1 Address (Y)
   1.3 Node 2 Address (C) -> Supplier 2 Address (Z)
2. Repeat Migrate MsgClaimMorseSupplier for every Node on Morse:
   --- iter 1 ---
   2.1 Owner Address = X - Because is the Shannon account bonded to Morse Account A as Output Address
   2.2 Morse Address = B -> Operator Address 1 = Y - Because is the Shannon bonding created with MsgClaimMorseAccount between networks for account B
   --- iter 2 ---
   2.3 Owner Address = X - Because is the Shannon account bonded to Morse Account A as Output Address
   2.4 Morse Address = C -> Operator Address 2 = Z - Because is the Shannon bonding created with MsgClaimMorseAccount between networks for account C

Result:

• Shannon Account (Y) as the Owner of Supplier Account (X) and (Z)

----------------------------------

Assumptions:

1. MsgClaimMorseSupplier enforce the following rules:
   1.1 shannon_owner_address used was the shannon_dest_address of the MsgClaimMorseAccount to migrate Morse Account (A) to Shannon Account (Y)
   1.2 shannon_operator_address used was the shannon_dest_address of the MsgClaimMorseAccount to migrate Morse Account 1 (B) to Shannon Account (X)
   1.3 shannon_operator_address used was the shannon_dest_address of the MsgClaimMorseAccount to migrate Morse Account 1 (C) to Shannon Account (Z)
   1.4 Same of 1.2 and 1.3 for Morse Node 2 -> Shannon Supplier 2

----------------------------------

Conclusion:

If our assumption about how the migration from Morse to Shannon works is correct, then the staking providers (who manage the nodes) only need to know the BONDED ‘output address/owner address’ in order to move the nodes for customers.

However, when we look at the code [1], it seems that only the ‘owner address’ is allowed to approve the transaction, which is not ideal.

Why isn't it ideal? Rely on the customer to run the migration could delay the process and overcomplicate it because they are not technical.
Also, the MsgClaimMorseSupplier requires some configuration files that require deep knowledge of stake structure [2], and usage of web/bash tools which may be ready but not properly documented for everyone.

Letting operators migrate these nodes for customers would make the process easier. It would also ensure that anyone with the proper private key could move the servicer's address to Shannon—as long as the ‘owner address’ matches during the migration.

I want to add that the flow we described here provides security for each actor (stake holder aka owner, provider aka node runner):

• does not allow to use an owner address that is not the one owned by the stake holder (currently done by require stake holder been the signer) but with this is due to the usage of the bonding of morse-shannon during the MsgClaimMorseAccount
• does not allow any weird movement to the wrong provider by mistake or bad actors (provider side)
• allows operator runs all the things, which speed up the migration process for the D-day
• reduce the pressure over the responsibility of the customer.
• open also the opportunity for operators to watch shannon to get their clients migration wallet (output) to then automatize their nodes migration.

Of course if the flow is the one we describe.

----------------------------------

Links:

1. https://github.com/pokt-network/poktroll/blob/main/proto/pocket/migration/tx.proto#L232
2. https://github.com/pokt-network/poktroll/blob/main/proto/pocket/migration/tx.proto#L235

[TheFeloniousMonk]

Subscribing.

[Olshansk]

Non-Custodial Claim Migration Workflow (Rewrite)

Background: This document is a (AI-assited) rewrite of the original content from @jorgecuesta that I put together while reading, understanding, evaluating and thinking about the suggestion.

Disclaimer: Suggested changes are a function of the assumptions being correct. Whether that's the case or not, streamlining the node's workflow will require a deeper dive into the investigation.

TL;DR

The goal is to streamline the claiming of Morse Nodes as Shannon Suppliers

-- WITHOUT --

Requiring owners to approve the transaction, thereby delegating the operational overhead tooperators.

What's new and what will come?

1. Nothing new? other than the content from @jorgecuesta
2. Bonus? Some diagrams & sections to make it easier to follow
3. What's coming? I'll start new/different threads of suggestions/comms to ensure clear comms.

---

A. Background - Migration Use Cases

1. Wallet Migration

Click to expand Wallet Migration details

TL;DR

A basic account migration that bonds Morse accounts to Shannon accounts, establishing the foundation for further migration steps.

Process

• Starting state:
  • Own Morse Account (A)
  • Own Shannon Account (B)
• Steps:
  1. Claim MACT (faucet) on Shannon for account B (forces Shannon account to exist)
  2. Migrate using MsgClaimMorseAccount from A → B (creates bonding between accounts)
• Result:
  • Shannon Account (B) becomes the new holder of tokens/authority in Morse Account (A)

graph LR
    A[Morse Account A] -->|MsgClaimMorseAccount| B[Shannon Account B]
    style A fill:#f9d5e5,stroke:#000
    style B fill:#eeeeee,stroke:#000
    
    %% Making text black by adding class definitions
    classDef default color:#000
    class A,B default

Loading

2. Custodial Migration

Click to expand Custodial Migration details

TL;DR

Migration process for a custodial setup where a single supplier account represents a node address on the Shannon network.

Process

• Morse Context:
  • Node Address (A)
  • A = OutputAddress (i.e. Owner)
  • A = Address (i.e. Operator)
• Shannon Context (empty wallets):
  • Supplier Address (Z)
  • Z = OwnerAddress
  • Z = OperatorAddress (for all intents and purposes)
• Steps:
  1. Run Wallet Migration for involved wallets:
     • Node Address (A) → Supplier Address (Z)
  2. Run MsgClaimMorseSupplier for Node on Morse:
     • Node Address = A → Operator & Owner Address = Z
     • (Z is valid because of the bonding created with MsgClaimMorseAccount)
• Result:
  • Supplier Account (Z) represents Node Address (A) in Shannon network

graph TD
    subgraph "Morse Network" AS MN
    A["Node Address A <br> A = Owner = Operator"]
    end
    
    subgraph "Shannon Network" AS SN
    Z["Supplier Address Z <br> A = Addr = Add"]
    end
    
    A -->|MsgClaimMorseAccount| Z
    A -->|MsgClaimMorseSupplier| Z
    
    style A fill:#f9d5e5,stroke:#000
    style Z fill:#eeeeee,stroke:#000
    
    %% Making all text black
    classDef default color:#000
    class A,Z default
    classDef subgraphStyle color:#000
    class MN,SN subgraphStyle

Loading

3. Non-Custodial Migration (CRITICAL SCENARIO FOR THIS DISCUSSION)

Click to expand Non-Custodial Migration details

TL;DR

Complex migration scenario where:

• Single Identity maintains multiple nodes
• Separate permutations of owner and operator addresses need to be migrated
• Relationship structure needs to be maintained

Process

• Morse Context:
  • Output Address: (A)
  • Node 1 Address: (B) (i.e. Operator)
  • Node 2 Address: (C) (i.e. Operator)
• Shannon Context (empty wallets):
  • Owner Address: (X)
  • Supplier 1 Address: (Y) (i.e. Operator)
  • Supplier 2 Address: (Z) (i.e. Operator)
• Steps:
  1. Run Wallet Migration for all wallets:
     • Output Address (A) → Owner Address (X)
     • Node 1 Address (B) → Supplier 1 Address (Y)
     • Node 2 Address (C) → Supplier 2 Address (Z)
  2. Migrate using MsgClaimMorseSupplier for each Node on Morse:
     • First Node:
       • Owner Address = X (bonded to Morse Account A)
       • Morse Address = B → Operator Address 1 = Y
     • Second Node:
       • Owner Address = X (bonded to Morse Account A)
       • Morse Address = C → Operator Address 2 = Z
• Result:
  • Shannon Account (X) becomes the Owner of Supplier Accounts (Y) and (Z)

graph TD
    subgraph "Morse Network" as MN
    A[Output Address A]
    B[Node 1 Address B]
    C[Node 2 Address C]
    end
    
    subgraph "Shannon Network" as SN
    X[Owner Address X]
    Y[Supplier 1 Address Y]
    Z[Supplier 2 Address Z]
    end
    
    A -->|MsgClaimMorseAccount| X
    B -->|MsgClaimMorseAccount| Y
    C -->|MsgClaimMorseAccount| Z
    
    B -->|MsgClaimMorseSupplier| Y
    C -->|MsgClaimMorseSupplier| Z
    
    X -->|Owns| Y
    X -->|Owns| Z
    
    style A fill:#f9d5e5,stroke:#000
    style B fill:#c8e6c9,stroke:#000
    style C fill:#c8e6c9,stroke:#000
    style X fill:#eeeeee,stroke:#000
    style Y fill:#e3f2fd,stroke:#000
    style Z fill:#e3f2fd,stroke:#000
    
    %% Making all text black
    classDef default color:#000
    class A,B,C,X,Y,Z default
    classDef subgraphStyle color:#000
    class MN,SN subgraphStyle

Loading

---

B. Assumptions, Issues, Conerns & Suggestions

The assumptions and concerns below are in reference to section A3 above.

1. Migration Rule Assumptions

Click to expand Migration Rule details

tl;dr The migration process depends on proper account bonding established during the wallet migration phase.

We believe MsgClaimMorseSupplier enforces these rules:
B1.1 Shannon owner must be the destination from MsgClaimMorseAccount from Morse's output
B1.2 Shannon operator must be the destination from MsgClaimMorseAccount for the Node addresses
B1.3 Proper bonding between Morse and Shannon accounts must be established first

2. Current Implementation Concerns

Click to expand Implementation Concerns

tl;dr The current implementation appears to require owner approval for migrations, which complicates the process for non-technical users.

B2.1 Looking at the code [1], only the 'owner address' appears authorized to approve transactions. This is problematic because:

• Relying on customers (often non-technical) to run migrations may delay the process
• MsgClaimMorseSupplier requires configuration files with deep knowledge of stake structure [2]
• Requires web/bash tools that may not be properly documented

---

C. Conclusion & Proposed Changes + Implementation

Click to expand Proposed Implementation details

tl;dr Allow node operators to handle migrations (fully) to streamline the process while maintaining security through proper account bonding.

Benefits of proposed approach:

• ✅ Does not allow using an owner address not owned by the stakeholder (secured by Morse-Shannon bonding during MsgClaimMorseAccount)
• ✅ Prevents incorrect provider assignments, protecting against mistakes or bad actors
• ✅ Allows operators to handle the entire process, accelerating migration
• ✅ Reduces customer responsibility and technical burden
• ✅ Enables operators to automate node migrations by watching Shannon for client migration wallets

Current implementation issues:

• ❌ Requires technical knowledge from customers
• ❌ May cause delays during migration day
• ❌ Increases complexity for end users

---

D. References

1. Migration TX Proto L232
2. Migration TX Proto L235

[Olshansk]

Just meant as a #FYI for reference - no more than that.

---

Posting a link w/ related github issues, PRs and ongoing work.

Actual details, proposal, explanations will follow up in a separate thread.

• [Migration] Clarification of Shannon signing not being restricted the owner or operator address #1320
• [Migration] Fix incorrect address used in supplier existence check during Supplier migration #1313
• [Morse -> Shannon Migration] Ensure Shannon supplier owner matches Morse output_address #1317
• [Morse -> Shannon Migration] Morse output_address account MAY claim Shannon supplier #1321
• [Morse -> Shannon Migration] Ensure supplier owner account matches #1314
• [DO NOT MERGE][WIP] Responding to #1311 #1312

[Olshansk]

A2. Cusotial Migration

Starting a thread ONLY to explain and provide details on flow A2 in this message

---

This is how things currently work on main and how things will continue working during the migration unless we, collectively, deem an issue.

Takeaway: MsgClaimMorseAccount DOES NOT need to be invoked for claiming custodial suppliers.

The understanding was this:

graph TD
    subgraph "Morse Network" AS MN
    A["Node Address A<br>A = Addr = Output"]
    end
    
    subgraph "Shannon Network" AS SN
    Z["Supplier Address Z<br>Z = Owner = Operator"]
    end
    
    A -->|MsgClaimMorseAccount| Z
    A -->|MsgClaimMorseSupplier| Z
    
    style A fill:#f9d5e5,stroke:#000
    style Z fill:#eeeeee,stroke:#000
    
    %% Making all text black
    classDef default color:#000
    class A,Z default
    classDef subgraphStyle color:#000
    class MN,SN subgraphStyle

Loading

The actuality is this:

graph TD
    subgraph MN["Morse Network"]
        A["Node Address A<br>A = Addr = Output"]
        UA["Unstaked Balance"]
        SA["Staked Balance"]
    end
    
    subgraph SN["Shannon Network"]
        UZ["Unstaked Balance (Shannon)"]    
        Z["Supplier Address Z<br>Z = Owner = Operator"]
        SZ["Staked Balance "]
    end
    
    MN -.->|MsgClaimMorseSupplier| SN
    UA ---|"Transfer <br> (Unstaked Balance)"| UZ
    SA ---|"Transfer <br> (Staked Balance)"| SZ
    
    style A fill:#f9d5e5,stroke:#000
    style UA fill:#fff2cc,stroke:#000
    style SA fill:#cfe2f3,stroke:#000
    style Z fill:#eeeeee,stroke:#000
    style UZ fill:#fff2cc,stroke:#000
    style SZ fill:#cfe2f3,stroke:#000
    %% Making all text black
    classDef default color:#000
    class A,UA,SA,Z,UZ,SZ default
    classDef subgraphStyle color:#000
    class MN,SN subgraphStyle

Loading

[jorgecuesta]

Unstaked balance from node wallet could be moved to any shannon account because will not be used to verify the relationship on MsgClaimMorseSupplier when the use case is Custodial.
Please confirm @Olshansk

[Olshansk]

@jorgecuesta Unfortunately I can't confirm that because I don't fully understand what you're describing.

---

This is an extremely nuanced workflow with lots of edge cases.

--

I tried to be as explicit as possible with what's possible using diagrams, visuals, and something you can test using LocalNet here.

We can do one of the three:

1. Can you try it out via LocalNet using the instructions here
2. Try to provide an example workflow?
3. Create a mermaid diagram

Any of one (not all three) of the above will help to ensure we're 100% aligned on what's possible and what's not.

[Olshansk]

A3. Non-Cusotial Migration

Starting a thread ONLY to continue the discussion in flow A3 in this message

---

This IS NOT due to a lack of support for custodial / non-custodial claiming as well as support for owner/output addresses.

There are two PRs in flight to add partial support for this, and one more will follow to enforce the table below.

In flight:

• [Morse -> Shannon Migration] Morse output_address account MAY claim Shannon supplier #1321
• [Morse -> Shannon Migration] Ensure Shannon supplier owner matches Morse output_address #1317
• Enforcing the table below: coming soon.

Call to action & Next Steps: Feedback on whether the list of supported/unsupported with onchain/offchain requirements below will satisfy the migration requirements. The process will be similar to what is described in A2 with additional constraints and slightly different configurations.

---

Morse / Shannon-sign Description	Morse (output_address, address)	Shannon (owner_address, operator_address)	Claim Signer	Supported	Details / Notes / Explanation	Pre-conditions
custodial / owner-operator-sign	(M, M)	(S, S)	S	✅	Custodial flow #1	S owns M
custodial / operator-sign	(null, M)	(S, null)	S	✅	Custodial flow #2	S owns M
custodial / operator-sign	(null, M)	(S, S)	S	✅	Custodial flow #3	S owns M
non-custodial / owner-sign	(M1, M2)	(S1, null)	S1	❌	MUST have a distinct operator_address if a distinct output_address exists (for backwards-simplification)	NA
non-custodial / owner-sign	(M1, M2)	(S1, S2)	S1	✅	Non-custodial flow executed by owner (ONLY requires S1 & M1 signature)	(S1 owns M1) && (S2 owns M2) && (M2 gives S2 shannon staking config offchain)
non-custodial / operator-sign	(M1, M2)	(S1, S2)	S2	✅	Non-custodial flow executed by operator (ONLY requires S2 & M2 signature)	(S1 owns M1) && (S2 owns M2) && (S2 gives M2 shannon address offline)
non-custodial / owner-sign	(M1, null)	(S1, S2)	S2	❌	MUST NOT have a distinct operator_address if a distinct output_address does not exist (for backwards-simplification)	NA
missing operator / NA	(M1, null)	NA	NA	❌	Not supported because M2 cannot be null	NA
NA / missing owner	NA	(null, S2)	NA	❌	Not supported because S1 cannot be null	NA
non-custodial / owner-operator-sign	(M1, M2)	(S, S)	S	❌	operator_address must be distinct from owner_address (for backwards-simplification)	NA

Some assumptions:

• Owners of (S|M)1 and (S|M)2 are intended to be distinct offchain
• The owner of SX/MX are the same identity offchain

V1 of the Table

| Morse / Shannon-sign Description    | Morse (`address`, `output_address`) | Shannon (`owner_address`, `operator_address`) | Claim Signer | Supported | Details / Notes / Explanation                                                                    | Pre-conditions                                                                                  |
| ----------------------------------- | ----------------------------------- | --------------------------------------------- | ------------ | --------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| custodial / owner-operator-sign     | (`M`, `M`)                          | (`S`, `S`)                                    | `S`          | ✅        | Custodial flow #1                                                                                | `S` owns `M`                                                                                    |
| custodial / owner-sign              | (`M1`, null)                        | (`S1`, null)                                  | `S1`         | ✅        | Custodial flow #1                                                                                | `S1` owns `M1`                                                                                  |
| non-custodial / owner-sign          | (`M1`, `M2`)                        | (`S1`, null)                                  | `S1`         | ❌        | MUST have `operator_address` if `output_address` exists for backwards-simplification             | NA                                                                                              |
| non-custodial / owner-sign          | (`M1`, `M2`)                        | (`S1`, `S2`)                                  | `S1`         | ✅        | Non-custodial flow executed by owner                                                             | (`S1` owns `M1`) && (`S2` owns `M2`) && (`M2` gives `S2` shannon staking instructions offchain) |
| non-custodial / operator-sign       | (`M1`, `M2`)                        | (`S1`, `S2`)                                  | `S2`         | ✅        | Non-custodial flow executed by operator                                                          | (`S1` owns `M1`) && (`S2` owns `M2`) && (`S2` gives `M2` shannon address offline)               |
| non-custodial / owner-sign          | (`M1`, null)                        | (`S1`, `S2`)                                  | `S2`         | ❌        | MUST NOT have `operator_address` if `output_address` does not exist for backwards-simplification | NA                                                                                              |
| missing operator / NA               | (null, `M2`)                        | NA                                            | NA           | ❌        | Not supported because `M1` cannot be null                                                        | NA                                                                                              |
| NA / missing owner                  | NA                                  | (null, `S2`)                                  | NA           | ❌        | Not supported because `S1` cannot be null                                                        | NA                                                                                              |
| non-custodial / owner-operator-sign | (`M1`, `M2`)                        | (`S`, `S`)                                    | `S`          | ❌        | `operator_address` must differ from `owner_address` for backwards-simplification                 | NA                                                                                              |

[bryanchriswhite]

I think there's a typo in a couple of the "Pre-conditions" (S2 owns M1 & vice versa) UPDATE: the Morse & Shannon columns. In order for M1 to correspond to S1, etc. it should be something like:

• Morse (output_address, address)
• Shannon(owner_address, operator_address)

Additionally, I feel like it's worth noting that:

• The owner account (M2 -> S1) MUST be migrated as a pre-condition for this case (UPDATE: bypassing this check for now)
• The owner Shannon address (S1) MAY be queried onchain via QueryMorseClaimableAccountRequest by M1 address
• EventMorseAccountClaimed may also be used to signal operators that M1 has been claimed and provide the S1 address

Either way (query or event), I don't see any reason that the operator should need to coordinate directly with the owner with respect to getting their new Shannon address.

(outdated)

Morse / Shannon-sign Description	Morse (output_address, address)	Shannon (owner_address, operator_address)	Claim Signer	Supported	Details / Notes / Explanation	Pre-conditions
non-custodial / owner-sign	(M1, M2)	(S1, S2)	S1	✅	Non-custodial flow executed by owner	(S2 owns M1) && (S1 owns M2) && (M2 gives S2 shannon staking instructions offchain)
non-custodial / operator-sign	(M1, M2)	(S1, S2)	S2	✅	Non-custodial flow executed by operator	(S1 owns M1) && (S2 owns M2) && (((M1 has already migrated to S1) && (M2 queries onchain for S1 by M1 address)) OR (M2 watches for M1 claim event))

[bryanchriswhite]

I also think that row 3 ("non-custodial / owner-sign" w/ only Shannon owner) reduces to row 4 because the operator defaults to the owner when claiming (as well as staking generally IIRC).

[Olshansk]

@bryanchriswhite I've gone ahead and:

• Updated the table based on your feedback
• Updated the table based on our offline discussion
• Added a couple of assumptions

Next steps:

• @bryanchriswhite: Re-review the table for clarity, missing gaps, etc..
• @Olshansk: Document risk tradeoffs and potential "trust based fuckups" with potential mitigation plans by an onchain authority

[jorgecuesta]

@Olshansk @bryanchriswhite we should close/hide this thread, because @Olshansk already handle the updates. Probably if that is the path, we should add an issue for the Event mention done by @bryanchriswhite .

[Olshansk]

Bonus: WIP LocalNet E2E Copy-Pasta Supplier Claiming Instructions

I'm actively working on an early WIP to test claims on LocalNet (to simplify things).

The work:

• Can be followed in [DO NOT MERGE][WIP] Responding to #1311 #1312
• Shows the process of A2 (A3 will come after a few more changes and alignment of the table above)
• Will be merged and deployed to dev.poktroll.com once complete

Below is a copy-pasta of the current state of the instructions for easier access.

Details

# LocalNet Supplier Claim

These are manual copy-pasta instructions to test, experiment and showcase Supplier Claiming on a localnet.

Table of Contents

• Morse (pocketd)
  • Morse Account Preparation
  • Morse State Upload Preparation
  • State Upload
• Shannon (pocketd)
  • Shannon Account Preparation
  • Shannon Claim Suppliers
    • Claim Shannon Supplier WITHOUT an output address
    • [NOT IMPLEMENTED YET] Option 1 - Claim Shannon Supplier WITH an output address - as an owner
    • [NOT IMPLEMENTED YET] Option 2 - Claim Shannon Supplier WITH an output address - as an operator

Morse (pocketd)

Morse Account Preparation

Create four accounts:

# PNF & Validator (exactly one)
pocket accounts create --datadir ./pocket_test
# Supplier Address/Operator (one of two WITHOUT output address)
pocket accounts create --datadir ./pocket_test
# Supplier Address/Operator (two of two WITH output address)
pocket accounts create --datadir ./pocket_test
# Supplier Owner/Output (exactly one)
pocket accounts create --datadir ./pocket_test

List accounts:

pocket accounts list --datadir ./pocket_test

(0) 028026796df1d8450410eab29c710a5944eef8dd
(1) 2e2624762bcfee4a44001543adddce0e4f4cc823
(2) 80e3058d66ee75578b07472650483da0035febe6
(3) f9f5335adfe2f7c4e49ef5cf5856eded1c5d3c58

Grab the account address and export the key:

pocket accounts export 2e2624762bcfee4a44001543adddce0e4f4cc823 --datadir ./pocket_test
pocket accounts export 80e3058d66ee75578b07472650483da0035febe6 --datadir ./pocket_test
pocket accounts export f9f5335adfe2f7c4e49ef5cf5856eded1c5d3c58 --datadir ./pocket_test

Morse State Upload Preparation

Manually update temp_state_export.json with the following to reflect the following configs

• 028026796df1d8450410eab29c710a5944eef8dd: PNF & Validator (not used)
• 2e2624762bcfee4a44001543adddce0e4f4cc823: Supplier Address/Operator (one of two WITHOUT output address)
• 80e3058d66ee75578b07472650483da0035febe6: Supplier Address/Operator (two of two WITH output address)
• f9f5335adfe2f7c4e49ef5cf5856eded1c5d3c58: Supplier Owner/Output (exactly one)

Prepare the import account message:

pocketd tx migration collect-morse-accounts temp_state_export.json msg_import_morse_accounts.json

Upload the state:

pocketd tx migration import-morse-accounts \
  "./msg_import_morse_accounts.json" \
  --from=pnf \
  --grpc-addr=localhost:9090 \
  --home=./localnet/pocketd --keyring-backend="test"\
  --chain-id=pocket \
  --gas=auto --gas-adjustment=1.5

And validate the list of claimable accounts:

pocketd query migration list-morse-claimable-account \
  -o json --node=tcp://127.0.0.1:26657 \
  --home=./localnet/pocketd

For example, you will see output like so showing that a supplier has a staked and unstaked balance:

{
  "morse_src_address": "2E2624762BCFEE4A44001543ADDDCE0E4F4CC823",
  "unstaked_balance": {
    "denom": "upokt",
    "amount": "20000000000000"
  },
  "supplier_stake": {
    "denom": "upokt",
    "amount": "60000000000"
  },
  "application_stake": {
    "denom": "upokt",
    "amount": "0"
  }
}

State Upload

Run LocalNet:

make localnet_up

Upload State:

pocketd tx migration import-morse-state \
  "./temp_state_export.json" \
  --from=pnf \
  --grpc-addr=localhost:9090 \
  --home=./localnet/pocketd --keyring-backend="test"\
  --chain-id=pocket \
  --gas=auto --gas-adjustment=1.5 \

pocketd tx migration collect-morse-accounts temp_state_export.json msg_import_morse_accounts.json

Shannon (pocketd)

Shannon Account Preparation

Create three new pocketd accounts:

pocketd --keyring-backend="test" --home=./localnet/pocketd  keys add 2e26-claim-supplier-1
pocketd --keyring-backend="test" --home=./localnet/pocketd  keys add 80e3-claim-supplier-2
pocketd --keyring-backend="test" --home=./localnet/pocketd  keys add f9f5-claim-owner

Export their addresses:

ADDR_SUPPLIER_1=$(pocketd --keyring-backend="test" --home=./localnet/pocketd  keys show 2e26-claim-supplier-1 -a)
ADDR_SUPPLIER_2=$(pocketd --keyring-backend="test" --home=./localnet/pocketd  keys show 80e3-claim-supplier-2 -a)
ADDR_OWNER=$(pocketd --keyring-backend="test" --home=./localnet/pocketd  keys show f9f5-claim-owner -a)

And fund them:

pocketd tx bank send pnf $ADDR_SUPPLIER_1 1000000000000upokt --home ./localnet/pocketd
# Wait for it to be funded (~ 10 seconds until the tx is processed)
pocketd tx bank send pnf $ADDR_SUPPLIER_2 1000000000000upokt --home ./localnet/pocketd
# Wait for it to be funded (~ 10 seconds until the tx is processed)
pocketd tx bank send pnf $ADDR_OWNER 1000000000000upokt --home ./localnet/pocketd

And ensure they're funded:

pocketd query bank balances ${ADDR_SUPPLIER_1} --home ./localnet/pocketd
pocketd query bank balances ${ADDR_SUPPLIER_2} --home ./localnet/pocketd
pocketd query bank balances ${ADDR_OWNER} --home ./localnet/pocketd

Shannon Claim Suppliers

Morse / Shannon-sign Description	Morse (address, output_address)	Shannon (owner_address, operator_address)	Claim Signer	Supported	Details / Notes / Explanation	Pre-conditions
custodial / owner-operator-sign	(M, M)	(S, S)	S	✅	Custodial flow #1	S owns M
custodial / owner-sign	(M1, null)	(S1, null)	S1	✅	Custodial flow #1	S1 owns M1
non-custodial / owner-sign	(M1, M2)	(S1, null)	S1	❌	MUST have operator_address if output_address exists for backwards-simplification	NA
non-custodial / owner-sign	(M1, M2)	(S1, S2)	S1	✅	Non-custodial flow executed by owner	(S1 owns M1) && (S2 owns M2) && (M2 gives S2 shannon staking instructions offchain)
non-custodial / operator-sign	(M1, M2)	(S1, S2)	S2	✅	Non-custodial flow executed by operator	(S1 owns M1) && (S2 owns M2) && (S2 gives M2 shannon address offline)
non-custodial / owner-sign	(M1, null)	(S1, S2)	S2	❌	MUST NOT have operator_address if output_address does not exist for backwards-simplification	NA
missing operator / NA	(null, M2)	NA	NA	❌	Not supported because M1 cannot be null	NA
NA / missing owner	NA	(null, S2)	NA	❌	Not supported because S1 cannot be null	NA
non-custodial / owner-operator-sign	(M1, M2)	(S, S)	S	❌	operator_address must differ from owner_address for backwards-simplification	NA

Claim Shannon Supplier WITHOUT an output address

Conditions whereby:

• In Morse: operator_address != null output_address = null
• In Shannon: owner_address = operator_address
• Claiming as a owner_address on behalf of operator_address

Prepare a supplier stake config:

cat <<EOF > 2e26_claim_supplier_1_supplier_config.yaml
owner_address: ${ADDR_SUPPLIER_1}
operator_address: ${ADDR_SUPPLIER_1}
default_rev_share_percent:
  ${ADDR_OWNER}: 100
services:
  - service_id: anvil
    endpoints:
      - publicly_exposed_url: http://relayminer1:8545
        rpc_type: JSON_RPC
EOF

Claim the supplier:

pocketd tx migration claim-supplier \
 pocket-account-2e2624762bcfee4a44001543adddce0e4f4cc823.json \
 2e26_claim_supplier_1_supplier_config.yaml \
 --from=2e26-claim-supplier-1 \
 --node=http://localhost:26657 --chain-id=pocket \
 --home=./localnet/pocketd --keyring-backend=test --no-passphrase

And verify it is onchain:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_1} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd

You can check its stake:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_1} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.supplier.stake.amount'

You can check its unstaked balance:

pocketd query bank balance ${ADDR_SUPPLIER_1} upokt \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.balance.amount'

[NOT IMPLEMENTED YET] Option 1 - Claim Shannon Supplier WITH an output address - as an owner

Conditions whereby:

• In Morse: output_address != null & operator_address != null
• In Shannon: owner_address != operator_address
• Claiming as a owner_address on behalf of output_address

Prepare a supplier stake config:

cat <<EOF > 80e3_claim_supplier_2_supplier_config.yaml
owner_address: ${ADDR_OWNER}
operator_address: ${ADDR_SUPPLIER_2}
default_rev_share_percent:
  ${ADDR_OWNER}: 20
  ${ADDR_SUPPLIER_2}: 80
services:
  - service_id: anvil
    endpoints:
      - publicly_exposed_url: http://relayminer1:8545
        rpc_type: JSON_RPC
EOF

Claim the supplier:

pocketd tx migration claim-supplier \
 pocket-account-80e3058d66ee75578b07472650483da0035febe6.json \
 80e3_claim_supplier_2_supplier_config.yaml \
 --from=80e3-claim-supplier-2 \
 --node=http://localhost:26657 --chain-id=pocket \
 --home=./localnet/pocketd --keyring-backend=test --no-passphrase

And verify it is onchain:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_2} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd

You can check its stake:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_2} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.supplier.stake.amount'

You can check the unstaked balance transfer of the owner's unstaked balance:

pocketd query bank balance ${ADDR_OWNER} upokt \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.balance.amount'

[NOT IMPLEMENTED YET] Option 2 - Claim Shannon Supplier WITH an output address - as an operator

Conditions whereby:

• In Morse: output_address != null & operator_address != null
• In Shannon: owner_address = operator_address
• Claiming as a operator_address on behalf of output_address

Prepare a supplier stake config:

cat <<EOF > 80e3_claim_supplier_2_supplier_config.yaml
owner_address: ${ADDR_OWNER}
operator_address: ${ADDR_SUPPLIER_2}
default_rev_share_percent:
  ${ADDR_OWNER}: 20
  ${ADDR_SUPPLIER_2}: 80
services:
  - service_id: anvil
    endpoints:
      - publicly_exposed_url: http://relayminer1:8545
        rpc_type: JSON_RPC
EOF

Claim the supplier:

pocketd tx migration claim-supplier \
 pocket-account-80e3058d66ee75578b07472650483da0035febe6.json \
 80e3_claim_supplier_2_supplier_config.yaml \
 --from=80e3-claim-supplier-2 \
 --node=http://localhost:26657 --chain-id=pocket \
 --home=./localnet/pocketd --keyring-backend=test --no-passphrase

And verify it is onchain:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_2} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd

You can check its stake:

pocketd query supplier show-supplier ${ADDR_SUPPLIER_2} \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.supplier.stake.amount'

You can check the unstaked balance transfer of the owner's unstaked balance:

pocketd query bank balance ${ADDR_OWNER} upokt \
  -o json --node=http://127.0.0.1:26657 \
  --home=./localnet/pocketd | jq '.balance.amount'

[bryanchriswhite]

(see: #1311 (reply in thread), note to update the table in the details here as well)

[Olshansk]

@bryanchriswhite I won't be updating this thread anymore.

It was intended as a "FYI - You'll be able to test everything locally soon".

I figured no one would click into the PR, so I copy-pasted it here to give visibility into the quantity/quality of work put into it, and more importantly, its ease of use.

Next step: What we merge to main will be what we iterate on.

[jorgecuesta]

@Olshansk We should close/hide this thread tbh!

[Olshansk]

@jorgecuesta @RawthiL @Alann27 @TheFeloniousMonk @fredteumer

I've tried to tackle all the open questions w/ next steps as clearly and simply as possible in separate threads.

PTAL at your convenience so we can keep the momentum going.

[breezytm]

After reviewing the table together, @jorgecuesta and I can confirm that the listed onchain/offchain requirements align with our suggestions. Our only recommendation is to clean up the table to display only the supported actions.

Many of the unsupported actions listed are not technically possible and may create unnecessary confusion. The only meaningful unsupported case worth highlighting is the scenario where a non-custodial staked servicer in Morse is attempt to be claimed as a custodial supplier in Shannon, which is invalid by design—but still a real-world edge case worth documenting.

reference ▽

Morse / Shannon-sign Description	Morse (output_address, address)	Shannon (owner_address, operator_address)	Claim Signer	Supported	Details / Notes / Explanation	Pre-conditions
Non-custodial / owner-operator-sign	(M1, M2)	(S, S)	S	❌	operator_address must be distinct from owner_address (for backwards simplification)	N/A

[Olshansk]

Sgtm - thank you for the clear and detailed response @breezytm.

I will migrate it into the docs (dev.poktroll.com) cleaned up with your suggestion 👍

[breezytm]

Additional Use Case for Migration Flow:

There should be a mechanism during the migration process that allows a owner_address to unstake their non-custodial suppliers from Morse without needing action from the operator_address. This covers cases where:

• The node operator is no longer responsive or reachable.
• The owner no longer wishes to stake those suppliers in Shannon.
• The stake was delegated in a non-custodial manner, and the owner retains the right to reclaim it.

Currently, MsgClaimMorseSupplier assumes the intent is to restake in Shannon. However, in some cases, the owner may simply wish to unstake and withdraw, especially if the operator relationship has ended.

This functionality might be better implemented as a separate message (e.g. MsgUnstakeMorseSupplier) rather than overloading MsgClaimMorseSupplier, to make the intent explicit and prevent ambiguity.

Failing to support this scenario risks locking up non-custodial stake if an operator becomes unreachable during migration.

[jorgecuesta]

Creates a potential "liquidity crisis" during the migration

Not 100% true, because our point here is move them to unstaking on shannon respecting the lock period of 21 days.

[TheFeloniousMonk]

The only accounts that are going to move to liquid are nodes which are staked at less than 60K, as a courtesy due to the min stake being changed. Anyone who wishes to unstake will have the cooldown as normal. We will not have a liquidity crisis with the 15K nodes being moved to liquid because there are so few of them on the network. The design that @Olshansk is referencing is intentional at the request of PNF.

[Olshansk]

Could this simply be achieved by using existing mechanism:

1. Claim Morse Supplier on Shannon (MsgClaimMorseSupplier)
2. Unstake Supplier on Shannon (MsgUnstakeSupplier)
3. Start Unstaking Period on Shannon

That way:

1. It is one extra step on the user (MsgClaimMorseSupplier + MsgUnstakeSupplier)
2. Zero extra work on the protocol & development for a feature that'll be deprecated very soon (no need to implement MsgUnstakeMorseSupplier)

[TheFeloniousMonk]

Yep, agreed on this. We have to prioritize the critical stuff over the "nice to haves" during this final run.

[jorgecuesta]

Well sounds good but add complexity to the sMsgClaimMorseSupplier because the explaination for it is that account should exists on chain as result of MsgClaimMorseAccount migration, which in what we explain will not be possible.

This should be handled but could be on the next week of the release, should not block the initial migration. I wish to think that you guys are not expecting all this get solved in just few days. Migration should remains a while open to be sure we avoid leave tokens behind.