wip

Add RUSTUP_PERMIT_COPY_RENAME to ci-lint-typescript
Add concurrency limit to CI (#5651 )
2025-03-21 17:23:56 +01:00 · 2025-03-21 11:39:58 +01:00 · 2025-03-20 20:13:41 +01:00 · 2025-03-20 19:54:07 +01:00 · 2025-03-20 19:08:02 +02:00 · 2025-03-20 15:59:44 +01:00
1206 changed files with 114202 additions and 40597 deletions
@@ -1 +1,2 @@
 nym-validator-rewarder/.sqlx/** diff=nodiff
+nym-node-status-api/nym-node-status-api/.sqlx/** diff=nodiff
@@ -9,7 +9,7 @@
      "version": "1.0.0",
      "dependencies": {
        "@actions/core": "^1.10.1",
-        "@actions/github": "^5.1.1",
+        "@actions/github": "^6.0.0",
        "@octokit/auth-action": "^4.0.1",
        "@octokit/rest": "^20.0.2",
        "hasha": "^5.2.0",
@@ -29,22 +29,34 @@
      }
    },
    "node_modules/@actions/github": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.1.1.tgz",
-      "integrity": "sha512-Nk59rMDoJaV+mHCOJPXuvB1zIbomlKS0dmSIqPGxd0enAXBnOfn4VWF+CGtRCwXZG9Epa54tZA7VIRlJDS8A6g==",
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@actions/github/-/github-6.0.0.tgz",
+      "integrity": "sha512-alScpSVnYmjNEXboZjarjukQEzgCRmjMv6Xj47fsdnqGS73bjJNDpiiXmp8jr0UZLdUB6d9jW63IcmddUP+l0g==",
+      "license": "MIT",
      "dependencies": {
-        "@actions/http-client": "^2.0.1",
-        "@octokit/core": "^3.6.0",
-        "@octokit/plugin-paginate-rest": "^2.17.0",
-        "@octokit/plugin-rest-endpoint-methods": "^5.13.0"
+        "@actions/http-client": "^2.2.0",
+        "@octokit/core": "^5.0.1",
+        "@octokit/plugin-paginate-rest": "^9.0.0",
+        "@octokit/plugin-rest-endpoint-methods": "^10.0.0"
      }
    },
    "node_modules/@actions/http-client": {
-      "version": "2.1.1",
-      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.1.1.tgz",
-      "integrity": "sha512-qhrkRMB40bbbLo7gF+0vu+X+UawOvQQqNAA/5Unx774RS8poaOhThDOG6BGmxvAnxhQnDp2BG/ZUm65xZILTpw==",
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.2.3.tgz",
+      "integrity": "sha512-mx8hyJi/hjFvbPokCg4uRd4ZX78t+YyRPtnKWwIl+RzNaVuFpQHfmlGVfsKEJN8LwTCvL+DfVgAM04XaHkm6bA==",
+      "license": "MIT",
      "dependencies": {
-        "tunnel": "^0.0.6"
+        "tunnel": "^0.0.6",
+        "undici": "^5.25.4"
+      }
+    },
+    "node_modules/@fastify/busboy": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz",
+      "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
      }
    },
    "node_modules/@octokit/auth-action": {
@@ -59,14 +71,6 @@
        "node": ">= 18"
      }
    },
-    "node_modules/@octokit/auth-action/node_modules/@octokit/auth-token": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-4.0.0.tgz",
-      "integrity": "sha512-tY/msAuJo6ARbK6SPIxZrPBms3xPbfwBrulZe0Wtr/DIY9lje2HeV1uoebShn6mx7SjCHif6EjMvoREj+gZ+SA==",
-      "engines": {
-        "node": ">= 18"
-      }
-    },
    "node_modules/@octokit/auth-action/node_modules/@octokit/openapi-types": {
      "version": "20.0.0",
      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-20.0.0.tgz",
@@ -81,115 +85,152 @@
      }
    },
    "node_modules/@octokit/auth-token": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.5.0.tgz",
-      "integrity": "sha512-r5FVUJCOLl19AxiuZD2VRZ/ORjp/4IN98Of6YJoJOkY75CIBuYfmiNHGrDwXr+aLGG55igl9QrxX3hbiXlLb+g==",
-      "dependencies": {
-        "@octokit/types": "^6.0.3"
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-4.0.0.tgz",
+      "integrity": "sha512-tY/msAuJo6ARbK6SPIxZrPBms3xPbfwBrulZe0Wtr/DIY9lje2HeV1uoebShn6mx7SjCHif6EjMvoREj+gZ+SA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/core": {
-      "version": "3.6.0",
-      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.6.0.tgz",
-      "integrity": "sha512-7RKRKuA4xTjMhY+eG3jthb3hlZCsOwg3rztWh75Xc+ShDWOfDDATWbeZpAHBNRpm4Tv9WgBMOy1zEJYXG6NJ7Q==",
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-5.2.0.tgz",
+      "integrity": "sha512-1LFfa/qnMQvEOAdzlQymH0ulepxbxnCYAKJZfMci/5XJyIHWgEYnDmgnKakbTh7CH2tFQ5O60oYDvns4i9RAIg==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/auth-token": "^2.4.4",
-        "@octokit/graphql": "^4.5.8",
-        "@octokit/request": "^5.6.3",
-        "@octokit/request-error": "^2.0.5",
-        "@octokit/types": "^6.0.3",
+        "@octokit/auth-token": "^4.0.0",
+        "@octokit/graphql": "^7.1.0",
+        "@octokit/request": "^8.3.1",
+        "@octokit/request-error": "^5.1.0",
+        "@octokit/types": "^13.0.0",
        "before-after-hook": "^2.2.0",
        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/endpoint": {
-      "version": "6.0.12",
-      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz",
-      "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==",
+      "version": "9.0.6",
+      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-9.0.6.tgz",
+      "integrity": "sha512-H1fNTMA57HbkFESSt3Y9+FBICv+0jFceJFPWDePYlR/iMGrwM5ph+Dd4XRQs+8X+PUFURLQgX9ChPfhJ/1uNQw==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/types": "^6.0.3",
-        "is-plain-object": "^5.0.0",
+        "@octokit/types": "^13.1.0",
        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/graphql": {
-      "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.8.0.tgz",
-      "integrity": "sha512-0gv+qLSBLKF0z8TKaSKTsS39scVKF9dbMxJpj3U0vC7wjNWFuIpL/z76Qe2fiuCbDRcJSavkXsVtMS6/dtQQsg==",
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-7.1.0.tgz",
+      "integrity": "sha512-r+oZUH7aMFui1ypZnAvZmn0KSqAUgE1/tUXIWaqUCa1758ts/Jio84GZuzsvUkme98kv0WFY8//n0J1Z+vsIsQ==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/request": "^5.6.0",
-        "@octokit/types": "^6.0.3",
+        "@octokit/request": "^8.3.0",
+        "@octokit/types": "^13.0.0",
        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/openapi-types": {
-      "version": "12.11.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-12.11.0.tgz",
-      "integrity": "sha512-VsXyi8peyRq9PqIz/tpqiL2w3w80OgVMwBHltTml3LmVvXiphgeqmY9mvBw9Wu7e0QWk/fqD37ux8yP5uVekyQ=="
+      "version": "23.0.1",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-23.0.1.tgz",
+      "integrity": "sha512-izFjMJ1sir0jn0ldEKhZ7xegCTj/ObmEDlEfpFrx4k/JyZSMRHbO3/rBwgE7f3m2DHt+RrNGIVw4wSmwnm3t/g==",
+      "license": "MIT"
    },
    "node_modules/@octokit/plugin-paginate-rest": {
-      "version": "2.21.3",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.21.3.tgz",
-      "integrity": "sha512-aCZTEf0y2h3OLbrgKkrfFdjRL6eSOo8komneVQJnYecAxIej7Bafor2xhuDJOIFau4pk0i/P28/XgtbyPF0ZHw==",
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-9.2.2.tgz",
+      "integrity": "sha512-u3KYkGF7GcZnSD/3UP0S7K5XUFT2FkOQdcfXZGZQPGv3lm4F2Xbf71lvjldr8c1H3nNbF+33cLEkWYbokGWqiQ==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/types": "^6.40.0"
+        "@octokit/types": "^12.6.0"
+      },
+      "engines": {
+        "node": ">= 18"
      },
      "peerDependencies": {
-        "@octokit/core": ">=2"
+        "@octokit/core": "5"
+      }
+    },
+    "node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/openapi-types": {
+      "version": "20.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-20.0.0.tgz",
+      "integrity": "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA==",
+      "license": "MIT"
+    },
+    "node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/types": {
+      "version": "12.6.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-12.6.0.tgz",
+      "integrity": "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/openapi-types": "^20.0.0"
      }
    },
    "node_modules/@octokit/plugin-rest-endpoint-methods": {
-      "version": "5.16.2",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.16.2.tgz",
-      "integrity": "sha512-8QFz29Fg5jDuTPXVtey05BLm7OB+M8fnvE64RNegzX7U+5NUXcOcnpTIK0YfSHBg8gYd0oxIq3IZTe9SfPZiRw==",
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-10.4.1.tgz",
+      "integrity": "sha512-xV1b+ceKV9KytQe3zCVqjg+8GTGfDYwaT1ATU5isiUyVtlVAO3HNdzpS4sr4GBx4hxQ46s7ITtZrAsxG22+rVg==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/types": "^6.39.0",
-        "deprecation": "^2.3.1"
+        "@octokit/types": "^12.6.0"
+      },
+      "engines": {
+        "node": ">= 18"
      },
      "peerDependencies": {
-        "@octokit/core": ">=3"
+        "@octokit/core": "5"
+      }
+    },
+    "node_modules/@octokit/plugin-rest-endpoint-methods/node_modules/@octokit/openapi-types": {
+      "version": "20.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-20.0.0.tgz",
+      "integrity": "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA==",
+      "license": "MIT"
+    },
+    "node_modules/@octokit/plugin-rest-endpoint-methods/node_modules/@octokit/types": {
+      "version": "12.6.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-12.6.0.tgz",
+      "integrity": "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/openapi-types": "^20.0.0"
      }
    },
    "node_modules/@octokit/request": {
-      "version": "5.6.3",
-      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.3.tgz",
-      "integrity": "sha512-bFJl0I1KVc9jYTe9tdGGpAMPy32dLBXXo1dS/YwSCTL/2nd9XeHsY616RE3HPXDVk+a+dBuzyz5YdlXwcDTr2A==",
+      "version": "8.4.1",
+      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-8.4.1.tgz",
+      "integrity": "sha512-qnB2+SY3hkCmBxZsR/MPCybNmbJe4KAlfWErXq+rBKkQJlbjdJeS85VI9r8UqeLYLvnAenU8Q1okM/0MBsAGXw==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/endpoint": "^6.0.1",
-        "@octokit/request-error": "^2.1.0",
-        "@octokit/types": "^6.16.1",
-        "is-plain-object": "^5.0.0",
-        "node-fetch": "^2.6.7",
+        "@octokit/endpoint": "^9.0.6",
+        "@octokit/request-error": "^5.1.1",
+        "@octokit/types": "^13.1.0",
        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/request-error": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz",
-      "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==",
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-5.1.1.tgz",
+      "integrity": "sha512-v9iyEQJH6ZntoENr9/yXxjuezh4My67CBSu9r6Ve/05Iu5gNgnisNWOsoJHTP6k0Rr0+HQIpnH+kyammu90q/g==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/types": "^6.0.3",
+        "@octokit/types": "^13.1.0",
        "deprecation": "^2.0.0",
        "once": "^1.4.0"
-      }
-    },
-    "node_modules/@octokit/request/node_modules/node-fetch": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
-      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
-      "dependencies": {
-        "whatwg-url": "^5.0.0"
      },
      "engines": {
-        "node": "4.x || >=6.0.0"
-      },
-      "peerDependencies": {
-        "encoding": "^0.1.0"
-      },
-      "peerDependenciesMeta": {
-        "encoding": {
-          "optional": true
-        }
+        "node": ">= 18"
      }
    },
    "node_modules/@octokit/rest": {
@@ -206,89 +247,6 @@
        "node": ">= 18"
      }
    },
-    "node_modules/@octokit/rest/node_modules/@octokit/auth-token": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-4.0.0.tgz",
-      "integrity": "sha512-tY/msAuJo6ARbK6SPIxZrPBms3xPbfwBrulZe0Wtr/DIY9lje2HeV1uoebShn6mx7SjCHif6EjMvoREj+gZ+SA==",
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/core": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-5.0.0.tgz",
-      "integrity": "sha512-YbAtMWIrbZ9FCXbLwT9wWB8TyLjq9mxpKdgB3dUNxQcIVTf9hJ70gRPwAcqGZdY6WdJPZ0I7jLaaNDCiloGN2A==",
-      "dependencies": {
-        "@octokit/auth-token": "^4.0.0",
-        "@octokit/graphql": "^7.0.0",
-        "@octokit/request": "^8.0.2",
-        "@octokit/request-error": "^5.0.0",
-        "@octokit/types": "^11.0.0",
-        "before-after-hook": "^2.2.0",
-        "universal-user-agent": "^6.0.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/endpoint": {
-      "version": "9.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-9.0.0.tgz",
-      "integrity": "sha512-szrQhiqJ88gghWY2Htt8MqUDO6++E/EIXqJ2ZEp5ma3uGS46o7LZAzSLt49myB7rT+Hfw5Y6gO3LmOxGzHijAQ==",
-      "dependencies": {
-        "@octokit/types": "^11.0.0",
-        "is-plain-object": "^5.0.0",
-        "universal-user-agent": "^6.0.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/graphql": {
-      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-7.0.1.tgz",
-      "integrity": "sha512-T5S3oZ1JOE58gom6MIcrgwZXzTaxRnxBso58xhozxHpOqSTgDS6YNeEUvZ/kRvXgPrRz/KHnZhtb7jUMRi9E6w==",
-      "dependencies": {
-        "@octokit/request": "^8.0.1",
-        "@octokit/types": "^11.0.0",
-        "universal-user-agent": "^6.0.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/openapi-types": {
-      "version": "18.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-18.0.0.tgz",
-      "integrity": "sha512-V8GImKs3TeQRxRtXFpG2wl19V7444NIOTDF24AWuIbmNaNYOQMWRbjcGDXV5B+0n887fgDcuMNOmlul+k+oJtw=="
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-paginate-rest": {
-      "version": "9.2.1",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-9.2.1.tgz",
-      "integrity": "sha512-wfGhE/TAkXZRLjksFXuDZdmGnJQHvtU/joFQdweXUgzo1XwvBCD4o4+75NtFfjfLK5IwLf9vHTfSiU3sLRYpRw==",
-      "dependencies": {
-        "@octokit/types": "^12.6.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      },
-      "peerDependencies": {
-        "@octokit/core": "5"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/openapi-types": {
-      "version": "20.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-20.0.0.tgz",
-      "integrity": "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA=="
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/types": {
-      "version": "12.6.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-12.6.0.tgz",
-      "integrity": "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw==",
-      "dependencies": {
-        "@octokit/openapi-types": "^20.0.0"
-      }
-    },
    "node_modules/@octokit/rest/node_modules/@octokit/plugin-request-log": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/@octokit/plugin-request-log/-/plugin-request-log-4.0.0.tgz",
@@ -300,75 +258,13 @@
        "@octokit/core": ">=5"
      }
    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-rest-endpoint-methods": {
-      "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-10.4.1.tgz",
-      "integrity": "sha512-xV1b+ceKV9KytQe3zCVqjg+8GTGfDYwaT1ATU5isiUyVtlVAO3HNdzpS4sr4GBx4hxQ46s7ITtZrAsxG22+rVg==",
-      "dependencies": {
-        "@octokit/types": "^12.6.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      },
-      "peerDependencies": {
-        "@octokit/core": "5"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-rest-endpoint-methods/node_modules/@octokit/openapi-types": {
-      "version": "20.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-20.0.0.tgz",
-      "integrity": "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA=="
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/plugin-rest-endpoint-methods/node_modules/@octokit/types": {
-      "version": "12.6.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-12.6.0.tgz",
-      "integrity": "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw==",
-      "dependencies": {
-        "@octokit/openapi-types": "^20.0.0"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/request": {
-      "version": "8.1.1",
-      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-8.1.1.tgz",
-      "integrity": "sha512-8N+tdUz4aCqQmXl8FpHYfKG9GelDFd7XGVzyN8rc6WxVlYcfpHECnuRkgquzz+WzvHTK62co5di8gSXnzASZPQ==",
-      "dependencies": {
-        "@octokit/endpoint": "^9.0.0",
-        "@octokit/request-error": "^5.0.0",
-        "@octokit/types": "^11.1.0",
-        "is-plain-object": "^5.0.0",
-        "universal-user-agent": "^6.0.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/request-error": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-5.0.0.tgz",
-      "integrity": "sha512-1ue0DH0Lif5iEqT52+Rf/hf0RmGO9NWFjrzmrkArpG9trFfDM/efx00BJHdLGuro4BR/gECxCU2Twf5OKrRFsQ==",
-      "dependencies": {
-        "@octokit/types": "^11.0.0",
-        "deprecation": "^2.0.0",
-        "once": "^1.4.0"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@octokit/rest/node_modules/@octokit/types": {
-      "version": "11.1.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-11.1.0.tgz",
-      "integrity": "sha512-Fz0+7GyLm/bHt8fwEqgvRBWwIV1S6wRRyq+V6exRKLVWaKGsuy6H9QFYeBVDV7rK6fO3XwHgQOPxv+cLj2zpXQ==",
-      "dependencies": {
-        "@octokit/openapi-types": "^18.0.0"
-      }
-    },
    "node_modules/@octokit/types": {
-      "version": "6.41.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.41.0.tgz",
-      "integrity": "sha512-eJ2jbzjdijiL3B4PrSQaSjuF2sPEQPVCPzBvTHJD9Nz+9dw2SGH4K4xeQJ77YfTq5bRQ+bD8wT11JbeDPmxmGg==",
+      "version": "13.8.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-13.8.0.tgz",
+      "integrity": "sha512-x7DjTIbEpEWXK99DMd01QfWy0hd5h4EN+Q7shkdKds3otGQP+oWE/y0A76i1OvH9fygo4ddvNf7ZvF0t78P98A==",
+      "license": "MIT",
      "dependencies": {
-        "@octokit/openapi-types": "^12.11.0"
+        "@octokit/openapi-types": "^23.0.1"
      }
    },
    "node_modules/@vercel/ncc": {
@@ -396,7 +292,8 @@
    "node_modules/deprecation": {
      "version": "2.3.1",
      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
-      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
+      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ==",
+      "license": "ISC"
    },
    "node_modules/fetch-blob": {
      "version": "3.2.0",
@@ -446,14 +343,6 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
-    "node_modules/is-plain-object": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
-      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
    "node_modules/is-stream": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
@@ -504,15 +393,11 @@
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
      "dependencies": {
        "wrappy": "1"
      }
    },
-    "node_modules/tr46": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
-      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
-    },
    "node_modules/tunnel": {
      "version": "0.0.6",
      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
@@ -529,6 +414,18 @@
        "node": ">=8"
      }
    },
+    "node_modules/undici": {
+      "version": "5.28.5",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-5.28.5.tgz",
+      "integrity": "sha512-zICwjrDrcrUE0pyyJc1I2QzBkLM8FINsgOrt6WjA+BgajVq9Nxu2PbFFXUrAggLfDXlZGZBVZYw7WNV5KiBiBA==",
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/busboy": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.0"
+      }
+    },
    "node_modules/universal-user-agent": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
@@ -550,24 +447,11 @@
        "node": ">= 8"
      }
    },
-    "node_modules/webidl-conversions": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
-      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="
-    },
-    "node_modules/whatwg-url": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
-      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
-      "dependencies": {
-        "tr46": "~0.0.3",
-        "webidl-conversions": "^3.0.0"
-      }
-    },
    "node_modules/wrappy": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC"
    }
  }
 }
@@ -11,7 +11,7 @@
  },
  "dependencies": {
    "@actions/core": "^1.10.1",
-    "@actions/github": "^5.1.1",
+    "@actions/github": "^6.0.0",
    "@octokit/auth-action": "^4.0.1",
    "@octokit/rest": "^20.0.2",
    "hasha": "^5.2.0",
@@ -31,3 +31,5 @@ updates:
        update-types:
          - "patch"
    open-pull-requests-limit: 10
+    assignees:
+      - "octol"
@@ -26,6 +26,7 @@ jobs:
    runs-on: ${{ matrix.platform }}
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - uses: actions/checkout@v4

@@ -79,7 +80,6 @@ jobs:
            target/release/nym-socks5-client
            target/release/nym-api
            target/release/nym-network-requester
-            target/release/nym-data-observatory
            target/release/nym-cli
            target/release/nymvisor
            target/release/nym-node
@@ -97,11 +97,9 @@ jobs:
          cp target/release/nym-socks5-client $OUTPUT_DIR
          cp target/release/nym-api $OUTPUT_DIR
          cp target/release/nym-network-requester $OUTPUT_DIR
-          cp target/release/nym-data-observatory $OUTPUT_DIR
          cp target/release/nymvisor $OUTPUT_DIR
          cp target/release/nym-node $OUTPUT_DIR
          cp target/release/nym-cli $OUTPUT_DIR
-          cp target/release/explorer-api $OUTPUT_DIR
          if [ ${{ github.event_name == 'workflow_dispatch' && inputs.enable_deb == true }} = true ]; then
            cp target/debian/*.deb $OUTPUT_DIR
          fi
@@ -12,6 +12,7 @@ jobs:
    runs-on: arc-ubuntu-22.04
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
@@ -8,16 +8,18 @@ on:
      - 'explorer-api/**'
      - 'gateway/**'
      - 'integrations/**'
-      - 'mixnode/**'
-      - 'sdk/rust/**'
-      - 'sdk/lib/**'
-      - 'service-providers/**'
-      - 'nym-network-monitor/**'
      - 'nym-api/**'
+      - 'nym-credential-proxy/**'
+      - 'nym-network-monitor/**'
      - 'nym-node/**'
+      - 'nym-node-status-api/**'
      - 'nym-outfox/**'
-      - 'nym-data-observatory/**'
      - 'nym-validator-rewarder/**'
+      - 'nyx-chain-watcher/**'
+      - 'sdk/ffi/**'
+      - 'sdk/rust/**'
+      - 'service-providers/**'
+      - 'nym-browser-extension/storage/**'
      - 'tools/**'
      - 'wasm/**'
      - 'Cargo.toml'
@@ -25,16 +27,23 @@ on:
      - '.github/workflows/ci-build.yml'
  workflow_dispatch:

+concurrency:
+  # only 1 concurrent `ci-build` allowed per branch
+  # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#example-using-concurrency-and-the-default-behavior
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
-        os: [ arc-ubuntu-20.04, custom-runner-mac-m1 ]
+        os: [ arc-ubuntu-20.04, custom-windows-11, custom-runner-mac-m1 ]
    runs-on: ${{ matrix.os }}
    env:
      CARGO_TERM_COLOR: always
      IPINFO_API_TOKEN: ${{ secrets.IPINFO_API_TOKEN }}
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - name: Install Dependencies (Linux)
        run: sudo apt-get update && sudo apt-get -y install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libudev-dev squashfs-tools protobuf-compiler
@@ -52,6 +61,20 @@ jobs:
          override: true
          components: rustfmt, clippy

+      # To avoid running out of disk space, skip generating debug symbols
+      - name: Set debug to false (unix)
+        if: contains(matrix.os, 'ubuntu') || contains(matrix.os, 'mac')
+        run: |
+          sed -i.bak 's/\[profile.dev\]/\[profile.dev\]\ndebug = false/' Cargo.toml
+          git diff
+
+      - name: Set debug to false (win)
+        if: contains(matrix.os, 'windows')
+        shell: pwsh
+        run: |
+          (Get-Content Cargo.toml) -replace '\[profile.dev\]', "`$&`ndebug = false" | Set-Content Cargo.toml
+          git diff
+
      - name: Check formatting
        uses: actions-rs/cargo@v1
        with:
@@ -0,0 +1,57 @@
+name: ci-check-ns-api-version
+
+on:
+  pull_request:
+    paths:
+      - "nym-node-status-api/**"
+
+env:
+  WORKING_DIRECTORY: "nym-node-status-api/nym-node-status-api"
+
+jobs:
+  check-if-tag-exists:
+    runs-on: arc-ubuntu-22.04-dind
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Get version from cargo.toml
+        uses: mikefarah/yq@v4.45.1
+        id: get_version
+        with:
+          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
+
+      - name: Check if git tag exists
+        run: |
+          TAG=${{ env.WORKING_DIRECTORY }}-${{ steps.get_version.outputs.result }}
+          if [[ -z "$TAG" ]]; then
+            echo "Tag is empty"
+            exit 1
+          fi
+          git ls-remote --tags origin | awk '{print $2}'
+          if git ls-remote --tags origin | awk '{print $2}' | grep -q "refs/tags/$TAG$" ; then
+              echo "Tag '$TAG' ALREADY EXISTS on the remote"
+              exit 1
+          else
+              echo "Tag '$TAG' does not exist on the remote"
+          fi
+      - name: Check if harbor tag exists
+        run: |
+          TAG=${{ steps.get_version.outputs.result }}
+          registry=https://harbor.nymte.ch
+          repo_name=nym/node-status-api
+          if [[ -z $TAG ]]; then
+            echo "Tag is empty"
+            exit 1
+          fi
+          curl -su ${{ secrets.HARBOR_ROBOT_USERNAME }}:${{ secrets.HARBOR_ROBOT_SECRET }} "$registry/v2/$repo_name/tags/list" | jq
+          exists=$(curl -su ${{ secrets.HARBOR_ROBOT_USERNAME }}:${{ secrets.HARBOR_ROBOT_SECRET }} "$registry/v2/$repo_name/tags/list" | jq --arg tag $TAG '.tags | contains([$tag])' )
+          if [[ $exists = "true" ]]; then
+            echo "Version '$TAG' defined in Cargo.toml ALREADY EXISTS as tag in harbor repo"
+            exit 1
+          elif [[ $exists = "false" ]]; then
+            echo "Version '$TAG' doesn't exist on the remote"
+          else
+            echo "Unknown output '$exists'"
+            exit 1
+          fi
@@ -9,6 +9,8 @@ on:
    paths:
      - 'contracts/**'
      - 'common/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
      - '.github/workflows/ci-contracts.yml'

 jobs:
@@ -11,6 +11,8 @@ on:
 jobs:
  build:
    runs-on: arc-ubuntu-20.04
+    env:
+      RUSTUP_PERMIT_COPY_RENAME: 1
    defaults:
      run:
        working-directory: documentation/docs
@@ -16,6 +16,8 @@ on:
 jobs:
  build:
    runs-on: arc-ubuntu-20.04
+    env:
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - uses: actions/checkout@v4
      - uses: rlespinasse/github-slug-action@v3.x
@@ -42,7 +44,7 @@ jobs:
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
-          go-version: '1.20'
+          go-version: "1.23.7"

      - name: Install
        run: yarn
@@ -14,6 +14,7 @@ jobs:
    runs-on: arc-ubuntu-20.04
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - name: Install Dependencies (Linux)
        run: sudo apt-get update && sudo apt-get -y install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev squashfs-tools
@@ -30,6 +31,12 @@ jobs:
          override: true
          components: rustfmt, clippy

+      - name: Set debug to false
+        working-directory: nym-wallet
+        run: |
+          sed -i.bak '1s/^/\[profile.dev\]\ndebug = false\n\n/' Cargo.toml
+          git diff
+
      - name: Build all binaries
        uses: actions-rs/cargo@v1
        with:
@@ -1,6 +1,7 @@
 name: ci-sdk-wasm

 on:
+  workflow_dispatch:
  pull_request:
    paths:
      - 'wasm/**'
@@ -13,6 +14,7 @@ jobs:
    runs-on: arc-ubuntu-20.04
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - uses: actions/checkout@v4

@@ -31,7 +33,7 @@ jobs:
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
-          go-version: '1.20'
+          go-version: "1.23.7"

      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
@@ -44,6 +46,11 @@ jobs:
      - name: Install wasm-bindgen-cli
        run: cargo install wasm-bindgen-cli

+      - name: Set debug to false
+        run: |
+          sed -i.bak 's/\[profile.dev\]/\[profile.dev\]\ndebug = false/' Cargo.toml
+          git diff
+
      - name: "Build"
        run: make sdk-wasm-build

@@ -15,6 +15,7 @@ jobs:
    runs-on: ${{ matrix.os }}
    env:
      CARGO_TERM_COLOR: always
+      IPINFO_API_TOKEN: ${{ secrets.IPINFO_API_TOKEN }}
    continue-on-error: true
    steps:
      - name: Check out repository code
@@ -49,7 +49,7 @@ jobs:
            "build-tools;$SDK_BUILDTOOLS_VERSION"

      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@1.90.0
+        uses: dtolnay/rust-toolchain@1.100.0

      - name: Install rust android targets
        run: |
@@ -31,12 +31,7 @@ jobs:
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
-          go-version: "1.20"
-
-      - name: Install TinyGo
-        uses: acifani/setup-tinygo@v2
-        with:
-          tinygo-version: "0.27.0"
+          go-version: "1.23.7"

      - name: Install dependencies
        run: yarn
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-credential-proxy/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-network-monitor/Cargo.toml
@@ -31,7 +31,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.44.6
+        uses: mikefarah/yq@v4.45.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -51,4 +51,11 @@ ppa-private-key.b64
 ppa-private-key.asc
 nym-network-monitor/topology.json
 nym-network-monitor/__pycache__
-nym-network-monitor/*.key
+nym-network-monitor/*.key
+nym-network-monitor/.envrc
+nym-network-monitor/.envrc
+nym-api/redocly/formatted-openapi.json
+
+
+*.sqlite
+.build
@@ -1,83 +0,0 @@
-extends:
-  - minimal
-apis:
-  nym-api:
-    root: ./formatted-openapi.json
-rules:
-  # https://redocly.com/docs/cli/rules/oas/operation-summary
-  operation-summary: off
-  # https://redocly.com/docs/cli/rules/oas/security-defined
-  security-defined: off
-  struct: off
-  # https://redocly.com/docs/cli/rules/oas/operation-2xx-response
-  operation-2xx-response: off
-# rules:
-#   skip-warnings: true
-  # ignore:
-  # - path: /v1/gateways
-  #   method: get
-  # - path: /v1/gateways/blacklisted
-  #   method: get
-  # - path: /v1/mixnodes
-  #   method: get
-  # - path: /v1/mixnodes/active
-  #   method: get
-  # - path: /v1/mixnodes/active/detailed
-  #   method: get
-  # - path: /v1/mixnodes/blacklisted
-  #   method: get
-  # - path: /v1/mixnodes/detailed
-  #   method: get
-  # - path: /v1/mixnodes/rewarded
-  #   method: get
-  # - path: /v1/mixnodes/rewarded/detailed
-  #   method: get
-  # - path: /v1/gateways/described
-  #   method: get
-  # # network-monitor-status (deprecated)
-  # - path: /v1/status/gateway/{identity}/avg_uptime
-  #   method: GET
-  # - path: /v1/status/gateway/{identity}/core-status-count
-  #   method: GET
-  # - path: /v1/status/gateway/{identity}/history
-  #   method: GET
-  # - path: /v1/status/gateway/{identity}/report
-  #   method: GET
-  # - path: /v1/status/gateways/detailed
-  #   method: GET
-  # - path: /v1/status/gateways/detailed-unfiltered
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/avg_uptime
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/compute-reward-estimation
-  #   method: POST
-  # - path: /v1/status/mixnode/{mix_id}/core-status-count
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/history
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/report
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/reward-estimation
-  #   method: GET
-  # - path: /v1/status/mixnodes/detailed-unfiltered
-  #   method: GET
-  # # status
-  # - path: /v1/status/mixnode/{mix_id}/inclusion-probability
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/stake-saturation
-  #   method: GET
-  # - path: /v1/status/mixnode/{mix_id}/status
-  #   method: GET
-  # - path: /v1/status/mixnodes/active/detailed
-  #   method: GET
-  # - path: /v1/status/mixnodes/detailed
-  #   method: GET
-  # - path: /v1/status/mixnodes/inclusion-probability
-  #   method: GET
-  # - path: /v1/status/mixnodes/rewarded/detailed
-  #   method: GET
-  # # unstable nym nodes
-  # - path: /v1/unstable/nym-nodes/gateways/skimmed
-  #   method: get
-  # - path: /v1/unstable/nym-nodes/mixnodes/skimmed
-  #   method: get
@@ -4,12 +4,423 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.5-chokito] (2025-03-18)
+
+- build(deps): bump braces from 3.0.2 to 3.0.3 in /sdk/typescript/packages/nodejs-client ([#5611])
+- build(deps-dev): bump webpack-dev-middleware from 5.3.3 to 5.3.4 in /wasm/client/internal-dev ([#5610])
+- Export lane queue lengths in sdk ([#5609])
+- Chore/more payment watcher debug endpoints ([#5608])
+- build(deps): bump @babel/helpers from 7.24.4 to 7.26.10 ([#5606])
+- Chore/update bls12 381 fork ([#5605])
+- chore: change auth v2 timestamp skew and allow values from the future ([#5604])
+- Chore/payment watcher debug endpoints ([#5601])
+- Allow resetting all SURB sender tags ([#5600])
+- introduce internal tool for checking signer status ([#5598])
+- build(deps-dev): bump webpack from 5.77.0 to 5.98.0 in /wasm/mix-fetch/internal-dev ([#5597])
+- build(deps): bump body-parser and express in /wasm/mix-fetch/internal-dev ([#5596])
+- build(deps): bump serve-static and express in /wasm/mix-fetch/internal-dev ([#5594])
+- build(deps-dev): bump ws from 8.13.0 to 8.18.1 in /wasm/mix-fetch/internal-dev ([#5593])
+- build(deps): bump cookie and express in /wasm/client/internal-dev ([#5592])
+- build(deps): bump cookie and express in /wasm/mix-fetch/internal-dev ([#5591])
+- build(deps): bump braces from 3.0.2 to 3.0.3 in /wasm/zknym-lib/internal-dev ([#5590])
+- build(deps): bump webpack-dev-middleware from 5.3.3 to 5.3.4 in /wasm/zknym-lib/internal-dev ([#5589])
+- build(deps): bump tempfile from 3.17.1 to 3.18.0 ([#5588])
+- build(deps): bump tokio from 1.43.0 to 1.44.0 ([#5587])
+- build(deps): bump the patch-updates group with 8 updates ([#5585])
+- build(deps): bump ring from 0.17.9 to 0.17.13 ([#5583])
+- delete double memo field in send modal ([#5578])
+- Server Side internal DoT/DoH opt out ([#5577])
+- Rust SDK SURB example: change hardcoded file to tempdir ([#5576])
+- Add /v3/nym-nodes ([#5569])
+- chore: start sending v2 sphinx packets ([#5554])
+- build(deps): bump the patch-updates group across 1 directory with 14 updates ([#5549])
+- build(deps): bump uuid from 1.13.2 to 1.15.1 ([#5542])
+- build(deps): bump rs_merkle from 1.4.2 to 1.5.0 ([#5541])
+- feature: v2 authentication request ([#5537])
+- Set RUSTUP_PERMIT_COPY_RENAME ([#5533])
+- feature: disallow routing mix packets to nodes not present in the topology ([#5526])
+- Make "Memo" visible per default on send NYM ([#5524])
+- feat: make sure any terminated task kills the watcher and write run info to db ([#5517])
+- Another total_stake SQL fix ([#5516])
+- Fix total_stake on SQL update ([#5514])
+- build(deps): bump flate2 from 1.0.35 to 1.1.0 ([#5510])
+- build(deps): bump itertools from 0.13.0 to 0.14.0 ([#5509])
+- build(deps): bump the patch-updates group with 2 updates ([#5505])
+- Treat gateways as Nym Nodes ([#5504])
+- Update version in Cargo.toml ([#5503])
+- feat: use ct_eq for checking bearer token ([#5501])
+- Add extra args for the probe ([#5499])
+- Fix stats bug & remove HM caching ([#5495])
+- fix: Cargo.lock for contracts ([#5489])
+- Display error messages if IPv4 or IPv6 address not found on nymtun0 ([#5465])
+
+[#5611]: https://github.com/nymtech/nym/pull/5611
+[#5610]: https://github.com/nymtech/nym/pull/5610
+[#5609]: https://github.com/nymtech/nym/pull/5609
+[#5608]: https://github.com/nymtech/nym/pull/5608
+[#5606]: https://github.com/nymtech/nym/pull/5606
+[#5605]: https://github.com/nymtech/nym/pull/5605
+[#5604]: https://github.com/nymtech/nym/pull/5604
+[#5601]: https://github.com/nymtech/nym/pull/5601
+[#5600]: https://github.com/nymtech/nym/pull/5600
+[#5598]: https://github.com/nymtech/nym/pull/5598
+[#5597]: https://github.com/nymtech/nym/pull/5597
+[#5596]: https://github.com/nymtech/nym/pull/5596
+[#5594]: https://github.com/nymtech/nym/pull/5594
+[#5593]: https://github.com/nymtech/nym/pull/5593
+[#5592]: https://github.com/nymtech/nym/pull/5592
+[#5591]: https://github.com/nymtech/nym/pull/5591
+[#5590]: https://github.com/nymtech/nym/pull/5590
+[#5589]: https://github.com/nymtech/nym/pull/5589
+[#5588]: https://github.com/nymtech/nym/pull/5588
+[#5587]: https://github.com/nymtech/nym/pull/5587
+[#5585]: https://github.com/nymtech/nym/pull/5585
+[#5583]: https://github.com/nymtech/nym/pull/5583
+[#5578]: https://github.com/nymtech/nym/pull/5578
+[#5577]: https://github.com/nymtech/nym/pull/5577
+[#5576]: https://github.com/nymtech/nym/pull/5576
+[#5569]: https://github.com/nymtech/nym/pull/5569
+[#5554]: https://github.com/nymtech/nym/pull/5554
+[#5549]: https://github.com/nymtech/nym/pull/5549
+[#5542]: https://github.com/nymtech/nym/pull/5542
+[#5541]: https://github.com/nymtech/nym/pull/5541
+[#5537]: https://github.com/nymtech/nym/pull/5537
+[#5533]: https://github.com/nymtech/nym/pull/5533
+[#5526]: https://github.com/nymtech/nym/pull/5526
+[#5524]: https://github.com/nymtech/nym/pull/5524
+[#5517]: https://github.com/nymtech/nym/pull/5517
+[#5516]: https://github.com/nymtech/nym/pull/5516
+[#5514]: https://github.com/nymtech/nym/pull/5514
+[#5510]: https://github.com/nymtech/nym/pull/5510
+[#5509]: https://github.com/nymtech/nym/pull/5509
+[#5505]: https://github.com/nymtech/nym/pull/5505
+[#5504]: https://github.com/nymtech/nym/pull/5504
+[#5503]: https://github.com/nymtech/nym/pull/5503
+[#5501]: https://github.com/nymtech/nym/pull/5501
+[#5499]: https://github.com/nymtech/nym/pull/5499
+[#5495]: https://github.com/nymtech/nym/pull/5495
+[#5489]: https://github.com/nymtech/nym/pull/5489
+[#5465]: https://github.com/nymtech/nym/pull/5465
+
+## [2025.4-dorina-patched] (2025-03-06)
+
+- use legacy crypto for constructing SURB headers ([#5579])
+- bugfix: make sure to correctly decode response content when putting it into error message ([#5571])
+- Tweak surb management to be more conservative ([#5570])
+- Deserialize v5 authenticator requests ([#5568])
+- chore: additional logs when attempting to load ecash keys ([#5567])
+- add full response body to error message upon decoding failure ([#5566])
+- hotfix: ensure we bail on merkle leaves insertion upon missing data ([#5565])
+- feature: v2 authentication request (#5537) ([#5563])
+- Create authenticator v5 request/response types ([#5561])
+
+[#5579]: https://github.com/nymtech/nym/pull/5579
+[#5571]: https://github.com/nymtech/nym/pull/5571
+[#5570]: https://github.com/nymtech/nym/pull/5570
+[#5568]: https://github.com/nymtech/nym/pull/5568
+[#5567]: https://github.com/nymtech/nym/pull/5567
+[#5566]: https://github.com/nymtech/nym/pull/5566
+[#5565]: https://github.com/nymtech/nym/pull/5565
+[#5563]: https://github.com/nymtech/nym/pull/5563
+[#5561]: https://github.com/nymtech/nym/pull/5561
+
+## [2025.4-dorina] (2025-03-04)
+
+- fixed sphinx version metrics registration ([#5546])
+- Feature/chain status api ([#5539])
+- Add SURBs soft threshold ([#5535])
+- Simplify IPR v8 ([#5532])
+- Shared instance for DNS AsyncResolver ([#5523])
+- merge #5512 again after reverting due to incorrect rebase ([#5520])
+- cherry-pick 17d3ff2d775f61aee381d90a304ed416c08f33fc onto dorina ([#5519])
+- cherry-pick 6e5d0dac1b75413c5f09122b0d953f8ec6ef48df onto dorina ([#5518])
+- chore: workspace global panic preventing lints ([#5512])
+- bugfix: dont query for ecash apis unless necessary when spending ticketbooks ([#5508])
+- bugfix: bound check when recovering a reply SURB ([#5502])
+- chore: removed all old coconut code ([#5500])
+- IPR request types v8 ([#5498])
+- Support static routes for HTTP requests ([#5487])
+- build(deps): bump the patch-updates group across 1 directory with 3 updates ([#5482])
+- added missing import to doctest ([#5480])
+- adjusted TestSetup::new_complex to ensure bonded node's existence ([#5478])
+- Trigger contracts CI on main workspace Cargo changes ([#5477])
+- build(deps): bump http from 1.1.0 to 1.2.0 ([#5472])
+- build(deps): bump utoipa-swagger-ui from 8.0.3 to 8.1.0 ([#5471])
+- build(deps): bump colored from 2.1.0 to 2.2.0 ([#5470])
+- build(deps): bump celes from 2.4.0 to 2.5.0 ([#5469])
+- build(deps): bump the patch-updates group with 2 updates ([#5467])
+- build(deps): bump elliptic from 6.5.4 to 6.6.1 in /docker/typescript_client/upload_contract ([#5463])
+- Run cargo autoinherit ([#5460])
+- Fix clippy::precedence ([#5457])
+- Provide Interval context with node descriptor endpoints ([#5456])
+- fix: update fx average rate calcs to ignore 0 values ([#5454])
+- Feature/add gbp currency ([#5453])
+- Add helper to extract a list of sqlite files with journal files wal/shm ([#5452])
+- Add a middleware layer to the nym api allowing for data compression ([#5451])
+- Condense core API functionalities and enable gzip decompression for reqwest payloads ([#5450])
+- build(deps): bump uniffi_build from 0.25.3 to 0.29.0 ([#5448])
+- Upgrade tower to 0.5.2 ([#5446])
+- build(deps): bump hickory-proto from 0.24.2 to 0.24.3 ([#5444])
+- Seedable clients ([#5440])
+- build(deps): bump the patch-updates group across 1 directory with 10 updates ([#5439])
+- Remove all recv_with_delay and add shutdown condition to loops in client-core ([#5435])
+- Disable the test for checking the remaining bandwidth in nym-node-status-api ([#5425])
+- Dz nym node stats ([#5418])
+- build(deps): bump hyper from 1.4.1 to 1.6.0 ([#5416])
+- build(deps): bump publicsuffix from 2.2.3 to 2.3.0 ([#5367])
+- Nymnode entrypoint docker ([#5300])
+
+[#5546]: https://github.com/nymtech/nym/pull/5546
+[#5539]: https://github.com/nymtech/nym/pull/5539
+[#5535]: https://github.com/nymtech/nym/pull/5535
+[#5532]: https://github.com/nymtech/nym/pull/5532
+[#5523]: https://github.com/nymtech/nym/pull/5523
+[#5520]: https://github.com/nymtech/nym/pull/5520
+[#5519]: https://github.com/nymtech/nym/pull/5519
+[#5518]: https://github.com/nymtech/nym/pull/5518
+[#5512]: https://github.com/nymtech/nym/pull/5512
+[#5508]: https://github.com/nymtech/nym/pull/5508
+[#5502]: https://github.com/nymtech/nym/pull/5502
+[#5500]: https://github.com/nymtech/nym/pull/5500
+[#5498]: https://github.com/nymtech/nym/pull/5498
+[#5487]: https://github.com/nymtech/nym/pull/5487
+[#5482]: https://github.com/nymtech/nym/pull/5482
+[#5480]: https://github.com/nymtech/nym/pull/5480
+[#5478]: https://github.com/nymtech/nym/pull/5478
+[#5477]: https://github.com/nymtech/nym/pull/5477
+[#5472]: https://github.com/nymtech/nym/pull/5472
+[#5471]: https://github.com/nymtech/nym/pull/5471
+[#5470]: https://github.com/nymtech/nym/pull/5470
+[#5469]: https://github.com/nymtech/nym/pull/5469
+[#5467]: https://github.com/nymtech/nym/pull/5467
+[#5463]: https://github.com/nymtech/nym/pull/5463
+[#5460]: https://github.com/nymtech/nym/pull/5460
+[#5457]: https://github.com/nymtech/nym/pull/5457
+[#5456]: https://github.com/nymtech/nym/pull/5456
+[#5454]: https://github.com/nymtech/nym/pull/5454
+[#5453]: https://github.com/nymtech/nym/pull/5453
+[#5452]: https://github.com/nymtech/nym/pull/5452
+[#5451]: https://github.com/nymtech/nym/pull/5451
+[#5450]: https://github.com/nymtech/nym/pull/5450
+[#5448]: https://github.com/nymtech/nym/pull/5448
+[#5446]: https://github.com/nymtech/nym/pull/5446
+[#5444]: https://github.com/nymtech/nym/pull/5444
+[#5440]: https://github.com/nymtech/nym/pull/5440
+[#5439]: https://github.com/nymtech/nym/pull/5439
+[#5435]: https://github.com/nymtech/nym/pull/5435
+[#5425]: https://github.com/nymtech/nym/pull/5425
+[#5418]: https://github.com/nymtech/nym/pull/5418
+[#5416]: https://github.com/nymtech/nym/pull/5416
+[#5367]: https://github.com/nymtech/nym/pull/5367
+[#5300]: https://github.com/nymtech/nym/pull/5300
+
+## [2025.3-ruta] (2025-02-10)
+
+- Push down forget me to client configs ([#5431])
+- Fix statistics shutdown ([#5426])
+- Make wait_for_graceful_shutdown to be pub ([#5424])
+- Upgrade to thiserror 2.0 ([#5414])
+- build(deps): bump the patch-updates group across 1 directory with 9 updates ([#5406])
+- Relocate a validator api function ([#5401])
+- Send shutdown instead of panic when reaching max fail ([#5398])
+- Change Explorer URL to new smooshed nodes ([#5396])
+- reduce log severity for checking topology validity ([#5395])
+- MixnetClient can send ClientRequests ([#5381])
+- Fix missing path triggers for CI ([#5380])
+- Uncouple storage reference for bandwidth client ([#5372])
+- build(deps): bump tokio from 1.40.0 to 1.43.0 ([#5370])
+- DNS resolver configuration for internal HTTP client lookups ([#5355])
+- Update README.md ([#5328])
+- Update README.md ([#5327])
+
+[#5431]: https://github.com/nymtech/nym/pull/5431
+[#5426]: https://github.com/nymtech/nym/pull/5426
+[#5424]: https://github.com/nymtech/nym/pull/5424
+[#5414]: https://github.com/nymtech/nym/pull/5414
+[#5406]: https://github.com/nymtech/nym/pull/5406
+[#5401]: https://github.com/nymtech/nym/pull/5401
+[#5398]: https://github.com/nymtech/nym/pull/5398
+[#5396]: https://github.com/nymtech/nym/pull/5396
+[#5395]: https://github.com/nymtech/nym/pull/5395
+[#5381]: https://github.com/nymtech/nym/pull/5381
+[#5380]: https://github.com/nymtech/nym/pull/5380
+[#5372]: https://github.com/nymtech/nym/pull/5372
+[#5370]: https://github.com/nymtech/nym/pull/5370
+[#5355]: https://github.com/nymtech/nym/pull/5355
+[#5328]: https://github.com/nymtech/nym/pull/5328
+[#5327]: https://github.com/nymtech/nym/pull/5327
+
+## [2025.2-hu] (2025-02-04)
+
+- Feature/remove double spending bloomfilter ([#5417])
+- HU - Downgrade harmless log message from info to debug ([#5405])
+- lower default ticket verification quorum to 0.7 ([#5404])
+- Downgrade harmless log message from info to debug ([#5403])
+- Redirect from mixnode page to nodes page ([#5397])
+- chore :update version of chain watcher and validator rewarder ([#5394])
+- bugfix: correctly handle ignore epoch roles flag ([#5390])
+- bugfix: terminate mixnet socket listener on shutdown ([#5389])
+- feat: make client ignore dual mode nodes by default ([#5388])
+- Handle ecash network errors differently ([#5378])
+- Remove empty ephemeral keys ([#5376])
+- fixed sql migration for adding default message timestamp ([#5374])
+- Bind to [::] on nym-node for both IP versions ([#5361])
+- exposed NymApiClient method for obtaining node performance history ([#5360])
+- Client gateway selection ([#5358])
+- chore: refresh wasm sdk ([#5353])
+- chore: update indexed_db_futures ([#5347])
+- build(deps): bump mikefarah/yq from 4.44.6 to 4.45.1 ([#5342])
+- updated cosmrs and tendermint-rpc to their most recent versions ([#5339])
+- build(deps): bump ts-rs from 10.0.0 to 10.1.0 ([#5338])
+- build(deps): bump tempfile from 3.14.0 to 3.15.0 ([#5337])
+- build(deps): bump the patch-updates group with 8 updates ([#5336])
+- feature: introduce /load endpoint for self-reported quantised NymNode load ([#5326])
+- feature: `CancellationToken`-based shutdowns ([#5325])
+- Use expect in geodata test to give error message on failure ([#5314])
+- feature: periodically remove stale gateway messages ([#5312])
+- build(deps): bump the patch-updates group across 1 directory with 35 updates ([#5310])
+- Add dependabot assigns for the root cargo ecosystem ([#5297])
+- Move tun constants to network defaults ([#5286])
+- Include IPINFO_API_TOKEN in nightly CI ([#5285])
+- Nyx Chain Watcher ([#5274])
+- bugfix: remove unnecessary arguments for nym-api swagger endpoints ([#5272])
+- feature: nym topology revamp ([#5271])
+- Add windows to CI builds ([#5269])
+- http-api-client: deduplicate code ([#5267])
+- build(deps): bump http from 1.1.0 to 1.2.0 ([#5228])
+- NS API: add mixnet scraper ([#5200])
+- build(deps): bump criterion from 0.4.0 to 0.5.1 ([#4911])
+
+[#5417]: https://github.com/nymtech/nym/pull/5417
+[#5405]: https://github.com/nymtech/nym/pull/5405
+[#5404]: https://github.com/nymtech/nym/pull/5404
+[#5403]: https://github.com/nymtech/nym/pull/5403
+[#5397]: https://github.com/nymtech/nym/pull/5397
+[#5394]: https://github.com/nymtech/nym/pull/5394
+[#5390]: https://github.com/nymtech/nym/pull/5390
+[#5389]: https://github.com/nymtech/nym/pull/5389
+[#5388]: https://github.com/nymtech/nym/pull/5388
+[#5378]: https://github.com/nymtech/nym/pull/5378
+[#5376]: https://github.com/nymtech/nym/pull/5376
+[#5374]: https://github.com/nymtech/nym/pull/5374
+[#5361]: https://github.com/nymtech/nym/pull/5361
+[#5360]: https://github.com/nymtech/nym/pull/5360
+[#5358]: https://github.com/nymtech/nym/pull/5358
+[#5353]: https://github.com/nymtech/nym/pull/5353
+[#5347]: https://github.com/nymtech/nym/pull/5347
+[#5342]: https://github.com/nymtech/nym/pull/5342
+[#5339]: https://github.com/nymtech/nym/pull/5339
+[#5338]: https://github.com/nymtech/nym/pull/5338
+[#5337]: https://github.com/nymtech/nym/pull/5337
+[#5336]: https://github.com/nymtech/nym/pull/5336
+[#5326]: https://github.com/nymtech/nym/pull/5326
+[#5325]: https://github.com/nymtech/nym/pull/5325
+[#5314]: https://github.com/nymtech/nym/pull/5314
+[#5312]: https://github.com/nymtech/nym/pull/5312
+[#5310]: https://github.com/nymtech/nym/pull/5310
+[#5297]: https://github.com/nymtech/nym/pull/5297
+[#5286]: https://github.com/nymtech/nym/pull/5286
+[#5285]: https://github.com/nymtech/nym/pull/5285
+[#5274]: https://github.com/nymtech/nym/pull/5274
+[#5272]: https://github.com/nymtech/nym/pull/5272
+[#5271]: https://github.com/nymtech/nym/pull/5271
+[#5269]: https://github.com/nymtech/nym/pull/5269
+[#5267]: https://github.com/nymtech/nym/pull/5267
+[#5228]: https://github.com/nymtech/nym/pull/5228
+[#5200]: https://github.com/nymtech/nym/pull/5200
+[#4911]: https://github.com/nymtech/nym/pull/4911
+
+## [2025.1-reeses] (2025-01-15)
+
+- Feature, Future/legacy alert ([#5346])
+- chore: readjusted --mode behaviour to fix the regression ([#5331])
+- chore: apply 1.84 linter suggestions ([#5330])
+- bugfix: make sure refresh data key matches bond info ([#5329])
+- reduce log severity for number of packets being delayed ([#5321])
+- feat: warn users if node is run in exit mode only ([#5320])
+- Bugfix/contract version assignment ([#5318])
+- fixed client session histogram buckets ([#5316])
+- amend 250gb limit ([#5313])
+- feature: expand nym-node prometheus metrics ([#5298])
+- Cherry picked #5286 ([#5287])
+- Add close to credential storage ([#5283])
+- feature: wireguard metrics ([#5278])
+- Add PATCH support to nym-http-api-client ([#5260])
+- chore: removed legacy socks5 listener ([#5259])
+- bugfix: make sure to apply gateway score filtering when choosing initial node ([#5256])
+- Update TS bindings ([#5255])
+- Add conversion unit tests for auth msg ([#5251])
+- Add control messages to GatewayTransciver ([#5247])
+- Remove unneeded async function annotation ([#5246])
+- bugfix: make sure to update timestamp of last batch verification to prevent double redemption ([#5239])
+- Add FromStr impl for UserAgent ([#5236])
+- Extend swagger docs ([#5235])
+- TicketType derive Hash and Eq ([#5233])
+- Add fd callback to client core ([#5230])
+- Extend raw ws fd for gateway client ([#5218])
+- Shipping raw metrics to PG ([#5216])
+- Change sqlite journal mode to WAL ([#5213])
+- Derive serialize for UserAgent ([#5210])
+- Restore Location fields ([#5208])
+- better date serialization ([#5207])
+- Fix overflow ([#5204])
+- feature: hopefully final steps of the smoosh™️ ([#5201])
+- Fix overflow ([#5184])
+- NS API - Gateway stats scraping ([#5180])
+- introduced initial internal commands for nym-cli: ecash key and request generation ([#5174])
+- Move NS client to separate package under NS API ([#5171])
+- build(deps): bump micromatch from 4.0.4 to 4.0.8 in /testnet-faucet ([#4813])
+
+[#5346]: https://github.com/nymtech/nym/pull/5346
+[#5331]: https://github.com/nymtech/nym/pull/5331
+[#5330]: https://github.com/nymtech/nym/pull/5330
+[#5329]: https://github.com/nymtech/nym/pull/5329
+[#5321]: https://github.com/nymtech/nym/pull/5321
+[#5320]: https://github.com/nymtech/nym/pull/5320
+[#5318]: https://github.com/nymtech/nym/pull/5318
+[#5316]: https://github.com/nymtech/nym/pull/5316
+[#5313]: https://github.com/nymtech/nym/pull/5313
+[#5298]: https://github.com/nymtech/nym/pull/5298
+[#5287]: https://github.com/nymtech/nym/pull/5287
+[#5283]: https://github.com/nymtech/nym/pull/5283
+[#5278]: https://github.com/nymtech/nym/pull/5278
+[#5260]: https://github.com/nymtech/nym/pull/5260
+[#5259]: https://github.com/nymtech/nym/pull/5259
+[#5256]: https://github.com/nymtech/nym/pull/5256
+[#5255]: https://github.com/nymtech/nym/pull/5255
+[#5251]: https://github.com/nymtech/nym/pull/5251
+[#5247]: https://github.com/nymtech/nym/pull/5247
+[#5246]: https://github.com/nymtech/nym/pull/5246
+[#5239]: https://github.com/nymtech/nym/pull/5239
+[#5236]: https://github.com/nymtech/nym/pull/5236
+[#5235]: https://github.com/nymtech/nym/pull/5235
+[#5233]: https://github.com/nymtech/nym/pull/5233
+[#5230]: https://github.com/nymtech/nym/pull/5230
+[#5218]: https://github.com/nymtech/nym/pull/5218
+[#5216]: https://github.com/nymtech/nym/pull/5216
+[#5213]: https://github.com/nymtech/nym/pull/5213
+[#5210]: https://github.com/nymtech/nym/pull/5210
+[#5208]: https://github.com/nymtech/nym/pull/5208
+[#5207]: https://github.com/nymtech/nym/pull/5207
+[#5204]: https://github.com/nymtech/nym/pull/5204
+[#5201]: https://github.com/nymtech/nym/pull/5201
+[#5184]: https://github.com/nymtech/nym/pull/5184
+[#5180]: https://github.com/nymtech/nym/pull/5180
+[#5174]: https://github.com/nymtech/nym/pull/5174
+[#5171]: https://github.com/nymtech/nym/pull/5171
+[#4813]: https://github.com/nymtech/nym/pull/4813
+
+## [2024.14-crunch-patched] (2024-12-17)
+
+- Fixes an issue to allow previously registered clients to connect to latest nym-nodes
+- Fixes compatibility issues between nym-nodes and older clients
+
 ## [2024.14-crunch] (2024-12-11)

 - Merge/release/2024.14-crunch ([#5242])
 - bugfix: added explicit openapi servers to account for route prefixes ([#5237])
 - Further config score adjustments ([#5225])
- feature: remve any filtering on node semver ([#5224])
+- feature: remove any filtering on node semver ([#5224])
 - Backport #5218 ([#5220])
 - Derive serialize for UserAgent (#5210) ([#5217])
 - dont consider legacy nodes for rewarded set selection ([#5215])
@@ -188,7 +599,7 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://
 - bugfix/feature: added NymApiClient method to get all skimmed nodes ([#5062])
 - Merge1/release/2024.13 magura ([#5061])
 - added hacky routes to return nymnodes alongside legacy nodes ([#5051])
- bugfix: mark migrated gateways as rewarded in the previous epoch in case theyre in the rewarded set ([#5049])
+- bugfix: mark migrated gateways as rewarded in the previous epoch in case they're, their, there in the rewarded set ([#5049])
 - bugfix: adjust runtime storage migration ([#5047])
 - bugfix: supersede 'cb13be27f8f61d9ae74d924e85d2e6787895eb14' by using… ([#5046])
 - bugfix: restore default http port for nym-api ([#5045])
@@ -249,7 +660,7 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://
 - Fix broken build after merge ([#4937])
 - bugfix: correctly paginate through 'search_tx' endpoint ([#4936])
 - Add more conversions for responses of authenticator messages ([#4929])
- Directory Sevices v2.1 ([#4903])
+- Directory Services, Devices v2.1 ([#4903])
 - Migrate Legacy Node (Frontend)  ([#4826])
 - Fix critical issues SI84 and SI85 from Cure53 ([#4758])

@@ -633,7 +1044,7 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://
 - Remove stale peers ([#4640])
 - Add generic wg private network routing ([#4636])
 - Feature/new node endpoints ([#4635])
- standarised ContractBuildInformation and added it to all contracts ([#4631])
+- standardised ContractBuildInformation and added it to all contracts ([#4631])
 - validate nym-node public ips on startup ([#4630])
 - Bump defguard wg ([#4625])
 - Fix cargo warnings ([#4624])
@@ -1254,7 +1665,7 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://
 - clean-up nym-api startup arguments/flags to use clap 3 and its macro-derived arguments ([#2772])
 - renamed all references to validator_api to nym_api
 - renamed all references to nymd to nyxd ([#2696])
- all-binaries: standarised argument names (note: old names should still be accepted) ([#2762]
+- all-binaries: standardised argument names (note: old names should still be accepted) ([#2762]

 ### Fixed

@@ -1759,7 +2170,7 @@ The release also include some additional work for distributed key generation in
 - Explorer UI tests missing data-testid [\#903](https://github.com/nymtech/nym/pull/903) ([tommyv1987](https://github.com/tommyv1987))
 - Fix up Nym-Wallet README.md [\#899](https://github.com/nymtech/nym/pull/899) ([tommyv1987](https://github.com/tommyv1987))
 - Feature/batch delegator rewarding [\#898](https://github.com/nymtech/nym/pull/898) ([jstuczyn](https://github.com/jstuczyn))
- Bug mapp nodemap [\#897](https://github.com/nymtech/nym/pull/897) ([Aid19801](https://github.com/Aid19801))
+- Bug map nodemap [\#897](https://github.com/nymtech/nym/pull/897) ([Aid19801](https://github.com/Aid19801))
 - Bug fix/macos keyboard shortcuts [\#896](https://github.com/nymtech/nym/pull/896) ([fmtabbara](https://github.com/fmtabbara))
 - Add a Mobile Nav to the Network Explorer [\#895](https://github.com/nymtech/nym/pull/895) ([Aid19801](https://github.com/Aid19801))
 - Only use ts-rs in tests [\#894](https://github.com/nymtech/nym/pull/894) ([durch](https://github.com/durch))
@@ -48,13 +48,12 @@ members = [
    "common/credentials-interface",
    "common/crypto",
    "common/dkg",
-    "common/ecash-double-spending",
    "common/ecash-time",
    "common/execute",
    "common/exit-policy",
    "common/gateway-requests",
-    "common/gateway-storage",
    "common/gateway-stats-storage",
+    "common/gateway-storage",
    "common/http-api-client",
    "common/http-api-common",
    "common/inclusion-probability",
@@ -67,7 +66,6 @@ members = [
    "common/nym-id",
    "common/nym-metrics",
    "common/nym_offline_compact_ecash",
-    "common/nymcoconut",
    "common/nymsphinx",
    "common/nymsphinx/acknowledgements",
    "common/nymsphinx/addressing",
@@ -93,17 +91,34 @@ members = [
    "common/topology",
    "common/tun",
    "common/types",
+    "common/verloc",
    "common/wasm/client-core",
    "common/wasm/storage",
    "common/wasm/utils",
    "common/wireguard",
    "common/wireguard-types",
    "documentation/autodoc",
-    "explorer-api",
-    "explorer-api/explorer-api-requests",
-    "explorer-api/explorer-client",
+    # "explorer-api",
+    # "explorer-api/explorer-api-requests",
+    # "explorer-api/explorer-client",
    "gateway",
    "integrations/bity",
+    "nym-api",
+    "nym-api/nym-api-requests",
+    "nym-browser-extension/storage",
+    "nym-credential-proxy/nym-credential-proxy",
+    "nym-credential-proxy/nym-credential-proxy-requests",
+    "nym-credential-proxy/vpn-api-lib-wasm",
+    "nym-network-monitor",
+    "nym-node",
+    "nym-node-status-api/nym-node-status-agent",
+    "nym-node-status-api/nym-node-status-api",
+    "nym-node-status-api/nym-node-status-client",
+    "nym-node/nym-node-metrics",
+    "nym-node/nym-node-requests",
+    "nym-outfox",
+    "nym-validator-rewarder",
+    "nyx-chain-watcher",
    "sdk/ffi/cpp",
    "sdk/ffi/go",
    "sdk/ffi/shared",
@@ -112,27 +127,17 @@ members = [
    "service-providers/common",
    "service-providers/ip-packet-router",
    "service-providers/network-requester",
-    "nym-api",
-    "nym-api/nym-api-requests",
-    "nym-browser-extension/storage",
-    "nym-credential-proxy/nym-credential-proxy",
-    "nym-credential-proxy/nym-credential-proxy-requests",
-    "nym-credential-proxy/vpn-api-lib-wasm",
-    "nym-data-observatory",
-    "nym-network-monitor",
-    "nym-node",
-    "nym-node/nym-node-requests",
-    "nym-node/nym-node-metrics",
-    "nym-node-status-api/nym-node-status-agent",
-    "nym-node-status-api/nym-node-status-api",
-    "nym-node-status-api/nym-node-status-client",
-    "nym-outfox",
-    "nym-validator-rewarder",
    "tools/echo-server",
-    "tools/internal/ssl-inject",
+    "tools/echo-server",
+    "tools/internal/contract-state-importer/importer-cli",
+    "tools/internal/contract-state-importer/importer-contract",
+    "tools/internal/mixnet-connectivity-check",
    # "tools/internal/sdk-version-bump",
+    "tools/internal/ssl-inject",
+    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
+    "tools/internal/testnet-manager/dkg-bypass-contract", "tools/internal/validator-status-check",
    "tools/nym-cli",
    "tools/nym-id-cli",
    "tools/nym-nr-query",
@@ -143,24 +148,18 @@ members = [
    "wasm/mix-fetch",
    "wasm/node-tester",
    "wasm/zknym-lib",
-    "tools/echo-server",
-    "tools/internal/contract-state-importer/importer-cli",
-    "tools/internal/contract-state-importer/importer-contract",
-    "tools/internal/testnet-manager",
-    "tools/internal/testnet-manager/dkg-bypass-contract", "common/verloc", "tools/internal/mixnet-connectivity-check",
 ]

 default-members = [
    "clients/native",
    "clients/socks5",
-    "explorer-api",
    "nym-api",
    "nym-credential-proxy/nym-credential-proxy",
-    "nym-data-observatory",
    "nym-node",
    "nym-node-status-api/nym-node-status-agent",
    "nym-node-status-api/nym-node-status-api",
    "nym-validator-rewarder",
+    "nyx-chain-watcher",
    "service-providers/authenticator",
    "service-providers/ip-packet-router",
    "service-providers/network-requester",
@@ -171,7 +170,6 @@ exclude = [
    "explorer",
    "contracts",
    "nym-wallet",
-    "nym-vpn/ui/src-tauri",
    "cpu-cycles",
 ]

@@ -187,45 +185,49 @@ readme = "README.md"

 [workspace.dependencies]
 addr = "0.15.6"
+aead = "0.5.2"
 aes = "0.8.1"
 aes-gcm = "0.10.1"
 aes-gcm-siv = "0.11.1"
-aead = "0.5.2"
-anyhow = "1.0.90"
+ammonia = "4"
+anyhow = "1.0.97"
+arc-swap = "1.7.1"
 argon2 = "0.5.0"
-async-trait = "0.1.83"
-axum-client-ip = "0.6.1"
+async-trait = "0.1.88"
 axum = "0.7.5"
+axum-client-ip = "0.6.1"
 axum-extra = "0.9.4"
+axum-test = "16.2.0"
 base64 = "0.22.1"
+base85rs = "0.1.3"
 bincode = "1.3.3"
 bip39 = { version = "2.0.0", features = ["zeroize"] }
 bit-vec = "0.7.0"                                     # can we unify those?
 bitvec = "1.0.0"
-blake3 = "1.5.4"
+blake3 = "1.6.1"
 bloomfilter = "1.0.14"
 bs58 = "0.5.1"
 bytecodec = "0.4.15"
-bytes = "1.7.2"
+bytes = "1.10.1"
 cargo_metadata = "0.18.1"
-celes = "2.4.0"
+celes = "2.6.0"
 cfg-if = "1.0.0"
 chacha20 = "0.9.0"
 chacha20poly1305 = "0.10.1"
-chrono = "0.4.31"
+chrono = "0.4.40"
 cipher = "0.4.3"
-clap = "4.5.20"
+clap = "4.5.32"
 clap_complete = "4.5"
 clap_complete_fig = "4.5"
-colored = "2.0"
-comfy-table = "7.1.1"
-console = "0.15.8"
+colored = "2.2"
+comfy-table = "7.1.4"
+console = "0.15.11"
 console-subscriber = "0.1.1"
 console_error_panic_hook = "0.1"
 const-str = "0.5.6"
-const_format = "0.2.33"
-criterion = "0.4"
-csv = "1.3.0"
+const_format = "0.2.34"
+criterion = "0.5"
+csv = "1.3.1"
 ctr = "0.9.1"
 cupid = "0.6.1"
 curve25519-dalek = "4.1"
@@ -238,58 +240,60 @@ doc-comment = "0.3"
 dotenvy = "0.15.6"
 ecdsa = "0.16"
 ed25519-dalek = "2.1"
-etherparse = "0.13.0"
+encoding_rs = "0.8.35"
+env_logger = "0.11.7"
 envy = "0.4"
+etherparse = "0.13.0"
 eyre = "0.6.9"
 fastrand = "2.1.1"
-flate2 = "1.0.34"
-futures = "0.3.28"
+flate2 = "1.1.0"
+futures = "0.3.31"
 futures-util = "0.3"
 generic-array = "0.14.7"
 getrandom = "0.2.10"
-getset = "0.1.3"
+getset = "0.1.5"
 handlebars = "3.5.5"
 headers = "0.4.0"
 hex = "0.4.3"
 hex-literal = "0.3.3"
+hickory-resolver = "0.24.4"
 hkdf = "0.12.3"
 hmac = "0.12.1"
 http = "1"
 http-body-util = "0.1"
 httpcodec = "0.2.3"
-humantime = "2.1.0"
-humantime-serde = "1.1.1"
 human-repr = "1.1.0"
-hyper = "1.4.1"
+humantime = "2.2.0"
+humantime-serde = "1.1.1"
+hyper = "1.6.0"
 hyper-util = "0.1"
-indicatif = "0.17.8"
+indicatif = "0.17.11"
 inquire = "0.6.2"
 ip_network = "0.4.1"
 ipnetwork = "0.20"
 isocountry = "0.3.2"
-itertools = "0.13.0"
+itertools = "0.14.0"
 k256 = "0.13"
 lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
 ledger-transport-hid = "0.10.0"
 log = "0.4"
 maxminddb = "0.23.0"
-rs_merkle = "1.4.2"
 mime = "0.3.17"
 moka = { version = "0.12", features = ["future"] }
 nix = "0.27.1"
 notify = "5.1.0"
 okapi = "0.7.0"
-once_cell = "1.20.2"
+once_cell = "1.21.1"
 opentelemetry = "0.19.0"
 opentelemetry-jaeger = "0.18.0"
 parking_lot = "0.12.3"
 pem = "0.8"
 petgraph = "0.6.5"
 pin-project = "1.1"
-pin-project-lite = "0.2.14"
+pin-project-lite = "0.2.16"
 pretty_env_logger = "0.4.0"
-publicsuffix = "2.2.3"
+publicsuffix = "2.3.0"
 quote = "1"
 rand = "0.8.5"
 rand_chacha = "0.3"
@@ -303,57 +307,61 @@ reqwest = { version = "0.12.4", default-features = false }
 rocket = "0.5.0"
 rocket_cors = "0.6.0"
 rocket_okapi = "0.8.0"
+rs_merkle = "1.5.0"
 safer-ffi = "0.1.13"
-schemars = "0.8.21"
-semver = "1.0.23"
-serde = "1.0.211"
-serde_bytes = "0.11.15"
+schemars = "0.8.22"
+semver = "1.0.26"
+serde = "1.0.219"
+serde_bytes = "0.11.17"
 serde_derive = "1.0"
-serde_json = "1.0.132"
-serde_json_path = "0.7.1"
+serde_json = "1.0.140"
+serde_json_path = "0.7.2"
 serde_repr = "0.1"
 serde_with = "3.9.0"
 serde_yaml = "0.9.25"
 sha2 = "0.10.8"
 si-scale = "0.2.3"
-sphinx-packet = "0.1.1"
+sphinx-packet = "=0.3.2"
 sqlx = "0.7.4"
 strum = "0.26"
 strum_macros = "0.26"
 subtle-encoding = "0.5"
 syn = "1"
-sysinfo = "0.30.13"
+sysinfo = "0.33.0"
 tap = "1.0.1"
-tar = "0.4.42"
-tempfile = "3.14"
-thiserror = "1.0.64"
-time = "0.3.30"
-tokio = "1.39"
-tokio-stream = "0.1.16"
+tar = "0.4.44"
+tempfile = "3.19"
+thiserror = "2.0"
+time = "0.3.39"
+tokio = "1.44"
+tokio-postgres = "0.7"
+tokio-stream = "0.1.17"
 tokio-test = "0.4.4"
 tokio-tun = "0.11.5"
 tokio-tungstenite = { version = "0.20.1" }
-tokio-util = "0.7.12"
-toml = "0.8.14"
-tower = "0.4.13"
+tokio-util = "0.7.14"
+toml = "0.8.20"
+tower = "0.5.2"
 tower-http = "0.5.2"
-tracing = "0.1.37"
-tracing-opentelemetry = "0.19.0"
-tracing-subscriber = "0.3.16"
-tracing-tree = "0.2.2"
+tracing = "0.1.41"
 tracing-log = "0.2"
-ts-rs = "10.0.0"
+tracing-opentelemetry = "0.19.0"
+tracing-subscriber = "0.3.19"
+tracing-tree = "0.2.2"
+ts-rs = "10.1.0"
 tungstenite = { version = "0.20.1", default-features = false }
+uniffi = "0.29.0"
+uniffi_build = "0.29.0"
 url = "2.5"
 utoipa = "5.2"
-utoipa-swagger-ui = "8.0"
+utoipa-swagger-ui = "8.1"
 utoipauto = "0.2"
 uuid = "*"
 vergen = { version = "=8.3.1", default-features = false }
 walkdir = "2"
-wasm-bindgen-test = "0.3.43"
+wasm-bindgen-test = "0.3.49"
 x25519-dalek = "2.0.0"
-zeroize = "1.6.0"
+zeroize = "1.8.1"

 prometheus = { version = "0.13.0" }

@@ -361,9 +369,9 @@ prometheus = { version = "0.13.0" }
 # unfortunately until https://github.com/zkcrypto/bls12_381/issues/10 is resolved, we have to rely on the fork
 # as we need to be able to serialize Gt so that we could create the lookup table for baby-step-giant-step algorithm
 # plus to make our live easier we need serde support from https://github.com/zkcrypto/bls12_381/pull/125
-bls12_381 = { git = "https://github.com/jstuczyn/bls12_381", default-features = false, branch = "temp/experimental-serdect" }
+bls12_381 = { git = "https://github.com/jstuczyn/bls12_381", default-features = false, branch = "temp/experimental-serdect-updated" }
 group = { version = "0.13.0", default-features = false }
-ff = { version = "0.13.0", default-features = false }
+ff = { version = "0.13.1", default-features = false }
 subtle = "2.5.0"

 # cosmwasm-related
@@ -382,31 +390,26 @@ cw4 = { version = "=1.1.2" }
 cw-controllers = { version = "=1.1.0" }

 # cosmrs-related
-bip32 = { version = "0.5.2", default-features = false }
+bip32 = { version = "0.5.3", default-features = false }

-# temporarily using a fork again (yay.) because we need staking and slashing support (which are already on main but not released)
-# plus response message parsing (which is, as of the time of writing this message, waiting to get merged)
-#cosmrs = { path = "../cosmos-rust-fork/cosmos-rust/cosmrs" }
-cosmrs = { git = "https://github.com/cosmos/cosmos-rust", rev = "4b1332e6d8258ac845cef71589c8d362a669675a" } # unfortuntely we need a fork by yours truly to get the staking support
-tendermint = "0.37.0"                                                                                        # same version as used by cosmrs
-tendermint-rpc = "0.37.0"                                                                                    # same version as used by cosmrs
-prost = { version = "0.12", default-features = false }
+
+cosmrs = { version = "0.21.1" }
+tendermint = "0.40.0"
+tendermint-rpc = "0.40.0"
+prost = { version = "0.13", default-features = false }

 # wasm-related dependencies
 gloo-utils = "0.2.0"
-gloo-net = "0.5.0"
+gloo-net = "0.6.0"

-# use a separate branch due to feature unification failures
-# this is blocked until the upstream removes outdates `wasm_bindgen` feature usage
-# indexed_db_futures = "0.4.1"
-indexed_db_futures = { git = "https://github.com/TiemenSch/rust-indexed-db", branch = "update-uuid" }
-js-sys = "0.3.70"
+indexed_db_futures = "0.6.1"
+js-sys = "0.3.76"
 serde-wasm-bindgen = "0.6.5"
 tsify = "0.4.5"
-wasm-bindgen = "0.2.95"
-wasm-bindgen-futures = "0.4.45"
-wasmtimer = "0.2.0"
-web-sys = "0.3.72"
+wasm-bindgen = "0.2.99"
+wasm-bindgen-futures = "0.4.49"
+wasmtimer = "0.4.1"
+web-sys = "0.3.76"

 # Profile settings for individual crates

@@ -434,3 +437,13 @@ opt-level = 'z'
 [profile.release.package.mix-fetch-wasm]
 # lto = true
 opt-level = 'z'
+
+[workspace.lints.clippy]
+unwrap_used = "deny"
+expect_used = "deny"
+todo = "deny"
+dbg_macro = "deny"
+exit = "deny"
+panic = "deny"
+unimplemented = "deny"
+unreachable = "deny"
@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
@@ -13,8 +13,8 @@ The platform is composed of multiple Rust crates. Top-level executable binary cr
 * `nym-client` - an executable which you can build into your own applications. Use it for interacting with Nym nodes.
 * `nym-socks5-client` - a Socks5 proxy you can run on your machine and use with existing applications.
 * `nym-explorer` - a (projected) block explorer and (existing) mixnet viewer.
-* `nym-wallet` - a desktop wallet implemented using the [Tauri](https://tauri.studio/en/docs/about/intro) framework.
-* `nym-cli` - a tool for interacting with the network from the CLI. 
+* `nym-wallet` - a desktop wallet implemented using the [Tauri](https://tauri.app)) framework.
+* `nym-cli` - a tool for interacting with the network from the CLI.
 <!-- coming soon
 * `nym-network-monitor` - sends packets through the full system to check that they are working as expected, and stores node uptime histories as the basis of a rewards system ("mixmining" or "proof-of-mixing").
 -->
@@ -42,10 +42,10 @@ client ───► Gateway ──┘  mix  │  mix  ┌─►mix ───►

 References for developers:

-* [Dev Docs](https://nymtech.net/docs/developers)
-* [SDKs](https://nymtech.net/docs/developers/rust)
-* [Network Docs](https://nymtech.net/docs/network)
-* [Release Cycle - git flow](https://nymtech.net/docs/operators/release-cycle)
+* [Dev Docs](https://nym.com/docs/developers)
+* [SDKs](https://nym.com/docs/developers/rust)
+* [Network Docs](https://nym.com/docs/network)
+* [Release Cycle - git flow](https://nym.com/docs/operators/release-cycle)

 ### Developer chat

@@ -66,4 +66,14 @@ As a general approach, licensing is as follows this pattern:
 - libraries and components are Apache 2.0 or MIT
 - documentation is Apache 2.0 or CC0-1.0

-Nym Node Operators and Validators Temrs and Conditions can be found [here](https://nymtech.net/terms-and-conditions/operators/v1.0.0).
+Nym Node Operators and Validators Terms and Conditions can be found [here](https://nym.com/operators-validators-terms).
+
+## Getting Started
+
+```bash
+yarn install
+```
+
+```bash
+yarn build
+```
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.45"
+version = "1.1.51"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -56,7 +56,7 @@ pub fn default_data_directory<P: AsRef<Path>>(id: P) -> PathBuf {
        .join(DEFAULT_DATA_DIR)
 }

-#[derive(Debug, Deserialize, PartialEq, Serialize)]
+#[derive(Debug, Deserialize, PartialEq, Serialize, Clone)]
 pub struct Config {
    #[serde(flatten)]
    pub base: BaseClientConfig,
@@ -94,6 +94,10 @@ impl CliClientConfig for Config {
 }

 impl Config {
+    pub fn base(&self) -> BaseClientConfig {
+        self.base.clone()
+    }
+
    pub fn new<S: AsRef<str>>(id: S) -> Self {
        Config {
            base: BaseClientConfig::new(id.as_ref(), env!("CARGO_PKG_VERSION")),
@@ -209,7 +213,7 @@ impl SocketType {
    }
 }

-#[derive(Debug, Deserialize, PartialEq, Eq, Serialize)]
+#[derive(Debug, Deserialize, PartialEq, Eq, Serialize, Clone)]
 #[serde(default, deny_unknown_fields)]
 pub struct Socket {
    pub socket_type: SocketType,
@@ -107,5 +107,8 @@ enabled = {{ debug.stats_reporting.enabled }}
 provider_address = '{{ debug.stats_reporting.provider_address }}'
 reporting_interval = '{{ debug.stats_reporting.reporting_interval }}'

+[debug.forget_me]
+client = {{ debug.forget_me.client }}
+stats = {{ debug.forget_me.stats }}

 "#;
@@ -20,7 +20,7 @@ pub use nym_sphinx::addressing::clients::Recipient;

 pub mod config;

-type NativeClientBuilder<'a> = BaseClientBuilder<'a, QueryHttpRpcNyxdClient, OnDiskPersistent>;
+type NativeClientBuilder = BaseClientBuilder<QueryHttpRpcNyxdClient, OnDiskPersistent>;

 pub struct SocketClient {
    /// Client configuration options, including, among other things, packet sending rates,
@@ -32,6 +32,10 @@ pub struct SocketClient {
 }

 impl SocketClient {
+    pub fn config(&self) -> Config {
+        self.config.clone()
+    }
+
    pub fn new(config: Config, custom_mixnet: Option<PathBuf>) -> Self {
        SocketClient {
            config,
@@ -45,7 +49,7 @@ impl SocketClient {
        client_output: ClientOutput,
        client_state: ClientState,
        self_address: &Recipient,
-        shutdown: nym_task::TaskClient,
+        task_client: nym_task::TaskClient,
        packet_type: PacketType,
    ) {
        info!("Starting websocket listener...");
@@ -73,10 +77,15 @@ impl SocketClient {
            shared_lane_queue_lengths,
            reply_controller_sender,
            Some(packet_type),
+            task_client.fork("websocket_handler"),
        );

-        websocket::Listener::new(config.socket.host, config.socket.listening_port)
-            .start(websocket_handler, shutdown);
+        websocket::Listener::new(
+            config.socket.host,
+            config.socket.listening_port,
+            task_client.with_suffix("websocket_listener"),
+        )
+        .start(websocket_handler);
    }

    /// blocking version of `start_socket` method. Will run forever (or until SIGINT is sent)
@@ -108,8 +117,9 @@ impl SocketClient {
        let storage = self.initialise_storage().await?;
        let user_agent = nym_bin_common::bin_info!().into();

-        let mut base_client = BaseClientBuilder::new(&self.config.base, storage, dkg_query_client)
-            .with_user_agent(user_agent);
+        let mut base_client =
+            BaseClientBuilder::new(self.config().base(), storage, dkg_query_client)
+                .with_user_agent(user_agent);

        if let Some(custom_mixnet) = &self.custom_mixnet {
            base_client = base_client.with_stored_topology(custom_mixnet)?;
@@ -82,6 +82,7 @@ impl From<Init> for OverrideConfig {
            nyxd_urls: init_config.common_args.nyxd_urls,
            enabled_credentials_mode: init_config.common_args.enabled_credentials_mode,
            stats_reporting_address: init_config.common_args.stats_reporting_address,
+            forget_me: init_config.common_args.forget_me.into(),
        }
    }
 }
@@ -16,6 +16,7 @@ use nym_bin_common::completions::{fig_generate, ArgShell};
 use nym_client::client::Recipient;
 use nym_client_core::cli_helpers::CliClient;
 use nym_client_core::client::base_client::storage::migration_helpers::v1_1_33;
+use nym_client_core::config::ForgetMe;
 use nym_config::OptionalSet;
 use std::error::Error;
 use std::net::IpAddr;
@@ -106,6 +107,7 @@ pub(crate) struct OverrideConfig {
    nyxd_urls: Option<Vec<url::Url>>,
    enabled_credentials_mode: Option<bool>,
    stats_reporting_address: Option<Recipient>,
+    forget_me: ForgetMe,
 }

 pub(crate) async fn execute(args: Cli) -> Result<(), Box<dyn Error + Send + Sync>> {
@@ -133,6 +135,7 @@ pub(crate) fn override_config(config: Config, args: OverrideConfig) -> Config {
            args.fastmode,
        )
        .with_base(BaseClientConfig::with_disabled_cover_traffic, args.no_cover)
+        .with_base(BaseClientConfig::with_forget_me, args.forget_me)
        .with_optional(Config::with_port, args.port)
        .with_optional(Config::with_host, args.host)
        .with_optional_custom_env_ext(
@@ -41,6 +41,7 @@ impl From<Run> for OverrideConfig {
            nyxd_urls: run_config.common_args.nyxd_urls,
            enabled_credentials_mode: run_config.common_args.enabled_credentials_mode,
            stats_reporting_address: run_config.common_args.stats_reporting_address,
+            forget_me: run_config.common_args.forget_me.into(),
        }
    }
 }
@@ -19,6 +19,7 @@ use nym_sphinx::receiver::ReconstructedMessage;
 use nym_task::connections::{
    ConnectionCommand, ConnectionCommandSender, ConnectionId, LaneQueueLengths, TransmissionLane,
 };
+use nym_task::TaskClient;
 use std::time::Duration;
 use tokio::net::TcpStream;
 use tokio::time::Instant;
@@ -43,9 +44,11 @@ pub(crate) struct HandlerBuilder {
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
    packet_type: Option<PacketType>,
+    task_client: TaskClient,
 }

 impl HandlerBuilder {
+    #[allow(clippy::too_many_arguments)]
    pub(crate) fn new(
        msg_input: InputMessageSender,
        client_connection_tx: ConnectionCommandSender,
@@ -54,6 +57,7 @@ impl HandlerBuilder {
        lane_queue_lengths: LaneQueueLengths,
        reply_controller_sender: ReplyControllerSender,
        packet_type: Option<PacketType>,
+        task_client: TaskClient,
    ) -> Self {
        Self {
            msg_input,
@@ -63,11 +67,14 @@ impl HandlerBuilder {
            lane_queue_lengths,
            reply_controller_sender,
            packet_type,
+            task_client,
        }
    }

    // TODO: make sure we only ever have one active handler
    pub fn create_active_handler(&self) -> Handler {
+        let mut task_client = self.task_client.fork("active_handler");
+        task_client.disarm();
        Handler {
            msg_input: self.msg_input.clone(),
            client_connection_tx: self.client_connection_tx.clone(),
@@ -78,6 +85,7 @@ impl HandlerBuilder {
            lane_queue_lengths: self.lane_queue_lengths.clone(),
            reply_controller_sender: self.reply_controller_sender.clone(),
            packet_type: self.packet_type,
+            task_client,
        }
    }
 }
@@ -92,16 +100,18 @@ pub(crate) struct Handler {
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
    packet_type: Option<PacketType>,
+    task_client: TaskClient,
 }

 impl Drop for Handler {
    fn drop(&mut self) {
-        if self
+        if let Err(err) = self
            .buffer_requester
            .unbounded_send(ReceivedBufferMessage::ReceiverDisconnect)
-            .is_err()
        {
-            error!("we failed to disconnect the receiver from the buffer! presumably the shutdown procedure has been initiated!")
+            if !self.task_client.is_shutdown_poll() {
+                error!("failed to disconnect the receiver from the buffer: {err}");
+            }
        }
    }
 }
@@ -125,10 +135,23 @@ impl Handler {
        };

        // get the number of pending replies waiting for reply surbs
-        let reply_queue_length = self
+        let reply_queue_length = match self
            .reply_controller_sender
            .get_lane_queue_length(connection_id)
-            .await;
+            .await
+        {
+            Ok(length) => length,
+            Err(err) => {
+                if !self.task_client.is_shutdown_poll() {
+                    error!(
+                        "Failed to get reply queue length for connection {connection_id}: {err}"
+                    );
+                }
+                // We're just going to assume that the queue is empty, and I think that's okay
+                // during shutdown.
+                0
+            }
+        };

        let queue_length = base_length + reply_queue_length;

@@ -168,10 +191,11 @@ impl Handler {

        // the ack control is now responsible for chunking, etc.
        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type);
-        self.msg_input
-            .send(input_msg)
-            .await
-            .expect("InputMessageReceiver has stopped receiving!");
+        if let Err(err) = self.msg_input.send(input_msg).await {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send message to the input buffer: {err}");
+            }
+        }

        // Only reply back with a `LaneQueueLength` if the sender providided a connection id
        let TransmissionLane::ConnectionId(connection_id) = lane else {
@@ -200,10 +224,11 @@ impl Handler {

        let input_msg =
            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);
-        self.msg_input
-            .send(input_msg)
-            .await
-            .expect("InputMessageReceiver has stopped receiving!");
+        if let Err(err) = self.msg_input.send(input_msg).await {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send anonymous message to the input buffer: {err}");
+            }
+        }

        // Only reply back with a `LaneQueueLength` if the sender providided a connection id
        let TransmissionLane::ConnectionId(connection_id) = lane else {
@@ -227,10 +252,11 @@ impl Handler {
        });

        let input_msg = InputMessage::new_reply(recipient_tag, message, lane, self.packet_type);
-        self.msg_input
-            .send(input_msg)
-            .await
-            .expect("InputMessageReceiver has stopped receiving!");
+        if let Err(err) = self.msg_input.send(input_msg).await {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send reply message to the input buffer: {err}");
+            }
+        }

        // Only reply back with a `LaneQueueLength` if the sender providided a connection id
        let TransmissionLane::ConnectionId(connection_id) = lane else {
@@ -245,9 +271,14 @@ impl Handler {
    }

    fn handle_closed_connection(&self, connection_id: u64) -> Option<ServerResponse> {
-        self.client_connection_tx
+        if let Err(err) = self
+            .client_connection_tx
            .unbounded_send(ConnectionCommand::Close(connection_id))
-            .unwrap();
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send close connection command: {err}");
+            }
+        }
        None
    }

@@ -362,11 +393,10 @@ impl Handler {
        }
    }

-    async fn listen_for_requests(
-        &mut self,
-        mut msg_receiver: ReconstructedMessagesReceiver,
-        mut task_client: nym_task::TaskClient,
-    ) {
+    async fn listen_for_requests(&mut self, mut msg_receiver: ReconstructedMessagesReceiver) {
+        let mut task_client = self.task_client.fork("select");
+        task_client.disarm();
+
        while !task_client.is_shutdown() {
            tokio::select! {
                // we can either get a client request from the websocket
@@ -415,15 +445,7 @@ impl Handler {
    }

    // consume self to make sure `drop` is called after this is done
-    pub(crate) async fn handle_connection(
-        mut self,
-        socket: TcpStream,
-        mut task_client: nym_task::TaskClient,
-    ) {
-        // We don't want a crash in the connection handler to trigger a shutdown of the whole
-        // process.
-        task_client.disarm();
-
+    pub(crate) async fn handle_connection(mut self, socket: TcpStream) {
        let ws_stream = match accept_async(socket).await {
            Ok(ws_stream) => ws_stream,
            Err(err) => {
@@ -436,14 +458,18 @@ impl Handler {
        let (reconstructed_sender, reconstructed_receiver) = mpsc::unbounded();

        // tell the buffer to start sending stuff to us
-        self.buffer_requester
-            .unbounded_send(ReceivedBufferMessage::ReceiverAnnounce(
-                reconstructed_sender,
-            ))
-            .expect("the buffer request failed!");
+        if let Err(err) =
+            self.buffer_requester
+                .unbounded_send(ReceivedBufferMessage::ReceiverAnnounce(
+                    reconstructed_sender,
+                ))
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("failed to announce the receiver to the buffer: {err}");
+            }
+        }

-        self.listen_for_requests(reconstructed_receiver, task_client)
-            .await;
+        self.listen_for_requests(reconstructed_receiver).await;
    }
 }

@@ -3,6 +3,7 @@

 use super::handler::HandlerBuilder;
 use log::*;
+use nym_task::TaskClient;
 use std::net::IpAddr;
 use std::{net::SocketAddr, process, sync::Arc};
 use tokio::io::AsyncWriteExt;
@@ -22,21 +23,19 @@ impl State {
 pub(crate) struct Listener {
    address: SocketAddr,
    state: State,
+    task_client: TaskClient,
 }

 impl Listener {
-    pub(crate) fn new(host: IpAddr, port: u16) -> Self {
+    pub(crate) fn new(host: IpAddr, port: u16, task_client: TaskClient) -> Self {
        Listener {
            address: SocketAddr::new(host, port),
            state: State::AwaitingConnection,
+            task_client,
        }
    }

-    pub(crate) async fn run(
-        &mut self,
-        handler: HandlerBuilder,
-        mut task_client: nym_task::TaskClient,
-    ) {
+    pub(crate) async fn run(&mut self, handler: HandlerBuilder) {
        let tcp_listener = match tokio::net::TcpListener::bind(self.address).await {
            Ok(listener) => listener,
            Err(err) => {
@@ -47,11 +46,11 @@ impl Listener {

        let notify = Arc::new(Notify::new());

-        loop {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                // When the handler finishes we check if shutdown is signalled
                _ = notify.notified() => {
-                    if task_client.is_shutdown() {
+                    if self.task_client.is_shutdown() {
                        log::trace!("Websocket listener: detected shutdown after connection closed");
                        break;
                    }
@@ -60,7 +59,7 @@ impl Listener {
                }
                // ... but when there is no connected client at the time of shutdown being
                // signalled, we handle it here.
-                _ = task_client.recv() => {
+                _ = self.task_client.recv() => {
                    if !self.state.is_connected() {
                        log::trace!("Not connected: shutting down");
                        break;
@@ -88,9 +87,8 @@ impl Listener {
                                // hanging because the executor doesn't come back here
                                let notify_clone = Arc::clone(&notify);
                                let fresh_handler = handler.create_active_handler();
-                                let task_client_handler = task_client.clone();
                                tokio::spawn(async move {
-                                    fresh_handler.handle_connection(socket, task_client_handler).await;
+                                    fresh_handler.handle_connection(socket).await;
                                    notify_clone.notify_one();
                                });
                                self.state = State::Connected;
@@ -104,13 +102,9 @@ impl Listener {
        log::debug!("Websocket listener: Exiting");
    }

-    pub(crate) fn start(
-        mut self,
-        handler: HandlerBuilder,
-        shutdown: nym_task::TaskClient,
-    ) -> JoinHandle<()> {
+    pub(crate) fn start(mut self, handler: HandlerBuilder) -> JoinHandle<()> {
        info!("Running websocket on {:?}", self.address.to_string());

-        tokio::spawn(async move { self.run(handler, shutdown).await })
+        tokio::spawn(async move { self.run(handler).await })
    }
 }
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.45"
+version = "1.1.51"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 description = "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address"
 edition = "2021"
@@ -93,6 +93,7 @@ impl From<Init> for OverrideConfig {
            enabled_credentials_mode: init_config.common_args.enabled_credentials_mode,
            outfox: false,
            stats_reporting_address: init_config.common_args.stats_reporting_address,
+            forget_me: init_config.common_args.forget_me.into(),
        }
    }
 }
@@ -17,7 +17,7 @@ use nym_bin_common::completions::{fig_generate, ArgShell};
 use nym_client_core::cli_helpers::CliClient;
 use nym_client_core::client::base_client::storage::migration_helpers::v1_1_33;
 use nym_client_core::client::topology_control::geo_aware_provider::CountryGroup;
-use nym_client_core::config::{GroupBy, TopologyStructure};
+use nym_client_core::config::{ForgetMe, GroupBy, TopologyStructure};
 use nym_config::OptionalSet;
 use nym_sphinx::addressing::Recipient;
 use nym_sphinx::params::{PacketSize, PacketType};
@@ -113,6 +113,7 @@ pub(crate) struct OverrideConfig {
    enabled_credentials_mode: Option<bool>,
    outfox: bool,
    stats_reporting_address: Option<Recipient>,
+    forget_me: ForgetMe,
 }

 pub(crate) async fn execute(args: Cli) -> Result<(), Box<dyn Error + Send + Sync>> {
@@ -179,6 +180,7 @@ pub(crate) fn override_config(config: Config, args: OverrideConfig) -> Config {
            BaseClientConfig::with_topology_structure,
            topology_structure,
        )
+        .with_base(BaseClientConfig::with_forget_me, args.forget_me)
        .with_optional(Config::with_anonymous_replies, args.use_anonymous_replies)
        .with_optional(Config::with_port, args.port)
        .with_optional(Config::with_ip, args.ip)
@@ -65,6 +65,7 @@ impl From<Run> for OverrideConfig {
            enabled_credentials_mode: run_config.common_args.enabled_credentials_mode,
            outfox: run_config.outfox,
            stats_reporting_address: run_config.common_args.stats_reporting_address,
+            forget_me: run_config.common_args.forget_me.into(),
        }
    }
 }
@@ -113,4 +113,8 @@ enabled = {{ core.debug.stats_reporting.enabled }}
 provider_address = '{{ core.debug.stats_reporting.provider_address }}'
 reporting_interval = '{{ core.debug.stats_reporting.reporting_interval }}'

+[core.debug.forget_me]
+client = {{ core.debug.forget_me.client }}
+stats = {{ core.debug.forget_me.stats }}
+
 "#;
@@ -1,2 +1,3 @@
 allow-unwrap-in-tests = true
 allow-expect-in-tests = true
+allow-panic-in-tests = true
@@ -6,14 +6,15 @@ pub mod v1;
 pub mod v2;
 pub mod v3;
 pub mod v4;
+pub mod v5;

 mod error;
 mod util;

 pub use error::Error;
-pub use v4 as latest;
+pub use v5 as latest;

-pub const CURRENT_VERSION: u8 = 4;
+pub const CURRENT_VERSION: u8 = 5;

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -8,8 +8,8 @@ use nym_sphinx::addressing::clients::Recipient;
 use nym_wireguard_types::PeerPublicKey;

 use crate::{
-    v1, v2, v3,
-    v4::{self, registration::IpPair},
+    v1, v2, v3, v4,
+    v5::{self, registration::IpPair},
    Error,
 };

@@ -19,6 +19,7 @@ pub enum AuthenticatorVersion {
    V2,
    V3,
    V4,
+    V5,
    UNKNOWN,
 }

@@ -34,6 +35,8 @@ impl From<Protocol> for AuthenticatorVersion {
            AuthenticatorVersion::V3
        } else if value.version == v4::VERSION {
            AuthenticatorVersion::V4
+        } else if value.version == v5::VERSION {
+            AuthenticatorVersion::V5
        } else {
            AuthenticatorVersion::UNKNOWN
        }
@@ -68,6 +71,12 @@ impl InitMessage for v4::registration::InitMessage {
    }
 }

+impl InitMessage for v5::registration::InitMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
 pub trait FinalMessage {
    fn pub_key(&self) -> PeerPublicKey;
    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error>;
@@ -138,6 +147,24 @@ impl FinalMessage for v4::registration::FinalMessage {
        self.gateway_client.verify(private_key, nonce)
    }

+    fn private_ips(&self) -> IpPair {
+        self.gateway_client.private_ips.into()
+    }
+
+    fn credential(&self) -> Option<CredentialSpendingData> {
+        self.credential.clone()
+    }
+}
+
+impl FinalMessage for v5::registration::FinalMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.gateway_client.pub_key
+    }
+
+    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+        self.gateway_client.verify(private_key, nonce)
+    }
+
    fn private_ips(&self) -> IpPair {
        self.gateway_client.private_ips
    }
@@ -182,29 +209,39 @@ impl TopUpMessage for v4::topup::TopUpMessage {
    }
 }

+impl TopUpMessage for v5::topup::TopUpMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+
+    fn credential(&self) -> CredentialSpendingData {
+        self.credential.clone()
+    }
+}
+
 pub enum AuthenticatorRequest {
    Initial {
        msg: Box<dyn InitMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    Final {
        msg: Box<dyn FinalMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    QueryBandwidth {
        msg: Box<dyn QueryBandwidthMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    TopUpBandwidth {
        msg: Box<dyn TopUpMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
 }
@@ -218,7 +255,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                    version: value.version,
                    service_provider_type: ServiceProviderType::Authenticator,
                },
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v1::request::AuthenticatorRequestData::Final(gateway_client) => Self::Final {
@@ -227,7 +264,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                    version: value.version,
                    service_provider_type: ServiceProviderType::Authenticator,
                },
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v1::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
@@ -237,7 +274,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                        version: value.version,
                        service_provider_type: ServiceProviderType::Authenticator,
                    },
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -251,20 +288,20 @@ impl From<v2::request::AuthenticatorRequest> for AuthenticatorRequest {
            v2::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v2::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
                msg: final_message,
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v2::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
                Self::QueryBandwidth {
                    msg: Box::new(peer_public_key),
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -278,20 +315,20 @@ impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
            v3::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v3::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
                msg: final_message,
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v3::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
                Self::QueryBandwidth {
                    msg: Box::new(peer_public_key),
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -299,7 +336,7 @@ impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
                Self::TopUpBandwidth {
                    msg: top_up_message,
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -313,20 +350,20 @@ impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
            v4::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v4::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
                msg: final_message,
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v4::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
                Self::QueryBandwidth {
                    msg: Box::new(peer_public_key),
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -334,7 +371,42 @@ impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
                Self::TopUpBandwidth {
                    msg: top_up_message,
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v5::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v5::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v5::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+            v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: None,
                    request_id: value.request_id,
                }
            }
@@ -28,7 +28,7 @@ pub type HmacSha256 = Hmac<Sha256>;
 pub type Nonce = u64;
 pub type Taken = Option<SystemTime>;

-pub const BANDWIDTH_CAP_PER_DAY: u64 = 1024 * 1024 * 1024; // 1 GB
+pub const BANDWIDTH_CAP_PER_DAY: u64 = 250 * 1024 * 1024 * 1024; // 250 GB

 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct IpPair {
@@ -60,7 +60,7 @@ impl From<IpAddr> for IpPair {
            std::net::IpAddr::V4(ipv4_addr) => (ipv4_addr.octets()[2], ipv4_addr.octets()[3]),
            std::net::IpAddr::V6(ipv6_addr) => (ipv6_addr.octets()[14], ipv6_addr.octets()[15]),
        };
-        let last_bytes = (before_last_byte as u16) << 8 | last_byte as u16;
+        let last_bytes = ((before_last_byte as u16) << 8) | last_byte as u16;
        let ipv4 = Ipv4Addr::new(
            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[0],
            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[1],
@@ -0,0 +1,478 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+use crate::{v4, v5};
+
+impl From<v4::request::AuthenticatorRequest> for v5::request::AuthenticatorRequest {
+    fn from(authenticator_request: v4::request::AuthenticatorRequest) -> Self {
+        Self {
+            protocol: Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: authenticator_request.data.into(),
+            request_id: authenticator_request.request_id,
+        }
+    }
+}
+
+impl From<v4::request::AuthenticatorRequestData> for v5::request::AuthenticatorRequestData {
+    fn from(authenticator_request_data: v4::request::AuthenticatorRequestData) -> Self {
+        match authenticator_request_data {
+            v4::request::AuthenticatorRequestData::Initial(init_msg) => {
+                v5::request::AuthenticatorRequestData::Initial(init_msg.into())
+            }
+            v4::request::AuthenticatorRequestData::Final(final_msg) => {
+                v5::request::AuthenticatorRequestData::Final(Box::new((*final_msg).into()))
+            }
+            v4::request::AuthenticatorRequestData::QueryBandwidth(pub_key) => {
+                v5::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+            }
+            v4::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message.into())
+            }
+        }
+    }
+}
+
+impl From<v4::registration::InitMessage> for v5::registration::InitMessage {
+    fn from(init_msg: v4::registration::InitMessage) -> Self {
+        Self {
+            pub_key: init_msg.pub_key,
+        }
+    }
+}
+
+impl From<v4::registration::FinalMessage> for v5::registration::FinalMessage {
+    fn from(final_msg: v4::registration::FinalMessage) -> Self {
+        Self {
+            gateway_client: final_msg.gateway_client.into(),
+            credential: final_msg.credential,
+        }
+    }
+}
+
+impl From<v4::registration::GatewayClient> for v5::registration::GatewayClient {
+    fn from(gateway_client: v4::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v5::registration::GatewayClient> for v4::registration::GatewayClient {
+    fn from(gateway_client: v5::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v4::registration::ClientMac> for v5::registration::ClientMac {
+    fn from(client_mac: v4::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<v5::registration::ClientMac> for v4::registration::ClientMac {
+    fn from(client_mac: v5::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<Box<v4::topup::TopUpMessage>> for Box<v5::topup::TopUpMessage> {
+    fn from(top_up_message: Box<v4::topup::TopUpMessage>) -> Self {
+        Box::new(v5::topup::TopUpMessage {
+            pub_key: top_up_message.pub_key,
+            credential: top_up_message.credential,
+        })
+    }
+}
+
+impl From<v4::response::AuthenticatorResponse> for v5::response::AuthenticatorResponse {
+    fn from(value: v4::response::AuthenticatorResponse) -> Self {
+        Self {
+            protocol: Protocol {
+                version: 5,
+                service_provider_type: value.protocol.service_provider_type,
+            },
+            data: value.data.into(),
+        }
+    }
+}
+
+impl From<v4::response::AuthenticatorResponseData> for v5::response::AuthenticatorResponseData {
+    fn from(authenticator_response_data: v4::response::AuthenticatorResponseData) -> Self {
+        match authenticator_response_data {
+            v4::response::AuthenticatorResponseData::PendingRegistration(pending_response) => {
+                v5::response::AuthenticatorResponseData::PendingRegistration(
+                    pending_response.into(),
+                )
+            }
+            v4::response::AuthenticatorResponseData::Registered(registered_response) => {
+                v5::response::AuthenticatorResponseData::Registered(registered_response.into())
+            }
+            v4::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response.into(),
+            ),
+            v4::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response) => {
+                v5::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response.into())
+            }
+        }
+    }
+}
+
+impl From<v4::response::RegisteredResponse> for v5::response::RegisteredResponse {
+    fn from(value: v4::response::RegisteredResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::response::PendingRegistrationResponse> for v5::response::PendingRegistrationResponse {
+    fn from(value: v4::response::PendingRegistrationResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::registration::RegistrationData> for v5::registration::RegistrationData {
+    fn from(value: v4::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v5::registration::RegistrationData> for v4::registration::RegistrationData {
+    fn from(value: v5::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v4::response::RemainingBandwidthResponse> for v5::response::RemainingBandwidthResponse {
+    fn from(value: v4::response::RemainingBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.map(Into::into),
+        }
+    }
+}
+
+impl From<v4::response::TopUpBandwidthResponse> for v5::response::TopUpBandwidthResponse {
+    fn from(value: v4::response::TopUpBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::registration::RegistredData> for v5::registration::RegistredData {
+    fn from(value: v4::registration::RegistredData) -> Self {
+        Self {
+            pub_key: value.pub_key,
+            private_ips: value.private_ips.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v4::registration::RemainingBandwidthData> for v5::registration::RemainingBandwidthData {
+    fn from(value: v4::registration::RemainingBandwidthData) -> Self {
+        Self {
+            available_bandwidth: value.available_bandwidth,
+        }
+    }
+}
+
+impl From<v4::registration::IpPair> for v5::registration::IpPair {
+    fn from(value: v4::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+impl From<v5::registration::IpPair> for v4::registration::IpPair {
+    fn from(value: v5::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{
+        net::{Ipv4Addr, Ipv6Addr},
+        str::FromStr,
+    };
+
+    use nym_credentials_interface::CredentialSpendingData;
+    use nym_crypto::asymmetric::encryption::PrivateKey;
+    use nym_sphinx::addressing::Recipient;
+    use nym_wireguard_types::PeerPublicKey;
+    use x25519_dalek::PublicKey;
+
+    use super::*;
+    use crate::{
+        util::tests::{CREDENTIAL_BYTES, RECIPIENT},
+        v4,
+    };
+
+    #[test]
+    fn upgrade_initial_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) = v4::request::AuthenticatorRequest::new_initial_request(
+            v4::registration::InitMessage::new(pub_key),
+            reply_to,
+        );
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::Initial(v5::registration::InitMessage {
+                pub_key
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_final_req() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let gateway_client = v4::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let credential = Some(CredentialSpendingData::try_from_bytes(&CREDENTIAL_BYTES).unwrap());
+        let final_message = v4::registration::FinalMessage {
+            gateway_client: gateway_client.clone(),
+            credential: credential.clone(),
+        };
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) =
+            v4::request::AuthenticatorRequest::new_final_request(final_message, reply_to);
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::Final(Box::new(
+                v5::registration::FinalMessage {
+                    gateway_client: v5::registration::GatewayClient::new(
+                        &local_secret,
+                        (&remote_secret).into(),
+                        v5::registration::IpPair::new(ipv4, ipv6),
+                        nonce
+                    ),
+                    credential
+                }
+            ))
+        );
+    }
+
+    #[test]
+    fn upgrade_query_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) = v4::request::AuthenticatorRequest::new_query_request(pub_key, reply_to);
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+        );
+    }
+
+    #[test]
+    fn upgrade_pending_reg_resp() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let wg_port = 51822;
+        let gateway_data = v4::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let registration_data = v4::registration::RegistrationData {
+            nonce,
+            gateway_data,
+            wg_port,
+        };
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_pending_registration_success(
+            registration_data,
+            request_id,
+            reply_to,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::PendingRegistration(
+                v5::response::PendingRegistrationResponse {
+                    request_id,
+                    reply: v5::registration::RegistrationData {
+                        nonce,
+                        gateway_data: v5::registration::GatewayClient::new(
+                            &local_secret,
+                            (&remote_secret).into(),
+                            v5::registration::IpPair::new(ipv4, ipv6),
+                            nonce
+                        ),
+                        wg_port
+                    }
+                }
+            )
+        );
+    }
+
+    #[test]
+    fn upgrade_registered_resp() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let ipv4 = Ipv4Addr::from_str("10.1.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let private_ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let wg_port = 51822;
+        let registred_data = v4::registration::RegistredData {
+            pub_key,
+            private_ips,
+            wg_port,
+        };
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_registered(
+            registred_data,
+            reply_to,
+            request_id,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::Registered(v5::response::RegisteredResponse {
+                request_id,
+                reply: v5::registration::RegistredData {
+                    wg_port,
+                    pub_key,
+                    private_ips: v5::registration::IpPair::new(ipv4, ipv6)
+                }
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_remaining_bandwidth_resp() {
+        let available_bandwidth = 42;
+        let remaining_bandwidth_data = Some(v4::registration::RemainingBandwidthData {
+            available_bandwidth,
+        });
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_remaining_bandwidth(
+            remaining_bandwidth_data,
+            reply_to,
+            request_id,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                v5::response::RemainingBandwidthResponse {
+                    request_id,
+                    reply: Some(v5::registration::RemainingBandwidthData {
+                        available_bandwidth,
+                    })
+                }
+            )
+        );
+    }
+}
@@ -0,0 +1,10 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod conversion;
+pub mod registration;
+pub mod request;
+pub mod response;
+pub mod topup;
+
+pub const VERSION: u8 = 5;
@@ -0,0 +1,287 @@
+// -2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::Error;
+use base64::{engine::general_purpose, Engine};
+use nym_credentials_interface::CredentialSpendingData;
+use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::time::SystemTime;
+use std::{fmt, ops::Deref, str::FromStr};
+
+#[cfg(feature = "verify")]
+use hmac::{Hmac, Mac};
+#[cfg(feature = "verify")]
+use nym_crypto::asymmetric::encryption::PrivateKey;
+#[cfg(feature = "verify")]
+use sha2::Sha256;
+
+pub type PendingRegistrations = HashMap<PeerPublicKey, RegistrationData>;
+pub type PrivateIPs = HashMap<IpPair, Taken>;
+
+#[cfg(feature = "verify")]
+pub type HmacSha256 = Hmac<Sha256>;
+
+pub type Nonce = u64;
+pub type Taken = Option<SystemTime>;
+
+pub const BANDWIDTH_CAP_PER_DAY: u64 = 250 * 1024 * 1024 * 1024; // 250 GB
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct IpPair {
+    pub ipv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+}
+
+impl IpPair {
+    pub fn new(ipv4: Ipv4Addr, ipv6: Ipv6Addr) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl From<(Ipv4Addr, Ipv6Addr)> for IpPair {
+    fn from((ipv4, ipv6): (Ipv4Addr, Ipv6Addr)) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl fmt::Display for IpPair {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "({}, {})", self.ipv4, self.ipv6)
+    }
+}
+
+impl From<IpAddr> for IpPair {
+    fn from(value: IpAddr) -> Self {
+        let (before_last_byte, last_byte) = match value {
+            std::net::IpAddr::V4(ipv4_addr) => (ipv4_addr.octets()[2], ipv4_addr.octets()[3]),
+            std::net::IpAddr::V6(ipv6_addr) => (ipv6_addr.octets()[14], ipv6_addr.octets()[15]),
+        };
+        let last_bytes = ((before_last_byte as u16) << 8) | last_byte as u16;
+        let ipv4 = Ipv4Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[1],
+            before_last_byte,
+            last_byte,
+        );
+        let ipv6 = Ipv6Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[1],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[2],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[3],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[4],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[5],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[6],
+            last_bytes,
+        );
+        IpPair::new(ipv4, ipv6)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct InitMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+}
+
+impl InitMessage {
+    pub fn new(pub_key: PeerPublicKey) -> Self {
+        InitMessage { pub_key }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct FinalMessage {
+    /// Gateway client data
+    pub gateway_client: GatewayClient,
+
+    /// Ecash credential
+    pub credential: Option<CredentialSpendingData>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegistrationData {
+    pub nonce: u64,
+    pub gateway_data: GatewayClient,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegistredData {
+    pub pub_key: PeerPublicKey,
+    pub private_ips: IpPair,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RemainingBandwidthData {
+    pub available_bandwidth: i64,
+}
+
+/// Client that wants to register sends its PublicKey bytes mac digest encrypted with a DH shared secret.
+/// Gateway/Nym node can then verify pub_key payload using the same process
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct GatewayClient {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Assigned private IPs (v4 and v6)
+    pub private_ips: IpPair,
+
+    /// Sha256 hmac on the data (alongside the prior nonce)
+    pub mac: ClientMac,
+}
+
+impl GatewayClient {
+    #[cfg(feature = "verify")]
+    pub fn new(
+        local_secret: &PrivateKey,
+        remote_public: x25519_dalek::PublicKey,
+        private_ips: IpPair,
+        nonce: u64,
+    ) -> Self {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(local_secret.to_bytes());
+        let local_public: x25519_dalek::PublicKey = (&static_secret).into();
+
+        let dh = static_secret.diffie_hellman(&remote_public);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(dh.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(local_public.as_bytes());
+        mac.update(private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        GatewayClient {
+            pub_key: PeerPublicKey::new(local_public),
+            private_ips,
+            mac: ClientMac(mac.finalize().into_bytes().to_vec()),
+        }
+    }
+
+    // Reusable secret should be gateways Wireguard PK
+    // Client should perform this step when generating its payload, using its own WG PK
+    #[cfg(feature = "verify")]
+    pub fn verify(&self, gateway_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(gateway_key.to_bytes());
+
+        let dh = static_secret.diffie_hellman(&self.pub_key);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(dh.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(self.pub_key.as_bytes());
+        mac.update(self.private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        mac.verify_slice(&self.mac)
+            .map_err(|source| Error::FailedClientMacVerification {
+                client: self.pub_key.to_string(),
+                source,
+            })
+    }
+
+    pub fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
+// TODO: change the inner type into generic array of size HmacSha256::OutputSize
+// TODO2: rely on our internal crypto/hmac
+#[derive(Debug, Clone, PartialEq)]
+pub struct ClientMac(Vec<u8>);
+
+impl fmt::Display for ClientMac {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", general_purpose::STANDARD.encode(&self.0))
+    }
+}
+
+impl ClientMac {
+    #[allow(dead_code)]
+    pub fn new(mac: Vec<u8>) -> Self {
+        ClientMac(mac)
+    }
+}
+
+impl Deref for ClientMac {
+    type Target = Vec<u8>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl FromStr for ClientMac {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mac_bytes: Vec<u8> =
+            general_purpose::STANDARD
+                .decode(s)
+                .map_err(|source| Error::MalformedClientMac {
+                    mac: s.to_string(),
+                    source,
+                })?;
+
+        Ok(ClientMac(mac_bytes))
+    }
+}
+
+impl Serialize for ClientMac {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let encoded_key = general_purpose::STANDARD.encode(self.0.clone());
+        serializer.serialize_str(&encoded_key)
+    }
+}
+
+impl<'de> Deserialize<'de> for ClientMac {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let encoded_key = String::deserialize(deserializer)?;
+        ClientMac::from_str(&encoded_key).map_err(serde::de::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nym_crypto::asymmetric::encryption;
+
+    #[test]
+    fn create_ip_pair() {
+        let ipv4: IpAddr = Ipv4Addr::from_str("10.1.10.50").unwrap().into();
+        let ipv6: IpAddr = Ipv6Addr::from_str("fc01::0a32").unwrap().into();
+
+        assert_eq!(IpPair::from(ipv4), IpPair::from(ipv6));
+    }
+
+    #[test]
+    #[cfg(feature = "verify")]
+    fn client_request_roundtrip() {
+        let mut rng = rand::thread_rng();
+
+        let gateway_key_pair = encryption::KeyPair::new(&mut rng);
+        let client_key_pair = encryption::KeyPair::new(&mut rng);
+
+        let nonce = 1234567890;
+
+        let client = GatewayClient::new(
+            client_key_pair.private_key(),
+            x25519_dalek::PublicKey::from(gateway_key_pair.public_key().to_bytes()),
+            IpPair::new("10.0.0.42".parse().unwrap(), "fc00::42".parse().unwrap()),
+            nonce,
+        );
+        assert!(client.verify(gateway_key_pair.private_key(), nonce).is_ok())
+    }
+}
@@ -0,0 +1,132 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::{
+    registration::{FinalMessage, InitMessage},
+    topup::TopUpMessage,
+};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+fn generate_random() -> u64 {
+    use rand::RngCore;
+    let mut rng = rand::rngs::OsRng;
+    rng.next_u64()
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorRequest {
+    pub protocol: Protocol,
+    pub data: AuthenticatorRequestData,
+    pub request_id: u64,
+}
+
+impl AuthenticatorRequest {
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn new_initial_request(init_message: InitMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Initial(init_message),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_final_request(final_message: FinalMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Final(Box::new(final_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_query_request(peer_public_key: PeerPublicKey) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::QueryBandwidth(peer_public_key),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_topup_request(top_up_message: TopUpMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::TopUpBandwidth(Box::new(top_up_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorRequestData {
+    Initial(InitMessage),
+    Final(Box<FinalMessage>),
+    QueryBandwidth(PeerPublicKey),
+    TopUpBandwidth(Box<TopUpMessage>),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::str::FromStr;
+
+    #[test]
+    fn check_first_bytes_protocol() {
+        let version = 5;
+        let data = AuthenticatorRequest {
+            protocol: Protocol {
+                version,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: AuthenticatorRequestData::Initial(InitMessage::new(
+                PeerPublicKey::from_str("yvNUDpT5l7W/xDhiu6HkqTHDQwbs/B3J5UrLmORl1EQ=").unwrap(),
+            )),
+            request_id: 1,
+        };
+        let bytes = *data.to_bytes().unwrap().first_chunk::<2>().unwrap();
+        assert_eq!(bytes, [version, ServiceProviderType::Authenticator as u8]);
+    }
+}
@@ -0,0 +1,132 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorResponse {
+    pub protocol: Protocol,
+    pub data: AuthenticatorResponseData,
+}
+
+impl AuthenticatorResponse {
+    pub fn new_pending_registration_success(
+        registration_data: RegistrationData,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::PendingRegistration(PendingRegistrationResponse {
+                reply: registration_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_registered(registred_data: RegistredData, request_id: u64) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::Registered(RegisteredResponse {
+                reply: registred_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_remaining_bandwidth(
+        remaining_bandwidth_data: Option<RemainingBandwidthData>,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::RemainingBandwidth(RemainingBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_topup_bandwidth(
+        remaining_bandwidth_data: RemainingBandwidthData,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::TopUpBandwidth(TopUpBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn id(&self) -> Option<u64> {
+        match &self.data {
+            AuthenticatorResponseData::PendingRegistration(response) => Some(response.request_id),
+            AuthenticatorResponseData::Registered(response) => Some(response.request_id),
+            AuthenticatorResponseData::RemainingBandwidth(response) => Some(response.request_id),
+            AuthenticatorResponseData::TopUpBandwidth(response) => Some(response.request_id),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorResponseData {
+    PendingRegistration(PendingRegistrationResponse),
+    Registered(RegisteredResponse),
+    RemainingBandwidth(RemainingBandwidthResponse),
+    TopUpBandwidth(TopUpBandwidthResponse),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct PendingRegistrationResponse {
+    pub request_id: u64,
+    pub reply: RegistrationData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RegisteredResponse {
+    pub request_id: u64,
+    pub reply: RegistredData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RemainingBandwidthResponse {
+    pub request_id: u64,
+    pub reply: Option<RemainingBandwidthData>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct TopUpBandwidthResponse {
+    pub request_id: u64,
+    pub reply: RemainingBandwidthData,
+}
@@ -0,0 +1,15 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_credentials_interface::CredentialSpendingData;
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct TopUpMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Ecash credential
+    pub credential: CredentialSpendingData,
+}
@@ -105,26 +105,24 @@ impl<C, St: Storage> BandwidthController<C, St> {
    async fn get_aggregate_verification_key(
        &self,
        epoch_id: EpochId,
-        apis: &mut ApiClientsWrapper,
+        ecash_apis: &mut ApiClientsWrapper<'_, C>,
    ) -> Result<VerificationKeyAuth, BandwidthControllerError>
    where
        C: DkgQueryClient + Sync + Send,
        <St as Storage>::StorageError: Send + Sync + 'static,
    {
-        let ecash_apis = apis.get_or_init(epoch_id, &self.client).await?;
        get_aggregate_verification_key(&self.storage, epoch_id, ecash_apis).await
    }

    async fn get_coin_index_signatures(
        &self,
        epoch_id: EpochId,
-        apis: &mut ApiClientsWrapper,
+        ecash_apis: &mut ApiClientsWrapper<'_, C>,
    ) -> Result<Vec<AnnotatedCoinIndexSignature>, BandwidthControllerError>
    where
        C: DkgQueryClient + Sync + Send,
        <St as Storage>::StorageError: Send + Sync + 'static,
    {
-        let ecash_apis = apis.get_or_init(epoch_id, &self.client).await?;
        get_coin_index_signatures(&self.storage, epoch_id, ecash_apis).await
    }

@@ -132,13 +130,12 @@ impl<C, St: Storage> BandwidthController<C, St> {
        &self,
        epoch_id: EpochId,
        expiration_date: Date,
-        apis: &mut ApiClientsWrapper,
+        ecash_apis: &mut ApiClientsWrapper<'_, C>,
    ) -> Result<Vec<AnnotatedExpirationDateSignature>, BandwidthControllerError>
    where
        C: DkgQueryClient + Sync + Send,
        <St as Storage>::StorageError: Send + Sync + 'static,
    {
-        let ecash_apis = apis.get_or_init(epoch_id, &self.client).await?;
        get_expiration_date_signatures(&self.storage, epoch_id, expiration_date, ecash_apis).await
    }

@@ -154,7 +151,7 @@ impl<C, St: Storage> BandwidthController<C, St> {
    {
        let epoch_id = retrieved_ticketbook.ticketbook.epoch_id();
        let expiration_date = retrieved_ticketbook.ticketbook.expiration_date();
-        let mut api_clients = Default::default();
+        let mut api_clients = ApiClientsWrapper::new(&self.client, epoch_id);

        let verification_key = self
            .get_aggregate_verification_key(epoch_id, &mut api_clients)
@@ -21,30 +21,67 @@ use rand::thread_rng;
 use std::fmt::Display;
 use std::future::Future;

-// it really doesn't need the RwLock because it's never moved across tasks,
-// but we need all the Send/Sync action
-#[derive(Default)]
-pub(crate) struct ApiClientsWrapper(Option<Vec<EcashApiClient>>);
-
-impl ApiClientsWrapper {
-    pub(crate) async fn get_or_init<C>(
+pub(crate) trait EcashClientsProvider {
+    async fn try_get_ecash_clients(
        &mut self,
+    ) -> Result<Vec<EcashApiClient>, BandwidthControllerError>;
+}
+
+impl EcashClientsProvider for Vec<EcashApiClient> {
+    async fn try_get_ecash_clients(
+        &mut self,
+    ) -> Result<Vec<EcashApiClient>, BandwidthControllerError> {
+        Ok(self.clone())
+    }
+}
+
+impl<C> EcashClientsProvider for &mut ApiClientsWrapper<'_, C>
+where
+    C: DkgQueryClient + Sync + Send,
+{
+    async fn try_get_ecash_clients(
+        &mut self,
+    ) -> Result<Vec<EcashApiClient>, BandwidthControllerError> {
+        self.clients().await
+    }
+}
+
+pub(crate) enum ApiClientsWrapper<'a, C> {
+    Uninitialised {
+        query_client: &'a C,
        epoch_id: EpochId,
-        dkg_client: &C,
-    ) -> Result<Vec<EcashApiClient>, BandwidthControllerError>
+    },
+    Cached {
+        clients: Vec<EcashApiClient>,
+    },
+}
+
+impl<'a, C> ApiClientsWrapper<'a, C> {
+    pub(crate) fn new(query_client: &'a C, epoch_id: EpochId) -> Self {
+        ApiClientsWrapper::Uninitialised {
+            query_client,
+            epoch_id,
+        }
+    }
+
+    async fn clients(&mut self) -> Result<Vec<EcashApiClient>, BandwidthControllerError>
    where
        C: DkgQueryClient + Sync + Send,
    {
-        if let Some(cached) = &self.0 {
-            return Ok(cached.clone());
+        match self {
+            ApiClientsWrapper::Uninitialised {
+                query_client,
+                epoch_id,
+            } => {
+                let clients = all_ecash_api_clients(*query_client, *epoch_id).await?;
+                *self = ApiClientsWrapper::Cached {
+                    clients: clients.clone(),
+                };
+
+                Ok(clients)
+            }
+            ApiClientsWrapper::Cached { clients } => Ok(clients.clone()),
        }
-
-        let clients = all_ecash_api_clients(dkg_client, epoch_id).await?;
-
-        // technically we don't have to be cloning all the clients here, but it's way simpler than
-        // dealing with locking and whatnot given the performance penalty is negligible
-        self.0 = Some(clients.clone());
-        Ok(clients)
    }
 }

@@ -76,7 +113,7 @@ where
 pub(crate) async fn get_aggregate_verification_key<St>(
    storage: &St,
    epoch_id: EpochId,
-    ecash_apis: Vec<EcashApiClient>,
+    mut ecash_apis: impl EcashClientsProvider,
 ) -> Result<VerificationKeyAuth, BandwidthControllerError>
 where
    St: Storage,
@@ -90,6 +127,8 @@ where
        return Ok(stored);
    };

+    let ecash_apis = ecash_apis.try_get_ecash_clients().await?;
+
    let master_vk = query_random_apis_until_success(
        ecash_apis,
        |api| async move { api.api_client.master_verification_key(Some(epoch_id)).await },
@@ -115,7 +154,7 @@ where
 pub(crate) async fn get_coin_index_signatures<St>(
    storage: &St,
    epoch_id: EpochId,
-    ecash_apis: Vec<EcashApiClient>,
+    mut ecash_apis: impl EcashClientsProvider,
 ) -> Result<Vec<AnnotatedCoinIndexSignature>, BandwidthControllerError>
 where
    St: Storage,
@@ -129,6 +168,8 @@ where
        return Ok(stored);
    };

+    let ecash_apis = ecash_apis.try_get_ecash_clients().await?;
+
    let index_sigs = query_random_apis_until_success(
        ecash_apis,
        |api| async move {
@@ -159,7 +200,7 @@ pub(crate) async fn get_expiration_date_signatures<St>(
    storage: &St,
    epoch_id: EpochId,
    expiration_date: Date,
-    ecash_apis: Vec<EcashApiClient>,
+    mut ecash_apis: impl EcashClientsProvider,
 ) -> Result<Vec<AnnotatedExpirationDateSignature>, BandwidthControllerError>
 where
    St: Storage,
@@ -173,6 +214,8 @@ where
        return Ok(stored);
    };

+    let ecash_apis = ecash_apis.try_get_ecash_clients().await?;
+
    let expiration_sigs = query_random_apis_until_success(
        ecash_apis,
        |api| async move {
@@ -3,7 +3,7 @@ name = "nym-client-core"
 version = "1.1.15"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 edition = "2021"
-rust-version = "1.70"
+rust-version = "1.76"
 license.workspace = true

 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
@@ -40,12 +40,13 @@ nym-crypto = { path = "../crypto" }
 nym-explorer-client = { path = "../../explorer-api/explorer-client" }
 nym-gateway-client = { path = "../client-libs/gateway-client" }
 nym-gateway-requests = { path = "../gateway-requests" }
+nym-http-api-client = { path = "../http-api-client" }
 nym-metrics = { path = "../nym-metrics" }
 nym-nonexhaustive-delayqueue = { path = "../nonexhaustive-delayqueue" }
 nym-sphinx = { path = "../nymsphinx" }
 nym-statistics-common = { path = "../statistics" }
 nym-pemstore = { path = "../pemstore" }
-nym-topology = { path = "../topology", features = ["serializable"] }
+nym-topology = { path = "../topology", features = ["persistence"] }
 nym-mixnet-client = { path = "../client-libs/mixnet-client", default-features = false }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }
 nym-task = { path = "../task" }
@@ -45,11 +45,12 @@ const DEFAULT_COVER_TRAFFIC_PRIMARY_SIZE_RATIO: f64 = 0.70;
 // clients/client-core/src/client/replies/reply_storage/surb_storage.rs
 const DEFAULT_MINIMUM_REPLY_SURB_STORAGE_THRESHOLD: usize = 10;
 const DEFAULT_MAXIMUM_REPLY_SURB_STORAGE_THRESHOLD: usize = 200;
+const DEFAULT_MINIMUM_REPLY_SURB_THRESHOLD_BUFFER: usize = 0;

 // define how much to request at once
 // clients/client-core/src/client/replies/reply_controller.rs
 const DEFAULT_MINIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 10;
-const DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 100;
+const DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 50;

 const DEFAULT_MAXIMUM_ALLOWED_SURB_REQUEST_SIZE: u32 = 500;

@@ -145,6 +146,11 @@ impl Config {
        self
    }

+    pub fn with_forget_me(mut self, forget_me: ForgetMe) -> Self {
+        self.debug.forget_me = forget_me;
+        self
+    }
+
    // TODO: this should be refactored properly
    // as of 12.09.23 the below is true (not sure how this comment will rot in the future)
    // medium_toggle:
@@ -517,7 +523,7 @@ impl Default for Acknowledgements {
 }

 #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Serialize)]
-#[serde(default, deny_unknown_fields)]
+#[serde(default)]
 pub struct Topology {
    /// The uniform delay every which clients are querying the directory server
    /// to try to obtain a compatible network topology to send sphinx packets through.
@@ -550,6 +556,18 @@ pub struct Topology {
    /// Specifies a minimum performance of a gateway that is used on route construction.
    /// This setting is only applicable when `NymApi` topology is used.
    pub minimum_gateway_performance: u8,
+
+    /// Specifies whether this client should attempt to retrieve all available network nodes
+    /// as opposed to just active mixnodes/gateways.
+    pub use_extended_topology: bool,
+
+    /// Specifies whether this client should ignore the current epoch role of the target egress node
+    /// when constructing the final hop packets.
+    pub ignore_egress_epoch_role: bool,
+
+    /// Specifies whether this client should ignore the current epoch role of the ingress node
+    /// when attempting to establish new connection
+    pub ignore_ingress_epoch_role: bool,
 }

 #[allow(clippy::large_enum_variant)]
@@ -586,6 +604,10 @@ impl Default for Topology {
            topology_structure: TopologyStructure::default(),
            minimum_mixnode_performance: DEFAULT_MIN_MIXNODE_PERFORMANCE,
            minimum_gateway_performance: DEFAULT_MIN_GATEWAY_PERFORMANCE,
+            use_extended_topology: false,
+
+            ignore_egress_epoch_role: true,
+            ignore_ingress_epoch_role: true,
        }
    }
 }
@@ -600,6 +622,10 @@ pub struct ReplySurbs {
    /// Defines the maximum number of reply surbs the client wants to keep in its storage at any times.
    pub maximum_reply_surb_storage_threshold: usize,

+    /// Defines the soft threshold ontop of the minimum reply surb storage threshold for when the client
+    /// should proactively request additional reply surbs.
+    pub minimum_reply_surb_threshold_buffer: usize,
+
    /// Defines the minimum number of reply surbs the client would request.
    pub minimum_reply_surb_request_size: u32,

@@ -632,6 +658,9 @@ pub struct ReplySurbs {
    /// Specifies the number of mixnet hops the packet should go through. If not specified, then
    /// the default value is used.
    pub surb_mix_hops: Option<u8>,
+
+    /// Specifies if we should reset all the sender tags on startup
+    pub fresh_sender_tags: bool,
 }

 impl Default for ReplySurbs {
@@ -639,6 +668,7 @@ impl Default for ReplySurbs {
        ReplySurbs {
            minimum_reply_surb_storage_threshold: DEFAULT_MINIMUM_REPLY_SURB_STORAGE_THRESHOLD,
            maximum_reply_surb_storage_threshold: DEFAULT_MAXIMUM_REPLY_SURB_STORAGE_THRESHOLD,
+            minimum_reply_surb_threshold_buffer: DEFAULT_MINIMUM_REPLY_SURB_THRESHOLD_BUFFER,
            minimum_reply_surb_request_size: DEFAULT_MINIMUM_REPLY_SURB_REQUEST_SIZE,
            maximum_reply_surb_request_size: DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE,
            maximum_allowed_reply_surb_request_size: DEFAULT_MAXIMUM_ALLOWED_SURB_REQUEST_SIZE,
@@ -648,6 +678,7 @@ impl Default for ReplySurbs {
            maximum_reply_surb_age: DEFAULT_MAXIMUM_REPLY_SURB_AGE,
            maximum_reply_key_age: DEFAULT_MAXIMUM_REPLY_KEY_AGE,
            surb_mix_hops: None,
+            fresh_sender_tags: false,
        }
    }
 }
@@ -703,6 +734,9 @@ pub struct DebugConfig {

    /// Defines all configuration options related to stats reporting.
    pub stats_reporting: StatsReporting,
+
+    /// Defines all configuration options related to the forget me flag.
+    pub forget_me: ForgetMe,
 }

 impl DebugConfig {
@@ -725,6 +759,69 @@ impl Default for DebugConfig {
            topology: Default::default(),
            reply_surbs: Default::default(),
            stats_reporting: Default::default(),
+            forget_me: Default::default(),
+        }
+    }
+}
+
+#[derive(Clone, Default, Debug, Deserialize, PartialEq, Serialize, Copy)]
+pub struct ForgetMe {
+    client: bool,
+    stats: bool,
+}
+
+impl From<bool> for ForgetMe {
+    fn from(value: bool) -> Self {
+        if value {
+            Self::new_all()
+        } else {
+            Self::new_none()
+        }
+    }
+}
+
+impl ForgetMe {
+    pub fn new_all() -> Self {
+        Self {
+            client: true,
+            stats: true,
+        }
+    }
+
+    pub fn new_client() -> Self {
+        Self {
+            client: true,
+            stats: false,
+        }
+    }
+
+    pub fn new_stats() -> Self {
+        Self {
+            client: false,
+            stats: true,
+        }
+    }
+
+    pub fn new(client: bool, stats: bool) -> Self {
+        Self { client, stats }
+    }
+
+    pub fn any(&self) -> bool {
+        self.client || self.stats
+    }
+
+    pub fn client(&self) -> bool {
+        self.client
+    }
+
+    pub fn stats(&self) -> bool {
+        self.stats
+    }
+
+    pub fn new_none() -> Self {
+        Self {
+            client: false,
+            stats: false,
        }
    }
 }
@@ -181,8 +181,9 @@ impl From<ConfigV5> for Config {
                    maximum_reply_surb_age: value.debug.reply_surbs.maximum_reply_surb_age,
                    maximum_reply_key_age: value.debug.reply_surbs.maximum_reply_key_age,
                    surb_mix_hops: value.debug.reply_surbs.surb_mix_hops,
+                    ..Default::default()
                },
-                stats_reporting: Default::default(),
+                ..Default::default()
            },
        }
    }
@@ -8,7 +8,10 @@ use crate::{
    },
 };
 use log::{debug, error};
-use sqlx::ConnectOptions;
+use sqlx::{
+    sqlite::{SqliteAutoVacuum, SqliteSynchronous},
+    ConnectOptions,
+};
 use std::path::Path;

 #[derive(Debug, Clone)]
@@ -30,6 +33,9 @@ impl StorageManager {
        }

        let opts = sqlx::sqlite::SqliteConnectOptions::new()
+            .journal_mode(sqlx::sqlite::SqliteJournalMode::Wal)
+            .synchronous(SqliteSynchronous::Normal)
+            .auto_vacuum(SqliteAutoVacuum::Incremental)
            .filename(database_path)
            .create_if_missing(true)
            .disable_statement_logging();
@@ -110,7 +116,7 @@ impl StorageManager {
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
            r#"
-                INSERT INTO registered_gateway(gateway_id_bs58, registration_timestamp, gateway_type) 
+                INSERT INTO registered_gateway(gateway_id_bs58, registration_timestamp, gateway_type)
                VALUES (?, ?, ?)
            "#,
            registered_gateway.gateway_id_bs58,
@@ -224,7 +230,7 @@ impl StorageManager {
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
            r#"
-                INSERT INTO custom_gateway_details(gateway_id_bs58, data) 
+                INSERT INTO custom_gateway_details(gateway_id_bs58, data)
                VALUES (?, ?)
            "#,
            custom.gateway_id_bs58,
@@ -15,6 +15,7 @@ pub mod error;
 mod manager;
 mod models;

+#[derive(Clone)]
 pub struct OnDiskGatewaysDetails {
    manager: StorageManager,
 }
@@ -20,12 +20,12 @@ pub enum InMemStorageError {
    MalformedGateway(#[from] BadGateway),
 }

-#[derive(Debug, Default)]
+#[derive(Clone, Debug, Default)]
 pub struct InMemGatewaysDetails {
    inner: Arc<RwLock<InMemStorageInner>>,
 }

-#[derive(Debug, Default)]
+#[derive(Clone, Debug, Default)]
 struct InMemStorageInner {
    active_gateway: Option<String>,
    gateways: HashMap<String, GatewayRegistration>,
@@ -112,14 +112,15 @@ where
                source,
            }
        })?;
-        hardcoded_topology.get_gateways()
+        hardcoded_topology.entry_capable_nodes().cloned().collect()
    } else {
        let mut rng = rand::thread_rng();
-        crate::init::helpers::current_gateways(
+        crate::init::helpers::gateways_for_init(
            &mut rng,
            &core.client.nym_api_urls,
            user_agent,
            core.debug.topology.minimum_gateway_performance,
+            core.debug.topology.ignore_ingress_epoch_role,
        )
        .await?
    };
@@ -128,7 +129,7 @@ where
    // make sure the list of available gateways doesn't overlap the list of known gateways
    let available_gateways = available_gateways
        .into_iter()
-        .filter(|g| !registered_gateways.contains(g.identity()))
+        .filter(|g| !registered_gateways.contains(&g.identity()))
        .collect::<Vec<_>>();

    if available_gateways.is_empty() {
@@ -93,6 +93,10 @@ pub struct CommonClientInitArgs {
    /// Sets the address to report statistics
    #[cfg_attr(feature = "cli", clap(long, hide = true))]
    pub stats_reporting_address: Option<Recipient>,
+
+    /// Sets the forget me flag
+    #[cfg_attr(feature = "cli", clap(long, hide = true, default_value_t = false))]
+    pub forget_me: bool,
 }

 pub struct InitResultsWithConfig<T> {
@@ -167,14 +171,15 @@ where
                source,
            }
        })?;
-        hardcoded_topology.get_gateways()
+        hardcoded_topology.entry_capable_nodes().cloned().collect()
    } else {
        let mut rng = rand::thread_rng();
-        crate::init::helpers::current_gateways(
+        crate::init::helpers::gateways_for_init(
            &mut rng,
            &core.client.nym_api_urls,
            user_agent,
            core.debug.topology.minimum_gateway_performance,
+            core.debug.topology.ignore_ingress_epoch_role,
        )
        .await?
    };
@@ -61,4 +61,8 @@ pub struct CommonClientRunArgs {
    /// Sets the address to report statistics
    #[cfg_attr(feature = "cli", clap(long, hide = true))]
    pub stats_reporting_address: Option<Recipient>,
+
+    /// Sets the forget me flag
+    #[cfg_attr(feature = "cli", clap(long, hide = true, default_value_t = false))]
+    pub forget_me: bool,
 }
@@ -1,9 +1,9 @@
 // Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use super::mix_traffic::ClientRequestSender;
 use super::received_buffer::ReceivedBufferMessage;
 use super::statistics_control::StatisticsControl;
-use super::topology_control::geo_aware_provider::GeoAwareTopologyProvider;
 use crate::client::base_client::storage::helpers::store_client_keys;
 use crate::client::base_client::storage::MixnetClientStorage;
 use crate::client::cover_traffic_stream::LoopCoverTrafficStream;
@@ -24,7 +24,7 @@ use crate::client::replies::reply_storage::{
 };
 use crate::client::topology_control::nym_api_provider::NymApiTopologyProvider;
 use crate::client::topology_control::{
-    nym_api_provider, TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
+    TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
 };
 use crate::config::{Config, DebugConfig};
 use crate::error::ClientCoreError;
@@ -36,9 +36,11 @@ use crate::{config, spawn_future};
 use futures::channel::mpsc;
 use log::*;
 use nym_bandwidth_controller::BandwidthController;
+use nym_client_core_config_types::ForgetMe;
 use nym_client_core_gateways_storage::{GatewayDetails, GatewaysDetailsStore};
 use nym_credential_storage::storage::Storage as CredentialStorage;
 use nym_crypto::asymmetric::{encryption, identity};
+use nym_crypto::hkdf::DerivationMaterial;
 use nym_gateway_client::client::config::GatewayClientConfig;
 use nym_gateway_client::{
    AcknowledgementReceiver, GatewayClient, GatewayConfig, MixnetMessageReceiver, PacketRouter,
@@ -176,8 +178,8 @@ impl From<bool> for CredentialsToggle {
    }
 }

-pub struct BaseClientBuilder<'a, C, S: MixnetClientStorage> {
-    config: &'a Config,
+pub struct BaseClientBuilder<C, S: MixnetClientStorage> {
+    config: Config,
    client_store: S,
    dkg_query_client: Option<C>,

@@ -188,18 +190,23 @@ pub struct BaseClientBuilder<'a, C, S: MixnetClientStorage> {
    user_agent: Option<UserAgent>,

    setup_method: GatewaySetup,
+
+    #[cfg(unix)]
+    connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
+
+    derivation_material: Option<DerivationMaterial>,
 }

-impl<'a, C, S> BaseClientBuilder<'a, C, S>
+impl<C, S> BaseClientBuilder<C, S>
 where
    S: MixnetClientStorage + 'static,
    C: DkgQueryClient + Send + Sync + 'static,
 {
    pub fn new(
-        base_config: &'a Config,
+        base_config: Config,
        client_store: S,
        dkg_query_client: Option<C>,
-    ) -> BaseClientBuilder<'a, C, S> {
+    ) -> BaseClientBuilder<C, S> {
        BaseClientBuilder {
            config: base_config,
            client_store,
@@ -210,9 +217,27 @@ where
            shutdown: None,
            user_agent: None,
            setup_method: GatewaySetup::MustLoad { gateway_id: None },
+            #[cfg(unix)]
+            connection_fd_callback: None,
+            derivation_material: None,
        }
    }

+    #[must_use]
+    pub fn with_derivation_material(
+        mut self,
+        derivation_material: Option<DerivationMaterial>,
+    ) -> Self {
+        self.derivation_material = derivation_material;
+        self
+    }
+
+    #[must_use]
+    pub fn with_forget_me(mut self, forget_me: &ForgetMe) -> Self {
+        self.config.debug.forget_me = *forget_me;
+        self
+    }
+
    #[must_use]
    pub fn with_gateway_setup(mut self, setup: GatewaySetup) -> Self {
        self.setup_method = setup;
@@ -261,6 +286,15 @@ where
        Ok(self)
    }

+    #[cfg(unix)]
+    pub fn with_connection_fd_callback(
+        mut self,
+        callback: Arc<dyn Fn(RawFd) + Send + Sync>,
+    ) -> Self {
+        self.connection_fd_callback = Some(callback);
+        self
+    }
+
    // note: do **NOT** make this method public as its only valid usage is from within `start_base`
    // because it relies on the crypto keys being already loaded
    fn mix_address(details: &InitialisationResult) -> Recipient {
@@ -276,7 +310,7 @@ where
        topology_accessor: TopologyAccessor,
        mix_tx: BatchMixMessageSender,
        stats_tx: ClientStatsSender,
-        shutdown: TaskClient,
+        task_client: TaskClient,
    ) {
        info!("Starting loop cover traffic stream...");

@@ -289,9 +323,10 @@ where
            debug_config.traffic,
            debug_config.cover_traffic,
            stats_tx,
+            task_client,
        );

-        stream.start_with_shutdown(shutdown);
+        stream.start();
    }

    #[allow(clippy::too_many_arguments)]
@@ -306,7 +341,7 @@ where
        reply_controller_receiver: ReplyControllerReceiver,
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
-        shutdown: TaskClient,
+        task_client: TaskClient,
        packet_type: PacketType,
        stats_tx: ClientStatsSender,
    ) {
@@ -324,8 +359,9 @@ where
            lane_queue_lengths,
            client_connection_rx,
            stats_tx,
+            task_client,
        )
-        .start_with_shutdown(shutdown, packet_type);
+        .start(packet_type);
    }

    // buffer controlling all messages fetched from provider
@@ -348,10 +384,12 @@ where
                reply_key_storage,
                reply_controller_sender,
                metrics_reporter,
+                shutdown,
            );
-        controller.start_with_shutdown(shutdown)
+        controller.start()
    }

+    #[allow(clippy::too_many_arguments)]
    async fn start_gateway_client(
        config: &Config,
        initialisation_result: InitialisationResult,
@@ -359,6 +397,7 @@ where
        details_store: &S::GatewaysDetailsStore,
        packet_router: PacketRouter,
        stats_reporter: ClientStatsSender,
+        #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
        shutdown: TaskClient,
    ) -> Result<GatewayClient<C, S::CredentialStore>, ClientCoreError>
    where
@@ -401,6 +440,8 @@ where
                    packet_router,
                    bandwidth_controller,
                    stats_reporter,
+                    #[cfg(unix)]
+                    connection_fd_callback,
                    shutdown,
                )
            };
@@ -437,8 +478,8 @@ where
            details_store
                .upgrade_stored_remote_gateway_key(gateway_client.gateway_identity(), &updated_key)
                .await.map_err(|err| {
-                    error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
-                    ClientCoreError::GatewaysDetailsStoreError { source: Box::new(err) }
+                error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
+                ClientCoreError::GatewaysDetailsStoreError { source: Box::new(err) }
            })?
        }

@@ -446,6 +487,7 @@ where
            .claim_initial_bandwidth()
            .await
            .map_err(gateway_failure)?;
+
        gateway_client
            .start_listening_for_mixnet_messages()
            .map_err(gateway_failure)?;
@@ -462,6 +504,7 @@ where
        details_store: &S::GatewaysDetailsStore,
        packet_router: PacketRouter,
        stats_reporter: ClientStatsSender,
+        #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
        mut shutdown: TaskClient,
    ) -> Result<Box<dyn GatewayTransceiver + Send>, ClientCoreError>
    where
@@ -493,6 +536,8 @@ where
            details_store,
            packet_router,
            stats_reporter,
+            #[cfg(unix)]
+            connection_fd_callback,
            shutdown,
        )
        .await?;
@@ -509,15 +554,15 @@ where
        // if no custom provider was ... provided ..., create one using nym-api
        custom_provider.unwrap_or_else(|| match config_topology.topology_structure {
            config::TopologyStructure::NymApi => Box::new(NymApiTopologyProvider::new(
-                nym_api_provider::Config {
-                    min_mixnode_performance: config_topology.minimum_mixnode_performance,
-                    min_gateway_performance: config_topology.minimum_gateway_performance,
-                },
+                config_topology,
                nym_api_urls,
                user_agent,
            )),
            config::TopologyStructure::GeoAware(group_by) => {
-                Box::new(GeoAwareTopologyProvider::new(nym_api_urls, group_by))
+                warn!("using deprecated 'GeoAware' topology provider - this option will be removed very soon");
+
+                #[allow(deprecated)]
+                Box::new(crate::client::topology_control::GeoAwareTopologyProvider::new(nym_api_urls, group_by))
            }
        })
    }
@@ -528,17 +573,24 @@ where
        topology_provider: Box<dyn TopologyProvider + Send + Sync>,
        topology_config: config::Topology,
        topology_accessor: TopologyAccessor,
-        local_gateway: &NodeIdentity,
+        local_gateway: NodeIdentity,
        wait_for_gateway: bool,
-        mut shutdown: TaskClient,
+        mut task_client: TaskClient,
    ) -> Result<(), ClientCoreError> {
        let topology_refresher_config =
            TopologyRefresherConfig::new(topology_config.topology_refresh_rate);

+        if topology_config.disable_refreshing {
+            // if we're not spawning the refresher, don't cause shutdown immediately
+            info!("The background topology refesher is not going to be started");
+            task_client.disarm();
+        }
+
        let mut topology_refresher = TopologyRefresher::new(
            topology_refresher_config,
            topology_accessor,
            topology_provider,
+            task_client,
        );
        // before returning, block entire runtime to refresh the current network view so that any
        // components depending on topology would see a non-empty view
@@ -560,7 +612,7 @@ where
        };

        if let Err(err) = topology_refresher
-            .ensure_contains_gateway(local_gateway)
+            .ensure_contains_routable_egress(local_gateway)
            .await
        {
            if let Some(waiting_timeout) = gateway_wait_timeout {
@@ -579,15 +631,11 @@ where
            }
        }

-        if topology_config.disable_refreshing {
-            // if we're not spawning the refresher, don't cause shutdown immediately
-            info!("The topology refesher is not going to be started");
-            shutdown.disarm();
-        } else {
+        if !topology_config.disable_refreshing {
            // don't spawn the refresher if we don't want to be refreshing the topology.
            // only use the initial values obtained
            info!("Starting topology refresher...");
-            topology_refresher.start_with_shutdown(shutdown);
+            topology_refresher.start();
        }

        Ok(())
@@ -598,28 +646,29 @@ where
        user_agent: Option<UserAgent>,
        client_stats_id: String,
        input_sender: Sender<InputMessage>,
-        shutdown: TaskClient,
+        task_client: TaskClient,
    ) -> ClientStatsSender {
        info!("Starting statistics control...");
-        StatisticsControl::create_and_start_with_shutdown(
+        StatisticsControl::create_and_start(
            config.debug.stats_reporting,
            user_agent
                .map(|u| u.application)
                .unwrap_or("unknown".to_string()),
            client_stats_id,
            input_sender.clone(),
-            shutdown.with_suffix("controller"),
+            task_client,
        )
    }

    fn start_mix_traffic_controller(
        gateway_transceiver: Box<dyn GatewayTransceiver + Send>,
        shutdown: TaskClient,
-    ) -> BatchMixMessageSender {
+    ) -> (BatchMixMessageSender, ClientRequestSender) {
        info!("Starting mix traffic controller...");
-        let (mix_traffic_controller, mix_tx) = MixTrafficController::new(gateway_transceiver);
-        mix_traffic_controller.start_with_shutdown(shutdown);
-        mix_tx
+        let (mix_traffic_controller, mix_tx, client_tx) =
+            MixTrafficController::new(gateway_transceiver, shutdown);
+        mix_traffic_controller.start();
+        (mix_tx, client_tx)
    }

    // TODO: rename it as it implies the data is persistent whilst one can use InMemBackend
@@ -654,6 +703,7 @@ where
        setup_method: GatewaySetup,
        key_store: &S::KeyStore,
        details_store: &S::GatewaysDetailsStore,
+        derivation_material: Option<DerivationMaterial>,
    ) -> Result<InitialisationResult, ClientCoreError>
    where
        <S::KeyStore as KeyStore>::StorageError: Sync + Send,
@@ -663,7 +713,12 @@ where
        if key_store.load_keys().await.is_err() {
            info!("could not find valid client keys - a new set will be generated");
            let mut rng = OsRng;
-            let keys = ClientKeys::generate_new(&mut rng);
+            let keys = if let Some(derivation_material) = derivation_material {
+                ClientKeys::from_master_key(&mut rng, &derivation_material)
+                    .map_err(|_| ClientCoreError::HkdfDerivationError {})?
+            } else {
+                ClientKeys::generate_new(&mut rng)
+            };
            store_client_keys(keys, key_store).await?;
        }

@@ -685,6 +740,7 @@ where
            self.setup_method,
            self.client_store.key_store(),
            self.client_store.gateway_details_store(),
+            self.derivation_material,
        )
        .await?;

@@ -708,7 +764,8 @@ where

        // channels responsible for controlling ack messages
        let (ack_sender, ack_receiver) = mpsc::unbounded();
-        let shared_topology_accessor = TopologyAccessor::new();
+        let shared_topology_accessor =
+            TopologyAccessor::new(self.config.debug.topology.ignore_egress_epoch_role);

        // Shutdown notifier for signalling tasks to stop
        let shutdown = self
@@ -740,7 +797,7 @@ where
        );

        let stats_reporter = Self::start_statistics_control(
-            self.config,
+            &self.config,
            self.user_agent.clone(),
            generate_client_stats_id(*self_address.identity()),
            input_sender.clone(),
@@ -766,12 +823,14 @@ where

        let gateway_transceiver = Self::setup_gateway_transceiver(
            self.custom_gateway_transceiver,
-            self.config,
+            &self.config,
            init_res,
            bandwidth_controller,
            &details_store,
            gateway_packet_router,
            stats_reporter.clone(),
+            #[cfg(unix)]
+            self.connection_fd_callback,
            shutdown.fork("gateway_transceiver"),
        )
        .await?;
@@ -797,7 +856,8 @@ where
        // that are to be sent to the mixnet. They are used by cover traffic stream and real
        // traffic stream.
        // The MixTrafficController then sends the actual traffic
-        let message_sender = Self::start_mix_traffic_controller(
+
+        let (message_sender, client_request_sender) = Self::start_mix_traffic_controller(
            gateway_transceiver,
            shutdown.fork("mix_traffic_controller"),
        );
@@ -874,6 +934,8 @@ where
            },
            stats_reporter,
            task_handle: shutdown,
+            client_request_sender,
+            forget_me: self.config.debug.forget_me,
        })
    }
 }
@@ -885,6 +947,7 @@ pub struct BaseClient {
    pub client_output: ClientOutputStatus,
    pub client_state: ClientState,
    pub stats_reporter: ClientStatsSender,
-
+    pub client_request_sender: ClientRequestSender,
    pub task_handle: TaskHandle,
+    pub forget_me: ForgetMe,
 }
@@ -88,7 +88,7 @@ pub async fn setup_fs_reply_surb_backend<P: AsRef<Path>>(
    let db_path = db_path.as_ref();
    if db_path.exists() {
        info!("loading existing surb database");
-        match fs_backend::Backend::try_load(db_path).await {
+        match fs_backend::Backend::try_load(db_path, surb_config.fresh_sender_tags).await {
            Ok(backend) => Ok(backend),
            Err(err) => {
                error!("failed to setup persistent storage backend for our reply needs: {err}. We're going to create a fresh database instead. This behaviour might change in the future");
@@ -4,6 +4,8 @@
 // TODO: combine those more closely. Perhaps into a single underlying store.
 // Like for persistent, on-disk, storage, what's the point of having 3 different databases?

+use rand::rngs::OsRng;
+
 use crate::client::key_manager::persistence::{InMemEphemeralKeys, KeyStore};
 use crate::client::replies::reply_storage;
 use crate::client::replies::reply_storage::ReplyStorageBackend;
@@ -63,7 +65,7 @@ pub trait MixnetClientStorage {
    fn gateway_details_store(&self) -> &Self::GatewaysDetailsStore;
 }

-#[derive(Default)]
+#[derive(Clone)]
 pub struct Ephemeral {
    key_store: InMemEphemeralKeys,
    reply_store: reply_storage::Empty,
@@ -71,9 +73,14 @@ pub struct Ephemeral {
    gateway_details_store: InMemGatewaysDetails,
 }

-impl Ephemeral {
-    pub fn new() -> Self {
-        Default::default()
+impl Default for Ephemeral {
+    fn default() -> Self {
+        Ephemeral {
+            key_store: InMemEphemeralKeys::new(&mut OsRng),
+            reply_store: Default::default(),
+            credential_store: Default::default(),
+            gateway_details_store: Default::default(),
+        }
    }
 }

@@ -114,6 +121,7 @@ impl MixnetClientStorage for Ephemeral {
    }
 }

+#[derive(Clone)]
 #[cfg(all(
    not(target_arch = "wasm32"),
    feature = "fs-surb-storage",
@@ -13,6 +13,7 @@ use nym_sphinx::cover::generate_loop_cover_packet;
 use nym_sphinx::params::{PacketSize, PacketType};
 use nym_sphinx::utils::sample_poisson_duration;
 use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, ClientStatsSender};
+use nym_task::TaskClient;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;
@@ -64,6 +65,8 @@ where
    packet_type: PacketType,

    stats_tx: ClientStatsSender,
+
+    task_client: TaskClient,
 }

 impl<R> Stream for LoopCoverTrafficStream<R>
@@ -110,6 +113,7 @@ impl LoopCoverTrafficStream<OsRng> {
        traffic_config: config::Traffic,
        cover_config: config::CoverTraffic,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        let rng = OsRng;

@@ -128,6 +132,7 @@ impl LoopCoverTrafficStream<OsRng> {
            secondary_packet_size: traffic_config.secondary_packet_size,
            packet_type: traffic_config.packet_type,
            stats_tx,
+            task_client,
        }
    }

@@ -163,6 +168,7 @@ impl LoopCoverTrafficStream<OsRng> {
        // poisson delay, but is it really a problem?
        let topology_permit = self.topology_access.get_read_permit().await;
        // the ack is sent back to ourselves (and then ignored)
+
        let topology_ref = match topology_permit.try_get_valid_topology_ref(
            &self.our_full_destination,
            Some(&self.our_full_destination),
@@ -174,7 +180,7 @@ impl LoopCoverTrafficStream<OsRng> {
            }
        };

-        let cover_message = generate_loop_cover_packet(
+        let cover_message = match generate_loop_cover_packet(
            &mut self.rng,
            topology_ref,
            &self.ack_key,
@@ -183,8 +189,15 @@ impl LoopCoverTrafficStream<OsRng> {
            self.cover_traffic.loop_cover_traffic_average_delay,
            cover_traffic_packet_size,
            self.packet_type,
-        )
-        .expect("Somehow failed to generate a loop cover message with a valid topology");
+        ) {
+            Ok(cover_message) => cover_message,
+            Err(err) => {
+                warn!(
+                    "Somehow failed to generate a loop cover message with a valid topology: {err}"
+                );
+                return;
+            }
+        };

        if let Err(err) = self.mix_tx.try_send(vec![cover_message]) {
            match err {
@@ -216,7 +229,7 @@ impl LoopCoverTrafficStream<OsRng> {
        tokio::task::yield_now().await;
    }

-    pub fn start_with_shutdown(mut self, mut shutdown: nym_task::TaskClient) {
+    pub fn start(mut self) {
        if self.cover_traffic.disable_loop_cover_traffic_stream {
            // we should have never got here in the first place - the task should have never been created to begin with
            // so panic and review the code that lead to this branch
@@ -230,6 +243,8 @@ impl LoopCoverTrafficStream<OsRng> {
        );
        self.set_next_delay(sampled);

+        let mut shutdown = self.task_client.fork("select");
+
        spawn_future(async move {
            debug!("Started LoopCoverTrafficStream with graceful shutdown support");

@@ -28,7 +28,7 @@ pub enum InputMessage {
        recipient: Recipient,
        data: Vec<u8>,
        lane: TransmissionLane,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    },

    /// Creates a message used for a duplex anonymous communication where the recipient
@@ -44,7 +44,7 @@ pub enum InputMessage {
        data: Vec<u8>,
        reply_surbs: u32,
        lane: TransmissionLane,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    },

    /// Attempt to use our internally received and stored `ReplySurb` to send the message back
@@ -55,6 +55,7 @@ pub enum InputMessage {
        recipient_tag: AnonymousSenderTag,
        data: Vec<u8>,
        lane: TransmissionLane,
+        max_retransmissions: Option<u32>,
    },

    MessageWrapper {
@@ -94,29 +95,7 @@ impl InputMessage {
            recipient,
            data,
            lane,
-            mix_hops: None,
-        };
-        if let Some(packet_type) = packet_type {
-            InputMessage::new_wrapper(message, packet_type)
-        } else {
-            message
-        }
-    }
-
-    // IMHO `new_regular` should take `mix_hops: Option<u8>` as an argument instead of creating
-    // this function, but that would potentially break backwards compatibility with the current API
-    pub fn new_regular_with_custom_hops(
-        recipient: Recipient,
-        data: Vec<u8>,
-        lane: TransmissionLane,
-        packet_type: Option<PacketType>,
-        mix_hops: Option<u8>,
-    ) -> Self {
-        let message = InputMessage::Regular {
-            recipient,
-            data,
-            lane,
-            mix_hops,
+            max_retransmissions: None,
        };
        if let Some(packet_type) = packet_type {
            InputMessage::new_wrapper(message, packet_type)
@@ -137,31 +116,7 @@ impl InputMessage {
            data,
            reply_surbs,
            lane,
-            mix_hops: None,
-        };
-        if let Some(packet_type) = packet_type {
-            InputMessage::new_wrapper(message, packet_type)
-        } else {
-            message
-        }
-    }
-
-    // IMHO `new_anonymous` should take `mix_hops: Option<u8>` as an argument instead of creating
-    // this function, but that would potentially break backwards compatibility with the current API
-    pub fn new_anonymous_with_custom_hops(
-        recipient: Recipient,
-        data: Vec<u8>,
-        reply_surbs: u32,
-        lane: TransmissionLane,
-        packet_type: Option<PacketType>,
-        mix_hops: Option<u8>,
-    ) -> Self {
-        let message = InputMessage::Anonymous {
-            recipient,
-            data,
-            reply_surbs,
-            lane,
-            mix_hops,
+            max_retransmissions: None,
        };
        if let Some(packet_type) = packet_type {
            InputMessage::new_wrapper(message, packet_type)
@@ -180,6 +135,7 @@ impl InputMessage {
            recipient_tag,
            data,
            lane,
+            max_retransmissions: None,
        };
        if let Some(packet_type) = packet_type {
            InputMessage::new_wrapper(message, packet_type)
@@ -197,4 +153,34 @@ impl InputMessage {
            InputMessage::MessageWrapper { message, .. } => message.lane(),
        }
    }
+
+    pub fn set_max_retransmissions(&mut self, max_retransmissions: u32) -> &mut Self {
+        match self {
+            InputMessage::Regular {
+                max_retransmissions: m,
+                ..
+            }
+            | InputMessage::Anonymous {
+                max_retransmissions: m,
+                ..
+            }
+            | InputMessage::Reply {
+                max_retransmissions: m,
+                ..
+            } => {
+                *m = Some(max_retransmissions);
+            }
+            InputMessage::Premade { .. } => {}
+            InputMessage::MessageWrapper { message, .. } => {
+                message.set_max_retransmissions(max_retransmissions);
+            }
+        }
+
+        self
+    }
+
+    pub fn with_max_retransmissions(mut self, max_retransmissions: u32) -> Self {
+        self.set_max_retransmissions(max_retransmissions);
+        self
+    }
 }
@@ -2,7 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::client::key_manager::persistence::KeyStore;
-use nym_crypto::asymmetric::{encryption, identity};
+use nym_crypto::{
+    asymmetric::{encryption, identity},
+    hkdf::{DerivationMaterial, InvalidLength},
+};
 use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
 use nym_sphinx::acknowledgements::AckKey;
 use rand::{CryptoRng, RngCore};
@@ -10,6 +13,7 @@ use std::sync::Arc;
 use zeroize::ZeroizeOnDrop;

 pub mod persistence;
+mod test;

 // Note: to support key rotation in the future, all keys will require adding an extra smart pointer,
 // most likely an AtomicCell, or if it doesn't work as I think it does, a Mutex. Although I think
@@ -43,6 +47,24 @@ impl ClientKeys {
        }
    }

+    pub fn from_master_key<R>(
+        rng: &mut R,
+        derivation_material: &DerivationMaterial,
+    ) -> Result<Self, InvalidLength>
+    where
+        R: RngCore + CryptoRng,
+    {
+        let secret = derivation_material.derive_secret()?;
+        Ok(ClientKeys {
+            identity_keypair: Arc::new(identity::KeyPair::from_secret(
+                secret,
+                derivation_material.index(),
+            )),
+            encryption_keypair: Arc::new(encryption::KeyPair::new(rng)),
+            ack_key: Arc::new(AckKey::new(rng)),
+        })
+    }
+
    pub fn from_keys(
        id_keypair: identity::KeyPair,
        enc_keypair: encryption::KeyPair,
@@ -3,7 +3,9 @@

 use crate::client::key_manager::ClientKeys;
 use async_trait::async_trait;
+use rand::{CryptoRng, RngCore};
 use std::error::Error;
+use std::sync::Arc;
 use tokio::sync::Mutex;

 #[cfg(not(target_arch = "wasm32"))]
@@ -64,6 +66,7 @@ pub enum OnDiskKeysError {
    },
 }

+#[derive(Clone)]
 #[cfg(not(target_arch = "wasm32"))]
 pub struct OnDiskKeys {
    paths: ClientKeysPaths,
@@ -193,9 +196,20 @@ impl KeyStore for OnDiskKeys {
    }
 }

-#[derive(Default)]
+#[derive(Clone)]
 pub struct InMemEphemeralKeys {
-    keys: Mutex<Option<ClientKeys>>,
+    keys: Arc<Mutex<ClientKeys>>,
+}
+
+impl InMemEphemeralKeys {
+    pub fn new<R>(rng: &mut R) -> Self
+    where
+        R: RngCore + CryptoRng,
+    {
+        InMemEphemeralKeys {
+            keys: Arc::new(Mutex::new(ClientKeys::generate_new(rng))),
+        }
+    }
 }

 #[derive(Debug, thiserror::Error)]
@@ -208,11 +222,11 @@ impl KeyStore for InMemEphemeralKeys {
    type StorageError = EphemeralKeysError;

    async fn load_keys(&self) -> Result<ClientKeys, Self::StorageError> {
-        self.keys.lock().await.clone().ok_or(EphemeralKeysError)
+        Ok(self.keys.lock().await.clone())
    }

    async fn store_keys(&self, keys: &ClientKeys) -> Result<(), Self::StorageError> {
-        *self.keys.lock().await = Some(keys.clone());
+        *self.keys.lock().await = keys.clone();
        Ok(())
    }
 }
@@ -0,0 +1,89 @@
+#[cfg(test)]
+mod tests {
+    use crate::client::key_manager::ClientKeys;
+    use nym_crypto::hkdf::DerivationMaterial;
+    use rand::SeedableRng;
+    use rand_chacha::ChaCha20Rng;
+
+    #[test]
+    fn test_from_master_key_success() {
+        // Set up a deterministic RNG.
+        let seed = [33u8; 32];
+        let mut rng = ChaCha20Rng::from_seed(seed);
+
+        // Set up the derivation material.
+        let master_key = b"this is a secret master key";
+        let salt = b"unique-salt";
+        let derivation_material = DerivationMaterial::new(master_key, 0, salt);
+
+        // Generate ClientKeys from the master key.
+        let client_keys = ClientKeys::from_master_key(&mut rng, &derivation_material)
+            .expect("Failed to create client keys");
+
+        assert_eq!(
+            client_keys.identity_keypair().public_key().to_string(),
+            String::from("FX4Undr5LPPBA7zThWWpAKXKQTXSbW1C28PnxbCqUkU4")
+        );
+
+        assert_eq!(
+            client_keys.identity_keypair().private_key().to_string(),
+            String::from("6S3uMi2rU5SwyUUYCiMrF5qqdcYnEDMYLggBSvavVzEt")
+        );
+    }
+
+    #[test]
+    fn test_from_master_key_deterministic_identity() {
+        // Using identical derivation material should result in the exactly same identity keypair.
+        let seed = [1u8; 32];
+        let mut rng1 = ChaCha20Rng::from_seed(seed);
+        let mut rng2 = ChaCha20Rng::from_seed(seed);
+
+        let master_key = b"another secret master key";
+        let salt = b"deterministic-salt";
+        let index = 7u32;
+        let derivation_material = DerivationMaterial::new(master_key, index, salt);
+
+        let client_keys1 = ClientKeys::from_master_key(&mut rng1, &derivation_material)
+            .expect("Failed to create client keys (first instance)");
+        let client_keys2 = ClientKeys::from_master_key(&mut rng2, &derivation_material)
+            .expect("Failed to create client keys (second instance)");
+
+        assert_eq!(
+            client_keys1.identity_keypair().public_key().to_string(),
+            client_keys2.identity_keypair().public_key().to_string()
+        );
+
+        assert_eq!(
+            client_keys1.identity_keypair().private_key().to_string(),
+            client_keys2.identity_keypair().private_key().to_string()
+        );
+    }
+
+    #[test]
+    fn test_from_master_key_different_indices() {
+        // Changing the index should yield a different identity key.
+        let seed = [5u8; 32];
+        let mut rng = ChaCha20Rng::from_seed(seed);
+
+        let master_key = b"same secret key";
+        let salt = b"same-salt";
+
+        let derivation_material1 = DerivationMaterial::new(master_key, 1, salt);
+        let derivation_material2 = DerivationMaterial::new(master_key, 2, salt);
+
+        let client_keys1 = ClientKeys::from_master_key(&mut rng, &derivation_material1)
+            .expect("Failed to create client keys for index 1");
+        let client_keys2 = ClientKeys::from_master_key(&mut rng, &derivation_material2)
+            .expect("Failed to create client keys for index 2");
+
+        assert_ne!(
+            client_keys1.identity_keypair().public_key().to_string(),
+            client_keys2.identity_keypair().public_key().to_string()
+        );
+
+        assert_ne!(
+            client_keys1.identity_keypair().private_key().to_string(),
+            client_keys2.identity_keypair().private_key().to_string()
+        );
+    }
+}
@@ -2,12 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::client::mix_traffic::transceiver::GatewayTransceiver;
+use crate::error::ClientCoreError;
 use crate::spawn_future;
 use log::*;
+use nym_gateway_requests::ClientRequest;
 use nym_sphinx::forwarding::packet::MixPacket;
+use nym_task::TaskClient;
+use transceiver::ErasedGatewayError;

 pub type BatchMixMessageSender = tokio::sync::mpsc::Sender<Vec<MixPacket>>;
 pub type BatchMixMessageReceiver = tokio::sync::mpsc::Receiver<Vec<MixPacket>>;
+pub type ClientRequestReceiver = tokio::sync::mpsc::Receiver<ClientRequest>;
+pub type ClientRequestSender = tokio::sync::mpsc::Sender<ClientRequest>;

 pub mod transceiver;

@@ -22,45 +28,73 @@ pub struct MixTrafficController {
    gateway_transceiver: Box<dyn GatewayTransceiver + Send>,

    mix_rx: BatchMixMessageReceiver,
+    client_rx: ClientRequestReceiver,

    // TODO: this is temporary work-around.
    // in long run `gateway_client` will be moved away from `MixTrafficController` anyway.
    consecutive_gateway_failure_count: usize,
+
+    task_client: TaskClient,
 }

 impl MixTrafficController {
-    pub fn new<T>(gateway_transceiver: T) -> (MixTrafficController, BatchMixMessageSender)
+    pub fn new<T>(
+        gateway_transceiver: T,
+        task_client: TaskClient,
+    ) -> (
+        MixTrafficController,
+        BatchMixMessageSender,
+        ClientRequestSender,
+    )
    where
        T: GatewayTransceiver + Send + 'static,
    {
        let (message_sender, message_receiver) =
            tokio::sync::mpsc::channel(MIX_MESSAGE_RECEIVER_BUFFER_SIZE);
+
+        let (client_sender, client_receiver) = tokio::sync::mpsc::channel(8);
+
        (
            MixTrafficController {
                gateway_transceiver: Box::new(gateway_transceiver),
                mix_rx: message_receiver,
+                client_rx: client_receiver,
                consecutive_gateway_failure_count: 0,
+                task_client,
            },
            message_sender,
+            client_sender,
        )
    }

    pub fn new_dynamic(
        gateway_transceiver: Box<dyn GatewayTransceiver + Send>,
-    ) -> (MixTrafficController, BatchMixMessageSender) {
+        task_client: TaskClient,
+    ) -> (
+        MixTrafficController,
+        BatchMixMessageSender,
+        ClientRequestSender,
+    ) {
        let (message_sender, message_receiver) =
            tokio::sync::mpsc::channel(MIX_MESSAGE_RECEIVER_BUFFER_SIZE);
+        let (client_sender, client_receiver) = tokio::sync::mpsc::channel(8);
        (
            MixTrafficController {
                gateway_transceiver,
                mix_rx: message_receiver,
+                client_rx: client_receiver,
                consecutive_gateway_failure_count: 0,
+                task_client,
            },
            message_sender,
+            client_sender,
        )
    }

-    async fn on_messages(&mut self, mut mix_packets: Vec<MixPacket>) {
+    async fn on_messages(
+        &mut self,
+        mut mix_packets: Vec<MixPacket>,
+    ) -> Result<(), ErasedGatewayError> {
        debug_assert!(!mix_packets.is_empty());

        let result = if mix_packets.len() == 1 {
@@ -72,46 +106,62 @@ impl MixTrafficController {
                .await
        };

-        match result {
-            Err(err) => {
-                error!("Failed to send sphinx packet(s) to the gateway: {err}");
-                self.consecutive_gateway_failure_count += 1;
-                if self.consecutive_gateway_failure_count == MAX_FAILURE_COUNT {
-                    // todo: in the future this should initiate a 'graceful' shutdown or try
-                    // to reconnect?
-                    panic!("failed to send sphinx packet to the gateway {MAX_FAILURE_COUNT} times in a row - assuming the gateway is dead. Can't do anything about it yet :(")
-                }
-            }
-            Ok(_) => {
-                trace!("We *might* have managed to forward sphinx packet(s) to the gateway!");
-                self.consecutive_gateway_failure_count = 0;
-            }
+        if result.is_err() {
+            self.consecutive_gateway_failure_count += 1;
+        } else {
+            trace!("We *might* have managed to forward sphinx packet(s) to the gateway!");
+            self.consecutive_gateway_failure_count = 0;
        }
+
+        result
    }

-    pub fn start_with_shutdown(mut self, mut shutdown: nym_task::TaskClient) {
+    pub fn start(mut self) {
        spawn_future(async move {
            debug!("Started MixTrafficController with graceful shutdown support");

-            loop {
+            while !self.task_client.is_shutdown() {
                tokio::select! {
                    mix_packets = self.mix_rx.recv() => match mix_packets {
                        Some(mix_packets) => {
-                            self.on_messages(mix_packets).await;
+                            if let Err(err) = self.on_messages(mix_packets).await {
+                                error!("Failed to send sphinx packet(s) to the gateway: {err}");
+                                if self.consecutive_gateway_failure_count == MAX_FAILURE_COUNT {
+                                    // Disconnect from the gateway. If we should try to re-connect
+                                    // is handled at a higher layer.
+                                    error!("Failed to send sphinx packet to the gateway {MAX_FAILURE_COUNT} times in a row - assuming the gateway is dead");
+                                    // Do we need to handle the embedded mixnet client case
+                                    // separately?
+                                    self.task_client.send_we_stopped(Box::new(ClientCoreError::GatewayFailedToForwardMessages));
+                                    break;
+                                }
+                            }
                        },
                        None => {
                            log::trace!("MixTrafficController: Stopping since channel closed");
                            break;
                        }
                    },
-                    _ = shutdown.recv_with_delay() => {
+                    client_request = self.client_rx.recv() => match client_request {
+                        Some(client_request) => {
+                            match self.gateway_transceiver.send_client_request(client_request).await {
+                                Ok(_) => (),
+                                Err(e) => error!("Failed to send client request: {}", e),
+                            };
+                        },
+                        None => {
+                            log::trace!("MixTrafficController, client request channel closed");
+                        }
+                    },
+                    _ = self.task_client.recv() => {
                        log::trace!("MixTrafficController: Received shutdown");
                        break;
                    }
                }
            }
-            shutdown.recv_timeout().await;
+            self.task_client.recv_timeout().await;
+
            log::debug!("MixTrafficController: Exiting");
-        })
+        });
    }
 }
@@ -5,8 +5,10 @@ use async_trait::async_trait;
 use log::{debug, error};
 use nym_credential_storage::storage::Storage as CredentialStorage;
 use nym_crypto::asymmetric::identity;
+use nym_gateway_client::error::GatewayClientError;
 use nym_gateway_client::GatewayClient;
 pub use nym_gateway_client::{GatewayPacketRouter, PacketRouter};
+use nym_gateway_requests::ClientRequest;
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use std::fmt::Debug;
@@ -26,9 +28,14 @@ fn erase_err<E: std::error::Error + Send + Sync + 'static>(err: E) -> ErasedGate
 }

 /// This combines combines the functionalities of being able to send and receive mix packets.
+#[async_trait]
 pub trait GatewayTransceiver: GatewaySender + GatewayReceiver {
    fn gateway_identity(&self) -> identity::PublicKey;
    fn ws_fd(&self) -> Option<RawFd>;
+    async fn send_client_request(
+        &mut self,
+        message: ClientRequest,
+    ) -> Result<(), GatewayClientError>;
 }

 /// This trait defines the functionality of sending `MixPacket` into the mixnet,
@@ -65,6 +72,7 @@ pub trait GatewayReceiver {
 }

 // to allow for dynamic dispatch
+#[async_trait]
 impl<G: GatewayTransceiver + ?Sized + Send> GatewayTransceiver for Box<G> {
    #[inline]
    fn gateway_identity(&self) -> identity::PublicKey {
@@ -73,6 +81,15 @@ impl<G: GatewayTransceiver + ?Sized + Send> GatewayTransceiver for Box<G> {
    fn ws_fd(&self) -> Option<RawFd> {
        (**self).ws_fd()
    }
+
+    async fn send_client_request(
+        &mut self,
+        message: ClientRequest,
+    ) -> Result<(), GatewayClientError> {
+        let _ = (**self).send_client_request(message.clone()).await?;
+        log::debug!("Sent client request: {:?}", message);
+        Ok(())
+    }
 }

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -91,7 +108,6 @@ impl<G: GatewaySender + ?Sized + Send> GatewaySender for Box<G> {
        (**self).batch_send_mix_packets(packets).await
    }
 }
-
 impl<G: GatewayReceiver + ?Sized> GatewayReceiver for Box<G> {
    #[inline]
    fn set_packet_router(&mut self, packet_router: PacketRouter) -> Result<(), ErasedGatewayError> {
@@ -111,6 +127,7 @@ impl<C, St> RemoteGateway<C, St> {
    }
 }

+#[async_trait]
 impl<C, St> GatewayTransceiver for RemoteGateway<C, St>
 where
    C: DkgQueryClient + Send + Sync,
@@ -123,6 +140,13 @@ where
    fn ws_fd(&self) -> Option<RawFd> {
        self.gateway_client.ws_fd()
    }
+
+    async fn send_client_request(
+        &mut self,
+        message: ClientRequest,
+    ) -> Result<(), GatewayClientError> {
+        self.gateway_client.send_client_request(message).await
+    }
 }

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -195,6 +219,7 @@ impl LocalGateway {
 mod nonwasm_sealed {
    use super::*;

+    #[async_trait]
    impl GatewayTransceiver for LocalGateway {
        fn gateway_identity(&self) -> identity::PublicKey {
            self.local_identity
@@ -202,6 +227,13 @@ mod nonwasm_sealed {
        fn ws_fd(&self) -> Option<RawFd> {
            None
        }
+
+        async fn send_client_request(
+            &mut self,
+            _message: ClientRequest,
+        ) -> Result<(), GatewayClientError> {
+            Ok(())
+        }
    }

    #[async_trait]
@@ -269,6 +301,7 @@ impl GatewaySender for MockGateway {
    }
 }

+#[async_trait]
 impl GatewayTransceiver for MockGateway {
    fn gateway_identity(&self) -> identity::PublicKey {
        self.dummy_identity
@@ -276,4 +309,11 @@ impl GatewayTransceiver for MockGateway {
    fn ws_fd(&self) -> Option<RawFd> {
        None
    }
+
+    async fn send_client_request(
+        &mut self,
+        _message: ClientRequest,
+    ) -> Result<(), GatewayClientError> {
+        Ok(())
+    }
 }
@@ -11,6 +11,7 @@ use nym_sphinx::{
    acknowledgements::{identifier::recover_identifier, AckKey},
    chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID},
 };
+use nym_task::TaskClient;
 use std::sync::Arc;

 /// Module responsible for listening for any data resembling acknowledgements from the network
@@ -20,6 +21,7 @@ pub(super) struct AcknowledgementListener {
    ack_receiver: AcknowledgementReceiver,
    action_sender: AckActionSender,
    stats_tx: ClientStatsSender,
+    task_client: TaskClient,
 }

 impl AcknowledgementListener {
@@ -28,12 +30,14 @@ impl AcknowledgementListener {
        ack_receiver: AcknowledgementReceiver,
        action_sender: AckActionSender,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        AcknowledgementListener {
            ack_key,
            ack_receiver,
            action_sender,
            stats_tx,
+            task_client,
        }
    }

@@ -64,9 +68,14 @@ impl AcknowledgementListener {
        trace!("Received {} from the mix network", frag_id);
        self.stats_tx
            .report(PacketStatisticsEvent::RealAckReceived(ack_content.len()).into());
-        self.action_sender
+        if let Err(err) = self
+            .action_sender
            .unbounded_send(Action::new_remove(frag_id))
-            .unwrap();
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send remove action to action controller: {err}");
+            }
+        }
    }

    async fn handle_ack_receiver_item(&mut self, item: Vec<Vec<u8>>) {
@@ -76,10 +85,10 @@ impl AcknowledgementListener {
        }
    }

-    pub(super) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(super) async fn run(&mut self) {
        debug!("Started AcknowledgementListener with graceful shutdown support");

-        while !shutdown.is_shutdown() {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                acks = self.ack_receiver.next() => match acks {
                    Some(acks) => self.handle_ack_receiver_item(acks).await,
@@ -88,12 +97,12 @@ impl AcknowledgementListener {
                        break;
                    }
                },
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv() => {
                    log::trace!("AcknowledgementListener: Received shutdown");
                }
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv_timeout().await;
        log::debug!("AcknowledgementListener: Exiting");
    }
 }
@@ -9,6 +9,7 @@ use log::*;
 use nym_nonexhaustive_delayqueue::{Expired, NonExhaustiveDelayQueue, QueueKey};
 use nym_sphinx::chunking::fragment::FragmentIdentifier;
 use nym_sphinx::Delay as SphinxDelay;
+use nym_task::TaskClient;
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
@@ -101,6 +102,8 @@ pub(super) struct ActionController {

    /// Channel for notifying `RetransmissionRequestListener` about expired acknowledgements.
    retransmission_sender: RetransmissionRequestSender,
+
+    task_client: TaskClient,
 }

 impl ActionController {
@@ -108,6 +111,7 @@ impl ActionController {
        config: Config,
        retransmission_sender: RetransmissionRequestSender,
        incoming_actions: AckActionReceiver,
+        task_client: TaskClient,
    ) -> Self {
        ActionController {
            config,
@@ -115,6 +119,7 @@ impl ActionController {
            pending_acks_timers: NonExhaustiveDelayQueue::new(),
            incoming_actions,
            retransmission_sender,
+            task_client,
        }
    }

@@ -216,14 +221,7 @@ impl ActionController {
    }

    // note: when the entry expires it's automatically removed from pending_acks_timers
-    fn handle_expired_ack_timer(
-        &mut self,
-        expired_ack: Expired<FragmentIdentifier>,
-        task_client: &mut nym_task::TaskClient,
-    ) {
-        // I'm honestly not sure how to handle it, because getting it means other things in our
-        // system are already misbehaving. If we ever see this panic, then I guess we should worry
-        // about it. Perhaps just reschedule it at later point?
+    fn handle_expired_ack_timer(&mut self, expired_ack: Expired<FragmentIdentifier>) {
        let frag_id = expired_ack.into_inner();

        trace!("{frag_id} has expired");
@@ -238,15 +236,13 @@ impl ActionController {
            // downgrading an arc and then upgrading vs cloning is difference of 30ns vs 15ns
            // so it's literally a NO difference while it might prevent us from unnecessarily
            // resending data (in maybe 1 in 1 million cases, but it's something)
-            if self
+            if let Err(err) = self
                .retransmission_sender
                .unbounded_send(Arc::downgrade(pending_ack_data))
-                .is_err()
            {
-                assert!(
-                    task_client.is_shutdown_poll(),
-                    "Failed to send pending ack for retransmission"
-                );
+                if !self.task_client.is_shutdown_poll() {
+                    log::error!("Failed to send pending ack for retransmission: {err}");
+                }
            }
        } else {
            // this shouldn't cause any issues but shouldn't have happened to begin with!
@@ -265,10 +261,10 @@ impl ActionController {
        }
    }

-    pub(super) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(super) async fn run(&mut self) {
        debug!("Started ActionController with graceful shutdown support");

-        loop {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                action = self.incoming_actions.next() => match action {
                    Some(action) => self.process_action(action),
@@ -280,19 +276,19 @@ impl ActionController {
                    }
                },
                expired_ack = self.pending_acks_timers.next() => match expired_ack {
-                    Some(expired_ack) => self.handle_expired_ack_timer(expired_ack, &mut shutdown),
+                    Some(expired_ack) => self.handle_expired_ack_timer(expired_ack),
                    None => {
                        log::trace!("ActionController: Stopping since ack channel closed");
                        break;
                    }
                },
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv() => {
                    log::trace!("ActionController: Received shutdown");
                    break;
                }
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv_timeout().await;
        log::debug!("ActionController: Exiting");
    }
 }
@@ -11,6 +11,7 @@ use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;
+use nym_task::TaskClient;
 use rand::{CryptoRng, Rng};

 /// Module responsible for dealing with the received messages: splitting them, creating acknowledgements,
@@ -23,6 +24,7 @@ where
    input_receiver: InputMessageReceiver,
    message_handler: MessageHandler<R>,
    reply_controller_sender: ReplyControllerSender,
+    task_client: TaskClient,
 }

 impl<R> InputMessageListener<R>
@@ -36,11 +38,13 @@ where
        input_receiver: InputMessageReceiver,
        message_handler: MessageHandler<R>,
        reply_controller_sender: ReplyControllerSender,
+        task_client: TaskClient,
    ) -> Self {
        InputMessageListener {
            input_receiver,
            message_handler,
            reply_controller_sender,
+            task_client,
        }
    }

@@ -61,10 +65,17 @@ where
        recipient_tag: AnonymousSenderTag,
        data: Vec<u8>,
        lane: TransmissionLane,
+        max_retransmissions: Option<u32>,
    ) {
        // offload reply handling to the dedicated task
-        self.reply_controller_sender
-            .send_reply(recipient_tag, data, lane)
+        if let Err(err) =
+            self.reply_controller_sender
+                .send_reply(recipient_tag, data, lane, max_retransmissions)
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("failed to send a reply - {err}");
+            }
+        }
    }

    async fn handle_plain_message(
@@ -73,11 +84,11 @@ where
        content: Vec<u8>,
        lane: TransmissionLane,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) {
        if let Err(err) = self
            .message_handler
-            .try_send_plain_message(recipient, content, lane, packet_type, mix_hops)
+            .try_send_plain_message(recipient, content, lane, packet_type, max_retransmissions)
            .await
        {
            warn!("failed to send a plain message - {err}")
@@ -91,7 +102,7 @@ where
        reply_surbs: u32,
        lane: TransmissionLane,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) {
        if let Err(err) = self
            .message_handler
@@ -101,7 +112,7 @@ where
                reply_surbs,
                lane,
                packet_type,
-                mix_hops,
+                max_retransmissions,
            )
            .await
        {
@@ -115,17 +126,23 @@ where
                recipient,
                data,
                lane,
-                mix_hops,
+                max_retransmissions,
            } => {
-                self.handle_plain_message(recipient, data, lane, PacketType::Mix, mix_hops)
-                    .await
+                self.handle_plain_message(
+                    recipient,
+                    data,
+                    lane,
+                    PacketType::Mix,
+                    max_retransmissions,
+                )
+                .await
            }
            InputMessage::Anonymous {
                recipient,
                data,
                reply_surbs,
                lane,
-                mix_hops,
+                max_retransmissions,
            } => {
                self.handle_repliable_message(
                    recipient,
@@ -133,7 +150,7 @@ where
                    reply_surbs,
                    lane,
                    PacketType::Mix,
-                    mix_hops,
+                    max_retransmissions,
                )
                .await
            }
@@ -141,8 +158,10 @@ where
                recipient_tag,
                data,
                lane,
+                max_retransmissions,
            } => {
-                self.handle_reply(recipient_tag, data, lane).await;
+                self.handle_reply(recipient_tag, data, lane, max_retransmissions)
+                    .await;
            }
            InputMessage::Premade { msgs, lane } => self.handle_premade_packets(msgs, lane).await,
            InputMessage::MessageWrapper {
@@ -153,17 +172,23 @@ where
                    recipient,
                    data,
                    lane,
-                    mix_hops,
+                    max_retransmissions,
                } => {
-                    self.handle_plain_message(recipient, data, lane, packet_type, mix_hops)
-                        .await
+                    self.handle_plain_message(
+                        recipient,
+                        data,
+                        lane,
+                        packet_type,
+                        max_retransmissions,
+                    )
+                    .await
                }
                InputMessage::Anonymous {
                    recipient,
                    data,
                    reply_surbs,
                    lane,
-                    mix_hops,
+                    max_retransmissions,
                } => {
                    self.handle_repliable_message(
                        recipient,
@@ -171,7 +196,7 @@ where
                        reply_surbs,
                        lane,
                        packet_type,
-                        mix_hops,
+                        max_retransmissions,
                    )
                    .await
                }
@@ -179,8 +204,10 @@ where
                    recipient_tag,
                    data,
                    lane,
+                    max_retransmissions,
                } => {
-                    self.handle_reply(recipient_tag, data, lane).await;
+                    self.handle_reply(recipient_tag, data, lane, max_retransmissions)
+                        .await;
                }
                InputMessage::Premade { msgs, lane } => {
                    self.handle_premade_packets(msgs, lane).await
@@ -191,10 +218,10 @@ where
        };
    }

-    pub(super) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(super) async fn run(&mut self) {
        debug!("Started InputMessageListener with graceful shutdown support");

-        while !shutdown.is_shutdown() {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                input_msg = self.input_receiver.recv() => match input_msg {
                    Some(input_msg) => {
@@ -205,12 +232,12 @@ where
                        break;
                    }
                },
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv() => {
                    log::trace!("InputMessageListener: Received shutdown");
                }
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv_timeout().await;
        log::debug!("InputMessageListener: Exiting");
    }
 }
@@ -24,6 +24,7 @@ use nym_sphinx::{
    Delay as SphinxDelay,
 };
 use nym_statistics_common::clients::ClientStatsSender;
+use nym_task::TaskClient;
 use rand::{CryptoRng, Rng};
 use std::{
    sync::{Arc, Weak},
@@ -66,12 +67,12 @@ pub(crate) enum PacketDestination {

 /// Structure representing a data `Fragment` that is on-route to the specified `Recipient`
 #[derive(Debug)]
-pub(crate) struct PendingAcknowledgement {
+pub struct PendingAcknowledgement {
    message_chunk: Fragment,
    delay: SphinxDelay,
    destination: PacketDestination,
-    mix_hops: Option<u8>,
    retransmissions: u32,
+    max_retransmissions: Option<u32>,
 }

 impl PendingAcknowledgement {
@@ -80,14 +81,14 @@ impl PendingAcknowledgement {
        message_chunk: Fragment,
        delay: SphinxDelay,
        recipient: Recipient,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) -> Self {
        PendingAcknowledgement {
            message_chunk,
            delay,
            destination: PacketDestination::KnownRecipient(recipient.into()),
-            mix_hops,
            retransmissions: 0,
+            max_retransmissions,
        }
    }

@@ -96,6 +97,7 @@ impl PendingAcknowledgement {
        delay: SphinxDelay,
        recipient_tag: AnonymousSenderTag,
        extra_surb_request: bool,
+        max_retransmissions: Option<u32>,
    ) -> Self {
        PendingAcknowledgement {
            message_chunk,
@@ -104,10 +106,8 @@ impl PendingAcknowledgement {
                recipient_tag,
                extra_surb_request,
            },
-            // Messages sent using SURBs are using the number of mix hops set by the recipient when
-            // they provided the SURBs, so it doesn't make sense to include it here.
-            mix_hops: None,
            retransmissions: 0,
+            max_retransmissions,
        }
    }

@@ -123,6 +123,18 @@ impl PendingAcknowledgement {
        self.delay = new_delay;
        self.retransmissions += 1;
    }
+
+    pub(crate) fn reached_max_retransmissions(
+        &self,
+        global_max_retransmissions: Option<u32>,
+    ) -> bool {
+        let reached_local_max = self
+            .max_retransmissions
+            .is_some_and(|limit| self.retransmissions >= limit);
+        let reached_global_max =
+            global_max_retransmissions.is_some_and(|limit| self.retransmissions >= limit);
+        reached_local_max || reached_global_max
+    }
 }

 /// AcknowledgementControllerConnectors represents set of channels for communication with
@@ -222,6 +234,7 @@ where
        message_handler: MessageHandler<R>,
        reply_controller_sender: ReplyControllerSender,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        let (retransmission_tx, retransmission_rx) = mpsc::unbounded();

@@ -231,6 +244,7 @@ where
            action_config,
            retransmission_tx,
            connectors.ack_action_receiver,
+            task_client.fork("action_controller"),
        );

        // will listen for any acks coming from the network
@@ -239,6 +253,7 @@ where
            connectors.ack_receiver,
            connectors.ack_action_sender.clone(),
            stats_tx,
+            task_client.fork("acknowledgement_listener"),
        );

        // will listen for any new messages from the client
@@ -246,6 +261,7 @@ where
            connectors.input_receiver,
            message_handler.clone(),
            reply_controller_sender.clone(),
+            task_client.fork("input_message_listener"),
        );

        // will listen for any ack timeouts and trigger retransmission
@@ -255,12 +271,16 @@ where
            message_handler,
            retransmission_rx,
            reply_controller_sender,
+            task_client.fork("retransmission_request_listener"),
        );

        // will listen for events indicating the packet was sent through the network so that
        // the retransmission timer should be started.
-        let sent_notification_listener =
-            SentNotificationListener::new(connectors.sent_notifier, connectors.ack_action_sender);
+        let sent_notification_listener = SentNotificationListener::new(
+            connectors.sent_notifier,
+            connectors.ack_action_sender,
+            task_client.with_suffix("sent_notification_listener"),
+        );

        AcknowledgementController {
            acknowledgement_listener,
@@ -271,53 +291,35 @@ where
        }
    }

-    pub(super) fn start_with_shutdown(
-        self,
-        shutdown: nym_task::TaskClient,
-        packet_type: PacketType,
-    ) {
+    pub(super) fn start(self, packet_type: PacketType) {
        let mut acknowledgement_listener = self.acknowledgement_listener;
        let mut input_message_listener = self.input_message_listener;
        let mut retransmission_request_listener = self.retransmission_request_listener;
        let mut sent_notification_listener = self.sent_notification_listener;
        let mut action_controller = self.action_controller;

-        let shutdown_handle = shutdown.fork("acknowledgement_listener");
        spawn_future(async move {
-            acknowledgement_listener
-                .run_with_shutdown(shutdown_handle)
-                .await;
+            acknowledgement_listener.run().await;
            debug!("The acknowledgement listener has finished execution!");
        });

-        let shutdown_handle = shutdown.fork("input_message_listener");
        spawn_future(async move {
-            input_message_listener
-                .run_with_shutdown(shutdown_handle)
-                .await;
+            input_message_listener.run().await;
            debug!("The input listener has finished execution!");
        });

-        let shutdown_handle = shutdown.fork("retransmission_request_listener");
        spawn_future(async move {
-            retransmission_request_listener
-                .run_with_shutdown(shutdown_handle, packet_type)
-                .await;
+            retransmission_request_listener.run(packet_type).await;
            debug!("The retransmission request listener has finished execution!");
        });

-        let shutdown_handle = shutdown.fork("sent_notification_listener");
        spawn_future(async move {
-            sent_notification_listener
-                .run_with_shutdown(shutdown_handle)
-                .await;
+            sent_notification_listener.run().await;
            debug!("The sent notification listener has finished execution!");
        });

        spawn_future(async move {
-            action_controller
-                .run_with_shutdown(shutdown.with_suffix("action_controller"))
-                .await;
+            action_controller.run().await;
            debug!("The controller has finished execution!");
        });
    }
@@ -14,7 +14,7 @@ use log::*;
 use nym_sphinx::chunking::fragment::Fragment;
 use nym_sphinx::preparer::PreparedFragment;
 use nym_sphinx::{addressing::clients::Recipient, params::PacketType};
-use nym_task::connections::TransmissionLane;
+use nym_task::{connections::TransmissionLane, TaskClient};
 use rand::{CryptoRng, Rng};
 use std::sync::{Arc, Weak};

@@ -25,6 +25,7 @@ pub(super) struct RetransmissionRequestListener<R> {
    message_handler: MessageHandler<R>,
    request_receiver: RetransmissionRequestReceiver,
    reply_controller_sender: ReplyControllerSender,
+    task_client: TaskClient,
 }

 impl<R> RetransmissionRequestListener<R>
@@ -37,6 +38,7 @@ where
        message_handler: MessageHandler<R>,
        request_receiver: RetransmissionRequestReceiver,
        reply_controller_sender: ReplyControllerSender,
+        task_client: TaskClient,
    ) -> Self {
        RetransmissionRequestListener {
            maximum_retransmissions,
@@ -44,6 +46,7 @@ where
            message_handler,
            request_receiver,
            reply_controller_sender,
+            task_client,
        }
    }

@@ -52,18 +55,12 @@ where
        packet_recipient: Recipient,
        chunk_data: Fragment,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
    ) -> Result<PreparedFragment, PreparationError> {
        debug!("retransmitting normal packet...");

        // TODO: Figure out retransmission packet type signaling
        self.message_handler
-            .try_prepare_single_chunk_for_sending(
-                packet_recipient,
-                chunk_data,
-                packet_type,
-                mix_hops,
-            )
+            .try_prepare_single_chunk_for_sending(packet_recipient, chunk_data, packet_type)
            .await
    }

@@ -82,14 +79,15 @@ where

        let frag_id = timed_out_ack.message_chunk.fragment_identifier();

-        if let Some(limit) = self.maximum_retransmissions {
-            if timed_out_ack.retransmissions >= limit {
-                warn!("reached maximum number of allowed retransmissions for the packet");
-                self.action_sender
-                    .unbounded_send(Action::new_remove(frag_id))
-                    .unwrap();
-                return;
+        if timed_out_ack.reached_max_retransmissions(self.maximum_retransmissions) {
+            debug!("reached maximum number of allowed retransmissions for the packet");
+            if let Err(err) = self
+                .action_sender
+                .unbounded_send(Action::new_remove(frag_id))
+            {
+                error!("Failed to send remove action to the controller: {err}");
            }
+            return;
        }

        let maybe_prepared_fragment = match &timed_out_ack.destination {
@@ -99,18 +97,22 @@ where
            } => {
                // if this is retransmission for reply, offload it to the dedicated task
                // that deals with all the surbs
-                return self.reply_controller_sender.send_retransmission_data(
+                if let Err(err) = self.reply_controller_sender.send_retransmission_data(
                    *recipient_tag,
                    weak_timed_out_ack,
                    *extra_surb_request,
-                );
+                ) {
+                    if !self.task_client.is_shutdown_poll() {
+                        error!("Failed to send retransmission data to the reply controller: {err}");
+                    }
+                }
+                return;
            }
            PacketDestination::KnownRecipient(recipient) => {
                self.prepare_normal_retransmission_chunk(
                    **recipient,
                    timed_out_ack.message_chunk.clone(),
                    packet_type,
-                    timed_out_ack.mix_hops,
                )
                .await
            }
@@ -121,9 +123,12 @@ where
            Err(err) => {
                warn!("Could not retransmit the packet - {err}");
                // we NEED to start timer here otherwise we will have this guy permanently stuck in memory
-                self.action_sender
+                if let Err(err) = self
+                    .action_sender
                    .unbounded_send(Action::new_start_timer(frag_id))
-                    .unwrap();
+                {
+                    error!("Failed to send start timer action to the controller: {err}");
+                }
                return;
            }
        };
@@ -148,9 +153,14 @@ where
        // is sent to the `OutQueueControl` and has gone through its internal queue
        // with the additional poisson delay.
        // And since Actions are executed in order `UpdateTimer` will HAVE TO be executed before `StartTimer`
-        self.action_sender
+        if let Err(err) = self
+            .action_sender
            .unbounded_send(Action::new_update_pending_ack(frag_id, new_delay))
-            .unwrap();
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send update pending ack action to the controller: {err}");
+            }
+        }

        // send to `OutQueueControl` to eventually send to the mix network
        self.message_handler
@@ -164,14 +174,10 @@ where
            .await
    }

-    pub(super) async fn run_with_shutdown(
-        &mut self,
-        mut shutdown: nym_task::TaskClient,
-        packet_type: PacketType,
-    ) {
+    pub(super) async fn run(&mut self, packet_type: PacketType) {
        debug!("Started RetransmissionRequestListener with graceful shutdown support");

-        while !shutdown.is_shutdown() {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                timed_out_ack = self.request_receiver.next() => match timed_out_ack {
                    Some(timed_out_ack) => self.on_retransmission_request(timed_out_ack, packet_type).await,
@@ -180,12 +186,12 @@ where
                        break;
                    }
                },
-                _ = shutdown.recv() => {
+                _ = self.task_client.recv() => {
                    log::trace!("RetransmissionRequestListener: Received shutdown");
                }
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv_timeout().await;
        log::debug!("RetransmissionRequestListener: Exiting");
    }
 }
@@ -6,6 +6,7 @@ use super::SentPacketNotificationReceiver;
 use futures::StreamExt;
 use log::*;
 use nym_sphinx::chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID};
+use nym_task::TaskClient;

 /// Module responsible for starting up retransmission timers.
 /// It is required because when we send our packet to the `real traffic stream` controlled
@@ -14,16 +15,19 @@ use nym_sphinx::chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID};
 pub(super) struct SentNotificationListener {
    sent_notifier: SentPacketNotificationReceiver,
    action_sender: AckActionSender,
+    task_client: TaskClient,
 }

 impl SentNotificationListener {
    pub(super) fn new(
        sent_notifier: SentPacketNotificationReceiver,
        action_sender: AckActionSender,
+        task_client: TaskClient,
    ) -> Self {
        SentNotificationListener {
            sent_notifier,
            action_sender,
+            task_client,
        }
    }

@@ -32,15 +36,20 @@ impl SentNotificationListener {
            trace!("sent off a cover message - no need to start retransmission timer!");
            return;
        }
-        self.action_sender
+        if let Err(err) = self
+            .action_sender
            .unbounded_send(Action::new_start_timer(frag_id))
-            .unwrap();
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send start timer action to action controller: {err}");
+            }
+        }
    }

-    pub(super) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(super) async fn run(&mut self) {
        debug!("Started SentNotificationListener with graceful shutdown support");

-        loop {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                frag_id = self.sent_notifier.next() => match frag_id {
                    Some(frag_id) => {
@@ -51,13 +60,13 @@ impl SentNotificationListener {
                        break;
                    }
                },
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv() => {
                    log::trace!("SentNotificationListener: Received shutdown");
                    break;
                }
            }
        }
-        assert!(shutdown.is_shutdown_poll());
+        assert!(self.task_client.is_shutdown_poll());
        log::debug!("SentNotificationListener: Exiting");
    }
 }
@@ -6,6 +6,7 @@ use crate::client::real_messages_control::real_traffic_stream::{
    BatchRealMessageSender, RealMessage,
 };
 use crate::client::real_messages_control::{AckActionSender, Action};
+use crate::client::replies::reply_controller::MaxRetransmissions;
 use crate::client::replies::reply_storage::{ReceivedReplySurbsMap, SentReplyKeys, UsedSenderTags};
 use crate::client::topology_control::{TopologyAccessor, TopologyReadPermit};
 use log::{debug, error, info, trace, warn};
@@ -15,11 +16,12 @@ use nym_sphinx::anonymous_replies::requests::{AnonymousSenderTag, RepliableMessa
 use nym_sphinx::anonymous_replies::{ReplySurb, SurbEncryptionKey};
 use nym_sphinx::chunking::fragment::{Fragment, FragmentIdentifier};
 use nym_sphinx::message::NymMessage;
-use nym_sphinx::params::{PacketSize, PacketType, DEFAULT_NUM_MIX_HOPS};
+use nym_sphinx::params::{PacketSize, PacketType};
 use nym_sphinx::preparer::{MessagePreparer, PreparedFragment};
 use nym_sphinx::Delay;
 use nym_task::connections::TransmissionLane;
-use nym_topology::{NymTopology, NymTopologyError};
+use nym_task::TaskClient;
+use nym_topology::{NymRouteProvider, NymTopologyError};
 use rand::{CryptoRng, Rng};
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -32,10 +34,12 @@ pub enum PreparationError {
    #[error(transparent)]
    NymTopologyError(#[from] NymTopologyError),

-    #[error("The received message cannot be sent using a single reply surb. It ended up getting split into {fragments} fragments.")]
+    #[error("message too long for a single SURB, splitting into {fragments} fragments.")]
    MessageTooLongForSingleSurb { fragments: usize },

-    #[error("Not enough reply SURBs to send the message. We have {available} available and require at least {required}.")]
+    #[error(
+        "not enough reply SURBs to send the message, available: {available} required: {required}."
+    )]
    NotEnoughSurbs { available: usize, required: usize },
 }

@@ -100,10 +104,6 @@ pub(crate) struct Config {
    /// Average delay an acknowledgement packet is going to get delay at a single mixnode.
    average_ack_delay: Duration,

-    /// Number of mix hops each packet ('real' message, ack, reply) is expected to take.
-    /// Note that it does not include gateway hops.
-    num_mix_hops: u8,
-
    /// Primary predefined packet size used for the encapsulated messages.
    primary_packet_size: PacketSize,

@@ -125,19 +125,11 @@ impl Config {
            deterministic_route_selection,
            average_packet_delay,
            average_ack_delay,
-            num_mix_hops: DEFAULT_NUM_MIX_HOPS,
            primary_packet_size: PacketSize::default(),
            secondary_packet_size: None,
        }
    }

-    /// Allows setting non-default number of expected mix hops in the network.
-    #[allow(dead_code)]
-    pub fn with_mix_hops(mut self, hops: u8) -> Self {
-        self.num_mix_hops = hops;
-        self
-    }
-
    /// Allows setting non-default size of the sphinx packets sent out.
    pub fn with_custom_primary_packet_size(mut self, packet_size: PacketSize) -> Self {
        self.primary_packet_size = packet_size;
@@ -151,6 +143,12 @@ impl Config {
    }
 }

+#[derive(Clone)]
+pub(crate) struct FragmentWithMaxRetransmissions {
+    pub(crate) fragment: Fragment,
+    pub(crate) max_retransmissions: MaxRetransmissions,
+}
+
 #[derive(Clone)]
 pub(crate) struct MessageHandler<R> {
    config: Config,
@@ -161,12 +159,14 @@ pub(crate) struct MessageHandler<R> {
    topology_access: TopologyAccessor,
    reply_key_storage: SentReplyKeys,
    tag_storage: UsedSenderTags,
+    task_client: TaskClient,
 }

 impl<R> MessageHandler<R>
 where
    R: CryptoRng + Rng,
 {
+    #[allow(clippy::too_many_arguments)]
    pub(crate) fn new(
        config: Config,
        rng: R,
@@ -175,6 +175,7 @@ where
        topology_access: TopologyAccessor,
        reply_key_storage: SentReplyKeys,
        tag_storage: UsedSenderTags,
+        task_client: TaskClient,
    ) -> Self
    where
        R: Copy,
@@ -185,9 +186,7 @@ where
            config.sender_address,
            config.average_packet_delay,
            config.average_ack_delay,
-        )
-        .with_mix_hops(config.num_mix_hops);
-
+        );
        MessageHandler {
            config,
            rng,
@@ -197,6 +196,7 @@ where
            topology_access,
            reply_key_storage,
            tag_storage,
+            task_client,
        }
    }

@@ -205,10 +205,10 @@ where
            trace!("we already had sender tag for {recipient}");
            existing
        } else {
-            info!("creating new sender tag for {recipient}");
+            debug!("creating new sender tag for {recipient}");
            let new_tag = AnonymousSenderTag::new_random(&mut self.rng);
            self.tag_storage.insert_new(recipient, new_tag);
-            info!("we'll be using {new_tag} for all anonymous messages sent to {recipient}");
+            info!("using {new_tag} for all anonymous messages sent to {recipient}");
            new_tag
        }
    }
@@ -216,7 +216,7 @@ where
    fn get_topology<'a>(
        &self,
        permit: &'a TopologyReadPermit<'a>,
-    ) -> Result<&'a NymTopology, PreparationError> {
+    ) -> Result<&'a NymRouteProvider, PreparationError> {
        match permit.try_get_valid_topology_ref(&self.config.sender_address, None) {
            Ok(topology_ref) => Ok(topology_ref),
            Err(err) => {
@@ -233,9 +233,8 @@ where
            return self.config.primary_packet_size;
        };

-        let primary_count =
-            msg.required_packets(self.config.primary_packet_size, self.config.num_mix_hops);
-        let secondary_count = msg.required_packets(secondary_packet, self.config.num_mix_hops);
+        let primary_count = msg.required_packets(self.config.primary_packet_size);
+        let secondary_count = msg.required_packets(secondary_packet);

        trace!("This message would require: {primary_count} primary packets or {secondary_count} secondary packets...");
        // if there would be no benefit in using the secondary packet - use the primary (duh)
@@ -302,8 +301,14 @@ where
            Some(chunk.fragment_identifier()),
        );
        let delay = prepared_fragment.total_delay;
-        let pending_ack =
-            PendingAcknowledgement::new_anonymous(chunk, delay, target, is_extra_surb_request);
+        let max_retransmissions = None;
+        let pending_ack = PendingAcknowledgement::new_anonymous(
+            chunk,
+            delay,
+            target,
+            is_extra_surb_request,
+            max_retransmissions,
+        );

        let lane = if is_extra_surb_request {
            TransmissionLane::ReplySurbRequest
@@ -358,7 +363,7 @@ where
    pub(crate) async fn try_send_reply_chunks_on_lane(
        &mut self,
        target: AnonymousSenderTag,
-        fragments: Vec<Fragment>,
+        fragments: Vec<FragmentWithMaxRetransmissions>,
        reply_surbs: Vec<ReplySurb>,
        lane: TransmissionLane,
    ) -> Result<(), SurbWrappedPreparationError> {
@@ -375,12 +380,12 @@ where
    pub(crate) async fn try_send_reply_chunks(
        &mut self,
        target: AnonymousSenderTag,
-        fragments: Vec<(TransmissionLane, Fragment)>,
+        fragments: Vec<(TransmissionLane, FragmentWithMaxRetransmissions)>,
        reply_surbs: Vec<ReplySurb>,
    ) -> Result<(), SurbWrappedPreparationError> {
        let prepared_fragments = self
            .prepare_reply_chunks_for_sending(
-                fragments.iter().map(|(_, f)| f.clone()).collect(),
+                fragments.iter().map(|(_, f)| f.fragment.clone()).collect(),
                reply_surbs,
            )
            .await?;
@@ -390,12 +395,21 @@ where

        for (raw, prepared) in fragments.into_iter().zip(prepared_fragments.into_iter()) {
            let lane = raw.0;
-            let fragment = raw.1;
+            let FragmentWithMaxRetransmissions {
+                fragment,
+                max_retransmissions,
+            } = raw.1;

            let real_message =
                RealMessage::new(prepared.mix_packet, Some(prepared.fragment_identifier));
            let delay = prepared.total_delay;
-            let pending_ack = PendingAcknowledgement::new_anonymous(fragment, delay, target, false);
+            let pending_ack = PendingAcknowledgement::new_anonymous(
+                fragment,
+                delay,
+                target,
+                false,
+                max_retransmissions,
+            );

            let entry = to_forward.entry(lane).or_default();
            entry.push(real_message);
@@ -424,11 +438,17 @@ where
        message: Vec<u8>,
        lane: TransmissionLane,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) -> Result<(), PreparationError> {
        let message = NymMessage::new_plain(message);
-        self.try_split_and_send_non_reply_message(message, recipient, lane, packet_type, mix_hops)
-            .await
+        self.try_split_and_send_non_reply_message(
+            message,
+            recipient,
+            lane,
+            packet_type,
+            max_retransmissions,
+        )
+        .await
    }

    pub(crate) async fn try_split_and_send_non_reply_message(
@@ -437,7 +457,7 @@ where
        recipient: Recipient,
        lane: TransmissionLane,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) -> Result<(), PreparationError> {
        debug!("Sending non-reply message with packet type {packet_type}");
        // TODO: I really dislike existence of this assertion, it implies code has to be re-organised
@@ -470,7 +490,6 @@ where
                &self.config.ack_key,
                &recipient,
                packet_type,
-                mix_hops,
            )?;

            let real_message = RealMessage::new(
@@ -479,7 +498,7 @@ where
            );
            let delay = prepared_fragment.total_delay;
            let pending_ack =
-                PendingAcknowledgement::new_known(fragment, delay, recipient, mix_hops);
+                PendingAcknowledgement::new_known(fragment, delay, recipient, max_retransmissions);

            real_messages.push(real_message);
            pending_acks.push(pending_ack);
@@ -496,7 +515,6 @@ where
        recipient: Recipient,
        amount: u32,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
    ) -> Result<(), PreparationError> {
        debug!("Sending additional reply SURBs with packet type {packet_type}");
        let sender_tag = self.get_or_create_sender_tag(&recipient);
@@ -508,12 +526,15 @@ where
            reply_surbs,
        ));

+        // When sending SURBs we want to retransmit
+        let max_retransmissions = None;
+
        self.try_split_and_send_non_reply_message(
            message,
            recipient,
            TransmissionLane::AdditionalReplySurbs,
            packet_type,
-            mix_hops,
+            max_retransmissions,
        )
        .await?;

@@ -530,7 +551,7 @@ where
        num_reply_surbs: u32,
        lane: TransmissionLane,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
+        max_retransmissions: Option<u32>,
    ) -> Result<(), SurbWrappedPreparationError> {
        debug!("Sending message with reply SURBs with packet type {packet_type}");
        let sender_tag = self.get_or_create_sender_tag(&recipient);
@@ -541,8 +562,14 @@ where
        let message =
            NymMessage::new_repliable(RepliableMessage::new_data(message, sender_tag, reply_surbs));

-        self.try_split_and_send_non_reply_message(message, recipient, lane, packet_type, mix_hops)
-            .await?;
+        self.try_split_and_send_non_reply_message(
+            message,
+            recipient,
+            lane,
+            packet_type,
+            max_retransmissions,
+        )
+        .await?;

        log::trace!("storing {} reply keys", reply_keys.len());
        self.reply_key_storage.insert_multiple(reply_keys);
@@ -555,23 +582,18 @@ where
        recipient: Recipient,
        chunk: Fragment,
        packet_type: PacketType,
-        mix_hops: Option<u8>,
    ) -> Result<PreparedFragment, PreparationError> {
        debug!("Sending single chunk with packet type {packet_type}");
        let topology_permit = self.topology_access.get_read_permit().await;
        let topology = self.get_topology(&topology_permit)?;

-        let prepared_fragment = self
-            .message_preparer
-            .prepare_chunk_for_sending(
-                chunk,
-                topology,
-                &self.config.ack_key,
-                &recipient,
-                packet_type,
-                mix_hops,
-            )
-            .unwrap();
+        let prepared_fragment = self.message_preparer.prepare_chunk_for_sending(
+            chunk,
+            topology,
+            &self.config.ack_key,
+            &recipient,
+            packet_type,
+        )?;

        Ok(prepared_fragment)
    }
@@ -624,30 +646,37 @@ where
            Err(err) => return Err(err.return_surbs(vec![reply_surb])),
        };

-        let prepared_fragment = self
-            .message_preparer
-            .prepare_reply_chunk_for_sending(
-                chunk,
-                topology,
-                &self.config.ack_key,
-                reply_surb,
-                PacketType::Mix,
-            )
-            .unwrap();
+        let prepared_fragment = self.message_preparer.prepare_reply_chunk_for_sending(
+            chunk,
+            topology,
+            &self.config.ack_key,
+            reply_surb,
+            PacketType::Mix,
+        )?;

        Ok(prepared_fragment)
    }

    pub(crate) fn update_ack_delay(&self, id: FragmentIdentifier, new_delay: Delay) {
-        self.action_sender
+        if let Err(err) = self
+            .action_sender
            .unbounded_send(Action::UpdatePendingAck(id, new_delay))
-            .expect("action control task has died")
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send update action to the controller: {err}");
+            }
+        }
    }

    pub(crate) fn insert_pending_acks(&self, pending_acks: Vec<PendingAcknowledgement>) {
-        self.action_sender
+        if let Err(err) = self
+            .action_sender
            .unbounded_send(Action::new_insert(pending_acks))
-            .expect("action control task has died")
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to send insert action to the controller: {err}");
+            }
+        }
    }

    // tells real message sender (with the poisson timer) to send this to the mix network
@@ -656,9 +685,14 @@ where
        messages: Vec<RealMessage>,
        transmission_lane: TransmissionLane,
    ) {
-        self.real_message_sender
+        if let Err(err) = self
+            .real_message_sender
            .send((messages, transmission_lane))
            .await
-            .expect("real message receiver task (OutQueueControl) has died");
+        {
+            if !self.task_client.is_shutdown_poll() {
+                error!("Failed to forward messages to the real message sender: {err}");
+            }
+        }
    }
 }
@@ -9,10 +9,12 @@ use self::{
    acknowledgement_control::AcknowledgementController, real_traffic_stream::OutQueueControl,
 };
 use crate::client::real_messages_control::message_handler::MessageHandler;
+use crate::client::replies::reply_controller;
 use crate::client::replies::reply_controller::{
    ReplyController, ReplyControllerReceiver, ReplyControllerSender,
 };
 use crate::client::replies::reply_storage::CombinedReplyStorage;
+use crate::config;
 use crate::{
    client::{
        inbound_messages::InputMessageReceiver, mix_traffic::BatchMixMessageSender,
@@ -27,16 +29,14 @@ use nym_gateway_client::AcknowledgementReceiver;
 use nym_sphinx::acknowledgements::AckKey;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::params::PacketType;
+use nym_statistics_common::clients::ClientStatsSender;
 use nym_task::connections::{ConnectionCommandReceiver, LaneQueueLengths};
+use nym_task::TaskClient;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::sync::Arc;

-use crate::client::replies::reply_controller;
-use crate::config;
 pub(crate) use acknowledgement_control::{AckActionSender, Action};

-use nym_statistics_common::clients::ClientStatsSender;
-
 pub(crate) mod acknowledgement_control;
 pub(crate) mod message_handler;
 pub(crate) mod real_traffic_stream;
@@ -148,11 +148,12 @@ impl RealMessagesController<OsRng> {
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        let rng = OsRng;

        // create channels for inter-task communication
-        let (real_message_sender, real_message_receiver) = tokio::sync::mpsc::channel(1);
+        let (real_message_sender, real_message_receiver) = tokio::sync::mpsc::channel(8);
        let (sent_notifier_tx, sent_notifier_rx) = mpsc::unbounded();
        let (ack_action_tx, ack_action_rx) = mpsc::unbounded();
        let ack_controller_connectors = AcknowledgementControllerConnectors::new(
@@ -178,6 +179,7 @@ impl RealMessagesController<OsRng> {
            topology_access.clone(),
            reply_storage.key_storage(),
            reply_storage.tags_storage(),
+            task_client.fork("message_handler"),
        );

        let ack_control = AcknowledgementController::new(
@@ -187,6 +189,7 @@ impl RealMessagesController<OsRng> {
            message_handler.clone(),
            reply_controller_sender,
            stats_tx.clone(),
+            task_client.fork("ack_control"),
        );

        let reply_control = ReplyController::new(
@@ -194,6 +197,7 @@ impl RealMessagesController<OsRng> {
            message_handler,
            reply_storage,
            reply_controller_receiver,
+            task_client.fork("reply_controller"),
        );

        let out_queue_control = OutQueueControl::new(
@@ -206,6 +210,7 @@ impl RealMessagesController<OsRng> {
            lane_queue_lengths,
            client_connection_rx,
            stats_tx,
+            task_client.with_suffix("out_queue_control"),
        );

        RealMessagesController {
@@ -215,22 +220,20 @@ impl RealMessagesController<OsRng> {
        }
    }

-    pub fn start_with_shutdown(self, shutdown: nym_task::TaskClient, packet_type: PacketType) {
+    pub fn start(self, packet_type: PacketType) {
        let mut out_queue_control = self.out_queue_control;
        let ack_control = self.ack_control;
        let mut reply_control = self.reply_control;

-        let shutdown_handle = shutdown.fork("out_queue_control");
        spawn_future(async move {
-            out_queue_control.run_with_shutdown(shutdown_handle).await;
+            out_queue_control.run().await;
            debug!("The out queue controller has finished execution!");
        });
-        let shutdown_handle = shutdown.fork("reply_control");
        spawn_future(async move {
-            reply_control.run_with_shutdown(shutdown_handle).await;
+            reply_control.run().await;
            debug!("The reply controller has finished execution!");
        });

-        ack_control.start_with_shutdown(shutdown.with_suffix("ack_control"), packet_type);
+        ack_control.start(packet_type);
    }
 }
@@ -22,6 +22,7 @@ use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, C
 use nym_task::connections::{
    ConnectionCommand, ConnectionCommandReceiver, ConnectionId, LaneQueueLengths, TransmissionLane,
 };
+use nym_task::TaskClient;
 use rand::{CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;
@@ -117,6 +118,8 @@ where

    /// Channel used for sending metrics events (specifically `PacketStatistics` events) to the metrics tracker.
    stats_tx: ClientStatsSender,
+
+    task_client: TaskClient,
 }

 #[derive(Debug)]
@@ -176,6 +179,7 @@ where
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        OutQueueControl {
            config,
@@ -190,6 +194,7 @@ where
            client_connection_rx,
            lane_queue_lengths,
            stats_tx,
+            task_client,
        }
    }

@@ -198,7 +203,9 @@ where
        // queues and client load rather than the required delay. So realistically we can treat
        // whatever is about to happen as negligible additional delay.
        trace!("{} is about to get sent to the mixnet", frag_id);
-        self.sent_notifier.unbounded_send(frag_id).unwrap();
+        if let Err(err) = self.sent_notifier.unbounded_send(frag_id) {
+            error!("Failed to notify about sent message: {err}");
+        }
    }

    fn loop_cover_message_size(&mut self) -> PacketSize {
@@ -230,6 +237,7 @@ where
                // poisson delay, but is it really a problem?
                let topology_permit = self.topology_access.get_read_permit().await;
                // the ack is sent back to ourselves (and then ignored)
+
                let topology_ref = match topology_permit.try_get_valid_topology_ref(
                    &self.config.our_full_destination,
                    Some(&self.config.our_full_destination),
@@ -270,7 +278,9 @@ where
        };

        if let Err(err) = self.mix_tx.send(vec![next_message]).await {
-            log::error!("Failed to send: {err}");
+            if !self.task_client.is_shutdown_poll() {
+                log::error!("Failed to send: {err}");
+            }
        } else {
            let event = if fragment_id.is_some() {
                PacketStatisticsEvent::RealPacketSent(packet_size)
@@ -503,21 +513,29 @@ where
    }

    #[cfg(not(target_arch = "wasm32"))]
-    fn log_status(&self, shutdown: &mut nym_task::TaskClient) {
+    fn log_status(&self, shutdown: &mut TaskClient) {
        use crate::error::ClientCoreStatusMessage;

        let packets = self.transmission_buffer.total_size();
-        let backlog = self.transmission_buffer.total_size_in_bytes() as f64 / 1024.0;
-        let lanes = self.transmission_buffer.num_lanes();
+        let lanes = self.transmission_buffer.lanes();
        let mult = self.sending_delay_controller.current_multiplier();
        let delay = self.current_average_message_sending_delay().as_millis();
+
+        let lane_status = lanes
+            .iter()
+            .map(|lane_name| {
+                let lane_length = self.transmission_buffer.lane_length(lane_name).unwrap_or(0);
+                format!("{lane_name:?}: {lane_length}")
+            })
+            .collect::<Vec<String>>()
+            .join(", ");
+
        let status_str = if self.config.traffic.disable_main_poisson_packet_distribution {
-            format!("Packet backlog: {backlog:.2} kiB ({packets}), {lanes} lanes, no delay")
+            format!("Packet backlog: {lane_status}, no delay")
        } else {
-            format!(
-                "Packet backlog: {backlog:.2} kiB ({packets}), {lanes} lanes, avg delay: {delay}ms ({mult})"
-            )
+            format!("Packet backlog: {lane_status}, avg delay: {delay}ms ({mult})")
        };
+
        if packets > 1000 {
            log::warn!("{status_str}");
        } else if packets > 0 {
@@ -534,17 +552,19 @@ where
        }
    }

-    pub(super) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(super) async fn run(&mut self) {
        debug!("Started OutQueueControl with graceful shutdown support");

+        let mut shutdown = self.task_client.fork("select");
+
        #[cfg(not(target_arch = "wasm32"))]
        {
            let mut status_timer = tokio::time::interval(Duration::from_secs(5));

-            loop {
+            while !shutdown.is_shutdown() {
                tokio::select! {
                    biased;
-                    _ = shutdown.recv_with_delay() => {
+                    _ = shutdown.recv() => {
                        log::trace!("OutQueueControl: Received shutdown");
                        break;
                    }
@@ -70,7 +70,10 @@ impl SendingDelayController {
            lower_bound,
            multiplier_elevated_counter: 0,
            time_when_logged_about_elevated_multiplier: now
-                - Duration::from_secs(INTERVAL_BETWEEN_WARNING_ABOUT_ELEVATED_MULTIPLIER_SECS),
+                .checked_sub(Duration::from_secs(
+                    INTERVAL_BETWEEN_WARNING_ABOUT_ELEVATED_MULTIPLIER_SECS,
+                ))
+                .unwrap_or(now),
            time_when_changed: now,
            time_when_backpressure_detected: now,
        }
@@ -20,8 +20,13 @@ use nym_sphinx::message::{NymMessage, PlainMessage};
 use nym_sphinx::params::ReplySurbKeyDigestAlgorithm;
 use nym_sphinx::receiver::{MessageReceiver, MessageRecoveryError, ReconstructedMessage};
 use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, ClientStatsSender};
+use nym_task::TaskClient;
 use std::collections::HashSet;
 use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+// The interval at which we check for stale buffers
+const STALE_BUFFER_CHECK_INTERVAL: Duration = Duration::from_secs(10);

 // Buffer Requests to say "hey, send any reconstructed messages to this channel"
 // or to say "hey, I'm going offline, don't send anything more to me. Just buffer them instead"
@@ -47,6 +52,9 @@ struct ReceivedMessagesBufferInner<R: MessageReceiver> {
    recently_reconstructed: HashSet<i32>,

    stats_tx: ClientStatsSender,
+
+    // Periodically check for stale buffers to clean up
+    last_stale_check: Instant,
 }

 impl<R: MessageReceiver> ReceivedMessagesBufferInner<R> {
@@ -95,9 +103,10 @@ impl<R: MessageReceiver> ReceivedMessagesBufferInner<R> {
                    }
                    None
                }
-                _ => unreachable!(
-                    "no other error kind should have been returned here! If so, it's a bug!"
-                ),
+                _ => {
+                    error!("unexpected error occurred during message reconstruction: {err}");
+                    None
+                }
            },
            Ok(reconstruction_result) => match reconstruction_result {
                Some((reconstructed_message, used_sets)) => {
@@ -143,6 +152,16 @@ impl<R: MessageReceiver> ReceivedMessagesBufferInner<R> {

        self.recover_from_fragment(fragment_data, raw_fragment_size)
    }
+
+    fn cleanup_stale_buffers(&mut self) {
+        let now = Instant::now();
+        if now - self.last_stale_check > STALE_BUFFER_CHECK_INTERVAL {
+            self.last_stale_check = now;
+            self.message_receiver
+                .reconstructor()
+                .cleanup_stale_buffers();
+        }
+    }
 }

 #[derive(Debug, Clone)]
@@ -152,6 +171,7 @@ struct ReceivedMessagesBuffer<R: MessageReceiver> {
    inner: Arc<Mutex<ReceivedMessagesBufferInner<R>>>,
    reply_key_storage: SentReplyKeys,
    reply_controller_sender: ReplyControllerSender,
+    task_client: TaskClient,
 }

 impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
@@ -160,6 +180,7 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
        reply_key_storage: SentReplyKeys,
        reply_controller_sender: ReplyControllerSender,
        stats_tx: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        ReceivedMessagesBuffer {
            inner: Arc::new(Mutex::new(ReceivedMessagesBufferInner {
@@ -169,9 +190,11 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                message_sender: None,
                recently_reconstructed: HashSet::new(),
                stats_tx,
+                last_stale_check: Instant::now(),
            })),
            reply_key_storage,
            reply_controller_sender,
+            task_client,
        }
    }

@@ -257,11 +280,15 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                }
            };

-            self.reply_controller_sender.send_additional_surbs(
+            if let Err(err) = self.reply_controller_sender.send_additional_surbs(
                msg.sender_tag,
                reply_surbs,
                from_surb_request,
-            )
+            ) {
+                if !self.task_client.is_shutdown_poll() {
+                    error!("{err}");
+                }
+            }
        }
        reconstructed
    }
@@ -276,8 +303,14 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                ReplyMessageContent::Data { message } => reconstructed.push(message.into()),
                ReplyMessageContent::SurbRequest { recipient, amount } => {
                    debug!("received request for {amount} additional reply SURBs from {recipient}");
-                    self.reply_controller_sender
-                        .send_additional_surbs_request(*recipient, amount);
+                    if let Err(err) = self
+                        .reply_controller_sender
+                        .send_additional_surbs_request(*recipient, amount)
+                    {
+                        if !self.task_client.is_shutdown_poll() {
+                            error!("{err}");
+                        }
+                    }
                }
            }
        }
@@ -378,6 +411,11 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
            }
        }

+        // Cleanup stale buffers, if there are any fragments that simply never arrived.
+        // We do this here as part of handling new received fragments so that we can keep the event
+        // loop focused on processing new messages.
+        inner_guard.cleanup_stale_buffers();
+
        drop(inner_guard);

        if !completed_messages.is_empty() {
@@ -399,16 +437,19 @@ pub enum ReceivedBufferMessage {
 struct RequestReceiver<R: MessageReceiver> {
    received_buffer: ReceivedMessagesBuffer<R>,
    query_receiver: ReceivedBufferRequestReceiver,
+    task_client: TaskClient,
 }

 impl<R: MessageReceiver> RequestReceiver<R> {
    fn new(
        received_buffer: ReceivedMessagesBuffer<R>,
        query_receiver: ReceivedBufferRequestReceiver,
+        task_client: TaskClient,
    ) -> Self {
        RequestReceiver {
            received_buffer,
            query_receiver,
+            task_client,
        }
    }

@@ -423,12 +464,12 @@ impl<R: MessageReceiver> RequestReceiver<R> {
        }
    }

-    async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    async fn run(&mut self) {
        debug!("Started RequestReceiver with graceful shutdown support");
-        while !shutdown.is_shutdown() {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                biased;
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv() => {
                    log::trace!("RequestReceiver: Received shutdown");
                }
                request = self.query_receiver.next() => {
@@ -441,7 +482,7 @@ impl<R: MessageReceiver> RequestReceiver<R> {
                },
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv().await;
        log::debug!("RequestReceiver: Exiting");
    }
 }
@@ -449,25 +490,25 @@ impl<R: MessageReceiver> RequestReceiver<R> {
 struct FragmentedMessageReceiver<R: MessageReceiver> {
    received_buffer: ReceivedMessagesBuffer<R>,
    mixnet_packet_receiver: MixnetMessageReceiver,
+    task_client: TaskClient,
 }

 impl<R: MessageReceiver> FragmentedMessageReceiver<R> {
    fn new(
        received_buffer: ReceivedMessagesBuffer<R>,
        mixnet_packet_receiver: MixnetMessageReceiver,
+        task_client: TaskClient,
    ) -> Self {
        FragmentedMessageReceiver {
            received_buffer,
            mixnet_packet_receiver,
+            task_client,
        }
    }

-    async fn run_with_shutdown(
-        &mut self,
-        mut shutdown: nym_task::TaskClient,
-    ) -> Result<(), MessageRecoveryError> {
+    async fn run(&mut self) -> Result<(), MessageRecoveryError> {
        debug!("Started FragmentedMessageReceiver with graceful shutdown support");
-        while !shutdown.is_shutdown() {
+        while !self.task_client.is_shutdown() {
            tokio::select! {
                new_messages = self.mixnet_packet_receiver.next() => {
                    if let Some(new_messages) = new_messages {
@@ -477,12 +518,12 @@ impl<R: MessageReceiver> FragmentedMessageReceiver<R> {
                        break;
                    }
                },
-                _ = shutdown.recv_with_delay() => {
+                _ = self.task_client.recv_with_delay() => {
                    log::trace!("FragmentedMessageReceiver: Received shutdown");
                }
            }
        }
-        shutdown.recv_timeout().await;
+        self.task_client.recv_timeout().await;
        log::debug!("FragmentedMessageReceiver: Exiting");
        Ok(())
    }
@@ -501,41 +542,42 @@ impl<R: MessageReceiver + Clone + Send + 'static> ReceivedMessagesBufferControll
        reply_key_storage: SentReplyKeys,
        reply_controller_sender: ReplyControllerSender,
        metrics_reporter: ClientStatsSender,
+        task_client: TaskClient,
    ) -> Self {
        let received_buffer = ReceivedMessagesBuffer::new(
            local_encryption_keypair,
            reply_key_storage,
            reply_controller_sender,
            metrics_reporter,
+            task_client.fork("received_messages_buffer"),
        );

        ReceivedMessagesBufferController {
            fragmented_message_receiver: FragmentedMessageReceiver::new(
                received_buffer.clone(),
                mixnet_packet_receiver,
+                task_client.fork("fragmented_message_receiver"),
+            ),
+            request_receiver: RequestReceiver::new(
+                received_buffer,
+                query_receiver,
+                task_client.with_suffix("request_receiver"),
            ),
-            request_receiver: RequestReceiver::new(received_buffer, query_receiver),
        }
    }

-    pub fn start_with_shutdown(self, shutdown: nym_task::TaskClient) {
+    pub fn start(self) {
        let mut fragmented_message_receiver = self.fragmented_message_receiver;
        let mut request_receiver = self.request_receiver;

-        let shutdown_handle = shutdown.fork("fragmented_message_receiver");
        spawn_future(async move {
-            match fragmented_message_receiver
-                .run_with_shutdown(shutdown_handle)
-                .await
-            {
+            match fragmented_message_receiver.run().await {
                Ok(_) => {}
                Err(e) => error!("{e}"),
            }
        });
        spawn_future(async move {
-            request_receiver
-                .run_with_shutdown(shutdown.with_suffix("request_receiver"))
-                .await;
+            request_receiver.run().await;
        });
    }
 }
@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::client::real_messages_control::acknowledgement_control::PendingAcknowledgement;
-use crate::client::real_messages_control::message_handler::{MessageHandler, PreparationError};
+use crate::client::real_messages_control::message_handler::{
+    FragmentWithMaxRetransmissions, MessageHandler, PreparationError,
+};
 use crate::client::replies::reply_storage::CombinedReplyStorage;
 use futures::channel::oneshot;
 use futures::StreamExt;
@@ -10,8 +12,9 @@ use log::{debug, error, info, trace, warn};
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
 use nym_sphinx::anonymous_replies::ReplySurb;
-use nym_sphinx::chunking::fragment::{Fragment, FragmentIdentifier};
+use nym_sphinx::chunking::fragment::FragmentIdentifier;
 use nym_task::connections::{ConnectionId, TransmissionLane};
+use nym_task::TaskClient;
 use rand::{CryptoRng, Rng};
 use std::cmp::{max, min};
 use std::collections::btree_map::Entry;
@@ -48,6 +51,8 @@ impl Config {
 // - replies to "give additional surbs" requests
 // - will reply to future heartbeats

+pub type MaxRetransmissions = Option<u32>;
+
 // TODO: this should be split into ingress and egress controllers
 // because currently its trying to perform two distinct jobs
 pub struct ReplyController<R> {
@@ -58,7 +63,8 @@ pub struct ReplyController<R> {
    // of surbs required to send the message through
    // expected_reliability: f32,
    request_receiver: ReplyControllerReceiver,
-    pending_replies: HashMap<AnonymousSenderTag, TransmissionBuffer<Fragment>>,
+    pending_replies:
+        HashMap<AnonymousSenderTag, TransmissionBuffer<FragmentWithMaxRetransmissions>>,

    /// Retransmission packets that have already timed out and are waiting for additional reply SURBs
    /// so that they could be sent back to the network. Once we receive more SURBs, we should send them ASAP.
@@ -68,6 +74,9 @@ pub struct ReplyController<R> {

    message_handler: MessageHandler<R>,
    full_reply_storage: CombinedReplyStorage,
+
+    // Listen for shutdown signals
+    task_client: TaskClient,
 }

 impl<R> ReplyController<R>
@@ -79,6 +88,7 @@ where
        message_handler: MessageHandler<R>,
        full_reply_storage: CombinedReplyStorage,
        request_receiver: ReplyControllerReceiver,
+        task_client: TaskClient,
    ) -> Self {
        ReplyController {
            config,
@@ -87,15 +97,17 @@ where
            pending_retransmissions: HashMap::new(),
            message_handler,
            full_reply_storage,
+            task_client,
        }
    }

-    fn insert_pending_replies<I: IntoIterator<Item = Fragment>>(
+    fn insert_pending_replies<I: IntoIterator<Item = FragmentWithMaxRetransmissions>>(
        &mut self,
        recipient: &AnonymousSenderTag,
        fragments: I,
        lane: TransmissionLane,
    ) {
+        trace!("buffering pending replies for {recipient}");
        self.pending_replies
            .entry(*recipient)
            .or_insert_with(TransmissionBuffer::new)
@@ -105,8 +117,9 @@ where
    fn re_insert_pending_replies(
        &mut self,
        recipient: &AnonymousSenderTag,
-        fragments: Vec<(TransmissionLane, Fragment)>,
+        fragments: Vec<(TransmissionLane, FragmentWithMaxRetransmissions)>,
    ) {
+        trace!("re-inserting pending replies for {recipient}");
        // the buffer should ALWAYS exist at this point, if it doesn't, it's a bug...
        self.pending_replies
            .entry(*recipient)
@@ -119,6 +132,7 @@ where
        recipient: &AnonymousSenderTag,
        data: Vec<Arc<PendingAcknowledgement>>,
    ) {
+        trace!("re-inserting pending retransmissions for {recipient}");
        // the underlying entry MUST exist as we've just got data from there
        let map_entry = self
            .pending_retransmissions
@@ -136,7 +150,7 @@ where
    }

    fn should_request_more_surbs(&self, target: &AnonymousSenderTag) -> bool {
-        trace!("checking if we should request more surbs from {:?}", target);
+        trace!("checking if we should request more surbs from {target}");

        let pending_queue_size = self
            .pending_replies
@@ -152,11 +166,6 @@ where

        let total_queue = pending_queue_size + retransmission_queue;

-        // simple as that - there's absolutely nothing to retransmit
-        if total_queue == 0 {
-            return false;
-        }
-
        let available_surbs = self
            .full_reply_storage
            .surbs_storage_ref()
@@ -173,11 +182,27 @@ where
            .full_reply_storage
            .surbs_storage_ref()
            .max_surb_threshold();
+        let min_surbs_threshold_buffer =
+            self.config.reply_surbs.minimum_reply_surb_threshold_buffer;

-        debug!("total queue size: {total_queue} = pending data {pending_queue_size} + pending retransmission {retransmission_queue}, available surbs: {available_surbs} pending surbs: {pending_surbs} threshold range: {min_surbs_threshold}..{max_surbs_threshold}");
+        // After clearing the queue, we want to have at least `min_surbs_threshold` surbs available
+        // and reserved for requesting additional surbs, and in addition to that we also want to
+        // have `min_surbs_threshold_buffer` surbs available proactively.
+        let target_surbs_after_clearing_queue = min_surbs_threshold + min_surbs_threshold_buffer;

-        (pending_surbs + available_surbs) < max_surbs_threshold
-            && (pending_surbs + available_surbs) < (total_queue + min_surbs_threshold)
+        // Check if we have enough surbs to handle the total queue and maintain minimum thresholds
+        let total_required_surbs = total_queue + target_surbs_after_clearing_queue;
+        let total_available_surbs = pending_surbs + available_surbs;
+
+        debug!("total queue size: {total_queue} = pending data {pending_queue_size} + pending retransmission {retransmission_queue}, available surbs: {available_surbs} pending surbs: {pending_surbs} threshold range: {min_surbs_threshold}..+{min_surbs_threshold_buffer}..{max_surbs_threshold}");
+
+        // We should request more surbs if:
+        // 1. We haven't hit the maximum surb threshold, and
+        // 2. We don't have enough surbs to handle the queue plus minimum thresholds
+        let is_below_max_threshold = total_available_surbs < max_surbs_threshold;
+        let is_below_required_surbs = total_available_surbs < total_required_surbs;
+
+        is_below_max_threshold && is_below_required_surbs
    }

    async fn handle_send_reply(
@@ -185,6 +210,7 @@ where
        recipient_tag: AnonymousSenderTag,
        data: Vec<u8>,
        lane: TransmissionLane,
+        max_retransmissions: Option<u32>,
    ) {
        if !self
            .full_reply_storage
@@ -222,7 +248,14 @@ where
                .get_reply_surbs(&recipient_tag, max_to_send);

            if let Some(reply_surbs) = surbs {
-                let to_send = fragments.drain(..max_to_send).collect::<Vec<_>>();
+                let to_send = fragments
+                    .drain(..max_to_send)
+                    .map(|f| FragmentWithMaxRetransmissions {
+                        fragment: f,
+                        max_retransmissions,
+                    })
+                    .collect::<Vec<_>>();
+
                if let Err(err) = self
                    .message_handler
                    .try_send_reply_chunks_on_lane(
@@ -238,6 +271,10 @@ where
                        &recipient_tag,
                    );
                    warn!("failed to send reply to {recipient_tag}: {err}");
+                    info!(
+                        "buffering {no_fragments} fragments for {recipient_tag}",
+                        no_fragments = to_send.len()
+                    );
                    self.insert_pending_replies(&recipient_tag, to_send, lane);
                }
            }
@@ -245,6 +282,20 @@ where

        // if there's leftover data we didn't send because we didn't have enough (or any) surbs - buffer it
        if !fragments.is_empty() {
+            // Ideally we should have enough surbs above the minimum threshold to handle sending
+            // new replies without having to first request more surbs. That's why I'd like to log
+            // these cases as they might indicate a problem with the surb management.
+            debug!(
+                "buffering {no_fragments} fragments for {recipient_tag}",
+                no_fragments = fragments.len()
+            );
+            let fragments: Vec<_> = fragments
+                .into_iter()
+                .map(|fragment| FragmentWithMaxRetransmissions {
+                    fragment,
+                    max_retransmissions,
+                })
+                .collect();
            self.insert_pending_replies(&recipient_tag, fragments, lane);
        }

@@ -259,6 +310,7 @@ where
        target: AnonymousSenderTag,
        amount: u32,
    ) -> Result<(), PreparationError> {
+        debug!("requesting {amount} additional reply surbs for {target}");
        let reply_surb = self
            .full_reply_storage
            .surbs_storage_ref()
@@ -377,7 +429,7 @@ where
        &mut self,
        from: &AnonymousSenderTag,
        amount: usize,
-    ) -> Option<Vec<(TransmissionLane, Fragment)>> {
+    ) -> Option<Vec<(TransmissionLane, FragmentWithMaxRetransmissions)>> {
        // if possible, pop all pending replies, if not, pop only entries for which we'd have a reply surb
        let total = self.pending_replies.get(from)?.total_size();
        trace!("pending queue has {total} elements");
@@ -516,7 +568,6 @@ where
                    recipient,
                    to_send,
                    nym_sphinx::params::PacketType::Mix,
-                    self.config.reply_surbs.surb_mix_hops,
                )
                .await
            {
@@ -658,7 +709,11 @@ where
                recipient,
                message,
                lane,
-            } => self.handle_send_reply(recipient, message, lane).await,
+                max_retransmissions,
+            } => {
+                self.handle_send_reply(recipient, message, lane, max_retransmissions)
+                    .await
+            }
            ReplyControllerMessage::AdditionalSurbs {
                sender_tag,
                reply_surbs,
@@ -681,7 +736,7 @@ where
    // it should take into consideration the average latency, sending rate and queue size.
    // it should request as many surbs as it takes to saturate its sending rate before next batch arrives
    async fn request_reply_surbs_for_queue_clearing(&mut self, target: AnonymousSenderTag) {
-        trace!("requesting surbs for queues clearing");
+        trace!("requesting surbs for queue clearing");

        let pending_queue_size = self
            .pending_replies
@@ -695,17 +750,18 @@ where
            .map(|pending_queue| pending_queue.len())
            .unwrap_or_default();

+        let min_surbs_buffer = self.config.reply_surbs.minimum_reply_surb_threshold_buffer as u32;
+
        let total_queue = (pending_queue_size + retransmission_queue) as u32;

-        if total_queue == 0 {
-            trace!("the pending queues for {:?} are already empty", target);
-            return;
-        }
+        // To proactively request additional surbs, we aim to have a buffer of extra surbs in our
+        // storage.
+        let total_queue_with_buffer = total_queue + min_surbs_buffer;

        let request_size = min(
            self.config.reply_surbs.maximum_reply_surb_request_size,
            max(
-                total_queue,
+                total_queue_with_buffer,
                self.config.reply_surbs.minimum_reply_surb_request_size,
            ),
        );
@@ -714,7 +770,7 @@ where
            .request_additional_reply_surbs(target, request_size)
            .await
        {
-            warn!("failed to request additional surbs... - {err}")
+            info!("{err}")
        }
    }

@@ -847,9 +903,11 @@ where
    //     todo!()
    // }

-    pub(crate) async fn run_with_shutdown(&mut self, mut shutdown: nym_task::TaskClient) {
+    pub(crate) async fn run(&mut self) {
        debug!("Started ReplyController with graceful shutdown support");

+        let mut shutdown = self.task_client.fork("select");
+
        let polling_rate = Duration::from_secs(5);
        let mut stale_inspection = new_interval_stream(polling_rate);

@@ -861,7 +919,7 @@ where
        while !shutdown.is_shutdown() {
            tokio::select! {
                biased;
-                _ = shutdown.recv_with_delay() => {
+                _ = shutdown.recv() => {
                    log::trace!("ReplyController: Received shutdown");
                },
                req = self.request_receiver.next() => match req {
@@ -15,6 +15,27 @@ pub(crate) fn new_control_channels() -> (ReplyControllerSender, ReplyControllerR
    (tx.into(), rx)
 }

+#[derive(Debug, thiserror::Error)]
+pub enum ReplyControllerSenderError {
+    #[error("failed to send retransmission data to reply controller")]
+    SendRetransmissionData(#[source] mpsc::TrySendError<ReplyControllerMessage>),
+
+    #[error("failed to send reply to reply controller")]
+    SendReply(#[source] mpsc::TrySendError<ReplyControllerMessage>),
+
+    #[error("failed to send additional surbs to reply controller")]
+    AdditionalSurbs(#[source] mpsc::TrySendError<ReplyControllerMessage>),
+
+    #[error("failed to send additional surbs request to reply controller")]
+    AdditionalSurbsRequest(#[source] mpsc::TrySendError<ReplyControllerMessage>),
+
+    #[error("failed to request lane queue length from reply controller")]
+    LaneQueueLength(#[source] mpsc::TrySendError<ReplyControllerMessage>),
+
+    #[error("response channel was dropped before we could receive the response")]
+    ResponseChannelDropped(#[source] oneshot::Canceled),
+}
+
 #[derive(Debug, Clone)]
 pub struct ReplyControllerSender(mpsc::UnboundedSender<ReplyControllerMessage>);

@@ -30,14 +51,14 @@ impl ReplyControllerSender {
        recipient: AnonymousSenderTag,
        timed_out_ack: Weak<PendingAcknowledgement>,
        extra_surb_request: bool,
-    ) {
+    ) -> Result<(), ReplyControllerSenderError> {
        self.0
            .unbounded_send(ReplyControllerMessage::RetransmitReply {
                recipient,
                timed_out_ack,
                extra_surb_request,
            })
-            .expect("ReplyControllerReceiver has died!")
+            .map_err(ReplyControllerSenderError::SendRetransmissionData)
    }

    pub(crate) fn send_reply(
@@ -45,14 +66,16 @@ impl ReplyControllerSender {
        recipient: AnonymousSenderTag,
        message: Vec<u8>,
        lane: TransmissionLane,
-    ) {
+        max_retransmissions: Option<u32>,
+    ) -> Result<(), ReplyControllerSenderError> {
        self.0
            .unbounded_send(ReplyControllerMessage::SendReply {
                recipient,
                message,
                lane,
+                max_retransmissions,
            })
-            .expect("ReplyControllerReceiver has died!")
+            .map_err(ReplyControllerSenderError::SendReply)
    }

    pub(crate) fn send_additional_surbs(
@@ -60,42 +83,47 @@ impl ReplyControllerSender {
        sender_tag: AnonymousSenderTag,
        reply_surbs: Vec<ReplySurb>,
        from_surb_request: bool,
-    ) {
+    ) -> Result<(), ReplyControllerSenderError> {
        self.0
            .unbounded_send(ReplyControllerMessage::AdditionalSurbs {
                sender_tag,
                reply_surbs,
                from_surb_request,
            })
-            .expect("ReplyControllerReceiver has died!")
+            .map_err(ReplyControllerSenderError::AdditionalSurbs)
    }

-    pub(crate) fn send_additional_surbs_request(&self, recipient: Recipient, amount: u32) {
+    pub(crate) fn send_additional_surbs_request(
+        &self,
+        recipient: Recipient,
+        amount: u32,
+    ) -> Result<(), ReplyControllerSenderError> {
        self.0
            .unbounded_send(ReplyControllerMessage::AdditionalSurbsRequest {
                recipient: Box::new(recipient),
                amount,
            })
-            .expect("ReplyControllerReceiver has died!")
+            .map_err(ReplyControllerSenderError::AdditionalSurbsRequest)
    }

-    pub async fn get_lane_queue_length(&self, connection_id: ConnectionId) -> usize {
+    pub async fn get_lane_queue_length(
+        &self,
+        connection_id: ConnectionId,
+    ) -> Result<usize, ReplyControllerSenderError> {
        let (response_tx, response_rx) = oneshot::channel();
-        self.0
+        if let Err(err) = self
+            .0
            .unbounded_send(ReplyControllerMessage::LaneQueueLength {
                connection_id,
                response_channel: response_tx,
            })
-            .expect("ReplyControllerReceiver has died!");
-
-        match response_rx.await {
-            Ok(length) => length,
-            Err(_) => {
-                error!("The reply controller has dropped our response channel!");
-                // TODO: should we panic here instead? this message implies something weird and unrecoverable has happened
-                0
-            }
+        {
+            return Err(ReplyControllerSenderError::LaneQueueLength(err));
        }
+
+        response_rx
+            .await
+            .map_err(ReplyControllerSenderError::ResponseChannelDropped)
    }
 }

@@ -110,7 +138,10 @@ impl ReplyQueueLengths {
        }
    }

-    pub async fn get_lane_queue_length(&self, connection_id: ConnectionId) -> usize {
+    pub async fn get_lane_queue_length(
+        &self,
+        connection_id: ConnectionId,
+    ) -> Result<usize, ReplyControllerSenderError> {
        self.reply_controller_sender
            .get_lane_queue_length(connection_id)
            .await
@@ -120,7 +151,7 @@ impl ReplyQueueLengths {
 pub(crate) type ReplyControllerReceiver = mpsc::UnboundedReceiver<ReplyControllerMessage>;

 #[derive(Debug)]
-pub(crate) enum ReplyControllerMessage {
+pub enum ReplyControllerMessage {
    RetransmitReply {
        recipient: AnonymousSenderTag,
        timed_out_ack: Weak<PendingAcknowledgement>,
@@ -131,6 +162,7 @@ pub(crate) enum ReplyControllerMessage {
        recipient: AnonymousSenderTag,
        message: Vec<u8>,
        lane: TransmissionLane,
+        max_retransmissions: Option<u32>,
    },

    AdditionalSurbs {
@@ -16,14 +16,14 @@
 #![warn(clippy::todo)]
 #![warn(clippy::dbg_macro)]

-use std::time::Duration;
-
+use futures::StreamExt;
 use nym_client_core_config_types::StatsReporting;
 use nym_sphinx::addressing::Recipient;
 use nym_statistics_common::clients::{
    ClientStatsController, ClientStatsReceiver, ClientStatsSender,
 };
-use nym_task::connections::TransmissionLane;
+use nym_task::{connections::TransmissionLane, TaskClient};
+use std::time::Duration;

 use crate::{
    client::inbound_messages::{InputMessage, InputMessageSender},
@@ -51,6 +51,9 @@ pub(crate) struct StatisticsControl {

    /// Config for stats reporting (enabled, address, interval)
    reporting_config: StatsReporting,
+
+    /// Task client for listening for shutdown
+    task_client: TaskClient,
 }

 impl StatisticsControl {
@@ -59,19 +62,24 @@ impl StatisticsControl {
        client_type: String,
        client_stats_id: String,
        report_tx: InputMessageSender,
+        task_client: TaskClient,
    ) -> (Self, ClientStatsSender) {
        let (stats_tx, stats_rx) = tokio::sync::mpsc::unbounded_channel();

        let stats = ClientStatsController::new(client_stats_id, client_type);

+        let mut task_client_stats_sender = task_client.fork("stats_sender");
+        task_client_stats_sender.disarm();
+
        (
            StatisticsControl {
                stats,
                stats_rx,
                report_tx,
                reporting_config,
+                task_client,
            },
-            ClientStatsSender::new(Some(stats_tx)),
+            ClientStatsSender::new(Some(stats_tx), task_client_stats_sender),
        )
    }

@@ -91,16 +99,43 @@ impl StatisticsControl {
        }
    }

-    async fn run_with_shutdown(&mut self, mut task_client: nym_task::TaskClient) {
+    async fn run(&mut self) {
        log::debug!("Started StatisticsControl with graceful shutdown support");

-        let mut stats_report_interval =
-            tokio::time::interval(self.reporting_config.reporting_interval);
-        let mut local_report_interval = tokio::time::interval(LOCAL_REPORT_INTERVAL);
-        let mut snapshot_interval = tokio::time::interval(SNAPSHOT_INTERVAL);
+        #[cfg(not(target_arch = "wasm32"))]
+        let mut stats_report_interval = tokio_stream::wrappers::IntervalStream::new(
+            tokio::time::interval(self.reporting_config.reporting_interval),
+        );

-        loop {
+        #[cfg(not(target_arch = "wasm32"))]
+        let mut local_report_interval = tokio_stream::wrappers::IntervalStream::new(
+            tokio::time::interval(LOCAL_REPORT_INTERVAL),
+        );
+
+        #[cfg(not(target_arch = "wasm32"))]
+        let mut snapshot_interval =
+            tokio_stream::wrappers::IntervalStream::new(tokio::time::interval(SNAPSHOT_INTERVAL));
+
+        #[cfg(target_arch = "wasm32")]
+        let mut stats_report_interval = gloo_timers::future::IntervalStream::new(
+            self.reporting_config.reporting_interval.as_millis() as u32,
+        );
+
+        #[cfg(target_arch = "wasm32")]
+        let mut local_report_interval =
+            gloo_timers::future::IntervalStream::new(LOCAL_REPORT_INTERVAL.as_millis() as u32);
+
+        #[cfg(target_arch = "wasm32")]
+        let mut snapshot_interval =
+            gloo_timers::future::IntervalStream::new(SNAPSHOT_INTERVAL.as_millis() as u32);
+
+        while !self.task_client.is_shutdown() {
            tokio::select! {
+                biased;
+                _ = self.task_client.recv() => {
+                    log::trace!("StatisticsControl: Received shutdown");
+                    break;
+                },
                stats_event = self.stats_rx.recv() => match stats_event {
                        Some(stats_event) => self.stats.handle_event(stats_event),
                        None => {
@@ -108,44 +143,48 @@ impl StatisticsControl {
                            break;
                        }
                },
-                _ = snapshot_interval.tick() => {
+                _ = snapshot_interval.next() => {
                    self.stats.snapshot();
                }
-                _ = stats_report_interval.tick(), if self.reporting_config.enabled && self.reporting_config.provider_address.is_some() => {
-                    // SAFTEY : this branch executes only if reporting is not none, so unwrapp is fine
-                    #[allow(clippy::unwrap_used)]
-                    self.report_stats(self.reporting_config.provider_address.unwrap()).await;
+                _ = stats_report_interval.next() => {
+                    let Some(recipient) = self.reporting_config.provider_address else {
+                        continue
+                    };
+
+                    if self.reporting_config.enabled {
+                        self.report_stats(recipient).await;
+                    }
                }

-                _ = local_report_interval.tick() => {
-                    self.stats.local_report(&mut task_client);
+                _ = local_report_interval.next() => {
+                    self.stats.local_report(&mut self.task_client);
                }
-                _ = task_client.recv_with_delay() => {
-                    log::trace!("StatisticsControl: Received shutdown");
-                    break;
-                },
            }
        }
-        task_client.recv_timeout().await;
        log::debug!("StatisticsControl: Exiting");
    }

-    pub(crate) fn start_with_shutdown(mut self, task_client: nym_task::TaskClient) {
+    pub(crate) fn start(mut self) {
        spawn_future(async move {
-            self.run_with_shutdown(task_client).await;
+            self.run().await;
        })
    }

-    pub(crate) fn create_and_start_with_shutdown(
+    pub(crate) fn create_and_start(
        reporting_config: StatsReporting,
        client_type: String,
        client_stats_id: String,
        report_tx: InputMessageSender,
-        task_client: nym_task::TaskClient,
+        task_client: TaskClient,
    ) -> ClientStatsSender {
-        let (controller, sender) =
-            Self::create(reporting_config, client_type, client_stats_id, report_tx);
-        controller.start_with_shutdown(task_client);
+        let (controller, sender) = Self::create(
+            reporting_config,
+            client_type,
+            client_stats_id,
+            report_tx,
+            task_client,
+        );
+        controller.start();
        sender
    }
 }
@@ -2,8 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use nym_sphinx::addressing::clients::Recipient;
-use nym_sphinx::params::DEFAULT_NUM_MIX_HOPS;
-use nym_topology::{NymTopology, NymTopologyError};
+use nym_topology::{NymRouteProvider, NymTopology, NymTopologyError};
 use std::ops::Deref;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
@@ -17,29 +16,36 @@ pub struct TopologyAccessorInner {
    // few seconds, while reads are needed every single packet generated.
    // However, proper benchmarks will be needed to determine if `RwLock` is indeed a better
    // approach than a `Mutex`
-    topology: RwLock<Option<NymTopology>>,
+    topology: RwLock<NymRouteProvider>,
 }

 impl TopologyAccessorInner {
-    fn new() -> Self {
+    fn new(initial: NymRouteProvider) -> Self {
        TopologyAccessorInner {
            controlled_manually: AtomicBool::new(false),
            released_manual_control: Notify::new(),
-            topology: RwLock::new(None),
+            topology: RwLock::new(initial),
        }
    }

    async fn update(&self, new: Option<NymTopology>) {
-        *self.topology.write().await = new;
+        let mut guard = self.topology.write().await;
+
+        match new {
+            Some(updated) => {
+                guard.update(updated);
+            }
+            None => guard.clear_topology(),
+        }
    }
 }

 pub struct TopologyReadPermit<'a> {
-    permit: RwLockReadGuard<'a, Option<NymTopology>>,
+    permit: RwLockReadGuard<'a, NymRouteProvider>,
 }

 impl Deref for TopologyReadPermit<'_> {
-    type Target = Option<NymTopology>;
+    type Target = NymRouteProvider;

    fn deref(&self) -> &Self::Target {
        &self.permit
@@ -53,43 +59,31 @@ impl<'a> TopologyReadPermit<'a> {
        &'a self,
        ack_recipient: &Recipient,
        packet_recipient: Option<&Recipient>,
-    ) -> Result<&'a NymTopology, NymTopologyError> {
+    ) -> Result<&'a NymRouteProvider, NymTopologyError> {
+        let route_provider = self.permit.deref();
+        let topology = &route_provider.topology;
+
        // 1. Have we managed to get anything from the refresher, i.e. have the nym-api queries gone through?
-        let topology = self
-            .permit
-            .as_ref()
-            .ok_or(NymTopologyError::EmptyNetworkTopology)?;
+        topology.ensure_not_empty()?;

-        // 2. does it have any mixnode at all?
-        // 3. does it have any gateways at all?
-        // 4. does it have a mixnode on each layer?
-        topology.ensure_can_construct_path_through(DEFAULT_NUM_MIX_HOPS)?;
+        // 2. does the topology have a node on each mixing layer?
+        topology.ensure_minimally_routable()?;

-        // 5. does it contain OUR gateway (so that we could create an ack packet)?
-        if !topology.gateway_exists(ack_recipient.gateway()) {
-            return Err(NymTopologyError::NonExistentGatewayError {
-                identity_key: ack_recipient.gateway().to_base58_string(),
-            });
-        }
+        // 3. does it contain OUR gateway (so that we could create an ack packet)?
+        let _ = route_provider.egress_by_identity(ack_recipient.gateway())?;

-        // 6. for our target recipient, does it contain THEIR gateway (so that we could create
+        // 4. for our target recipient, does it contain THEIR gateway (so that we send anything over?)
        if let Some(recipient) = packet_recipient {
-            if !topology.gateway_exists(recipient.gateway()) {
-                return Err(NymTopologyError::NonExistentGatewayError {
-                    identity_key: recipient.gateway().to_base58_string(),
-                });
-            }
+            let _ = route_provider.egress_by_identity(recipient.gateway())?;
        }

-        Ok(topology)
+        Ok(route_provider)
    }
 }

-impl<'a> From<RwLockReadGuard<'a, Option<NymTopology>>> for TopologyReadPermit<'a> {
-    fn from(read_permit: RwLockReadGuard<'a, Option<NymTopology>>) -> Self {
-        TopologyReadPermit {
-            permit: read_permit,
-        }
+impl<'a> From<RwLockReadGuard<'a, NymRouteProvider>> for TopologyReadPermit<'a> {
+    fn from(permit: RwLockReadGuard<'a, NymRouteProvider>) -> Self {
+        TopologyReadPermit { permit }
    }
 }

@@ -99,9 +93,11 @@ pub struct TopologyAccessor {
 }

 impl TopologyAccessor {
-    pub fn new() -> Self {
+    pub fn new(ignore_egress_epoch_roles: bool) -> Self {
        TopologyAccessor {
-            inner: Arc::new(TopologyAccessorInner::new()),
+            inner: Arc::new(TopologyAccessorInner::new(NymRouteProvider::new_empty(
+                ignore_egress_epoch_roles,
+            ))),
        }
    }

@@ -121,8 +117,21 @@ impl TopologyAccessor {
        self.inner.released_manual_control.notified().await
    }

+    #[deprecated(note = "use .current_route_provider instead")]
    pub async fn current_topology(&self) -> Option<NymTopology> {
-        self.inner.topology.read().await.clone()
+        self.current_route_provider()
+            .await
+            .as_ref()
+            .map(|p| p.topology.clone())
+    }
+
+    pub async fn current_route_provider(&self) -> Option<RwLockReadGuard<NymRouteProvider>> {
+        let provider = self.inner.topology.read().await;
+        if provider.topology.is_empty() {
+            None
+        } else {
+            Some(provider)
+        }
    }

    pub async fn manually_change_topology(&self, new_topology: NymTopology) {
@@ -140,15 +149,11 @@ impl TopologyAccessor {
    // only used by the client at startup to get a slightly more reasonable error message
    // (currently displays as unused because health checker is disabled due to required changes)
    pub async fn ensure_is_routable(&self) -> Result<(), NymTopologyError> {
-        match self.inner.topology.read().await.deref() {
-            None => Err(NymTopologyError::EmptyNetworkTopology),
-            Some(ref topology) => topology.ensure_can_construct_path_through(DEFAULT_NUM_MIX_HOPS),
-        }
-    }
-}
-
-impl Default for TopologyAccessor {
-    fn default() -> Self {
-        TopologyAccessor::new()
+        self.inner
+            .topology
+            .read()
+            .await
+            .topology
+            .ensure_minimally_routable()
    }
 }
@@ -3,7 +3,6 @@ use log::{debug, error};
 use nym_explorer_client::{ExplorerClient, PrettyDetailedMixNodeBond};
 use nym_network_defaults::var_names::EXPLORER_API;
 use nym_topology::{
-    nym_topology_from_basic_info,
    provider_trait::{async_trait, TopologyProvider},
    NymTopology,
 };
@@ -15,8 +14,6 @@ use url::Url;

 pub use nym_country_group::CountryGroup;

-const MIN_NODES_PER_LAYER: usize = 1;
-
 fn create_explorer_client() -> Option<ExplorerClient> {
    let Ok(explorer_api_url) = std::env::var(EXPLORER_API) else {
        error!("Missing EXPLORER_API");
@@ -63,30 +60,20 @@ fn log_mixnode_distribution(mixnodes: &HashMap<CountryGroup, Vec<NodeId>>) {
 }

 fn check_layer_integrity(topology: NymTopology) -> Result<(), ()> {
-    let mixes = topology.mixes();
-    if mixes.keys().len() < 3 {
+    if topology.ensure_minimally_routable().is_err() {
        error!("Layer is missing in topology!");
        return Err(());
    }
-    for (layer, mixnodes) in mixes {
-        debug!("Layer {:?} has {} mixnodes", layer, mixnodes.len());
-        if mixnodes.len() < MIN_NODES_PER_LAYER {
-            error!(
-                "There are only {} mixnodes in layer {:?}",
-                mixnodes.len(),
-                layer
-            );
-            return Err(());
-        }
-    }
    Ok(())
 }

+#[deprecated(note = "use NymApiTopologyProvider instead as explorer API will soon be removed")]
 pub struct GeoAwareTopologyProvider {
    validator_client: nym_validator_client::client::NymApiClient,
    filter_on: GroupBy,
 }

+#[allow(deprecated)]
 impl GeoAwareTopologyProvider {
    pub fn new(mut nym_api_urls: Vec<Url>, filter_on: GroupBy) -> GeoAwareTopologyProvider {
        log::info!(
@@ -104,6 +91,15 @@ impl GeoAwareTopologyProvider {
    }

    async fn get_topology(&self) -> Option<NymTopology> {
+        let rewarded_set = self
+            .validator_client
+            .get_current_rewarded_set()
+            .await
+            .inspect_err(|err| error!("failed to get current rewarded set: {err}"))
+            .ok()?;
+
+        let mut topology = NymTopology::new_empty(rewarded_set);
+
        let mixnodes = match self
            .validator_client
            .get_all_basic_active_mixing_assigned_nodes()
@@ -187,7 +183,8 @@ impl GeoAwareTopologyProvider {
            .filter(|m| filtered_mixnode_ids.contains(&m.node_id))
            .collect::<Vec<_>>();

-        let topology = nym_topology_from_basic_info(&mixnodes, &gateways);
+        topology.add_skimmed_nodes(&mixnodes);
+        topology.add_skimmed_nodes(&gateways);

        // TODO: return real error type
        check_layer_integrity(topology.clone()).ok()?;
@@ -196,6 +193,7 @@ impl GeoAwareTopologyProvider {
    }
 }

+#[allow(deprecated)]
 #[cfg(not(target_arch = "wasm32"))]
 #[async_trait]
 impl TopologyProvider for GeoAwareTopologyProvider {
@@ -205,6 +203,7 @@ impl TopologyProvider for GeoAwareTopologyProvider {
    }
 }

+#[allow(deprecated)]
 #[cfg(target_arch = "wasm32")]
 #[async_trait(?Send)]
 impl TopologyProvider for GeoAwareTopologyProvider {
@@ -6,6 +6,7 @@ pub(crate) use accessor::{TopologyAccessor, TopologyReadPermit};
 use futures::StreamExt;
 use log::*;
 use nym_sphinx::addressing::nodes::NodeIdentity;
+use nym_task::TaskClient;
 use nym_topology::NymTopologyError;
 use std::time::Duration;

@@ -19,6 +20,7 @@ mod accessor;
 pub mod geo_aware_provider;
 pub mod nym_api_provider;

+#[allow(deprecated)]
 pub use geo_aware_provider::GeoAwareTopologyProvider;
 pub use nym_api_provider::{Config as NymApiTopologyProviderConfig, NymApiTopologyProvider};
 pub use nym_topology::provider_trait::TopologyProvider;
@@ -27,7 +29,7 @@ pub use nym_topology::provider_trait::TopologyProvider;
 const MAX_FAILURE_COUNT: usize = 10;

 pub struct TopologyRefresherConfig {
-    refresh_rate: Duration,
+    pub refresh_rate: Duration,
 }

 impl TopologyRefresherConfig {
@@ -42,6 +44,8 @@ pub struct TopologyRefresher {

    refresh_rate: Duration,
    consecutive_failure_count: usize,
+
+    task_client: TaskClient,
 }

 impl TopologyRefresher {
@@ -49,12 +53,14 @@ impl TopologyRefresher {
        cfg: TopologyRefresherConfig,
        topology_accessor: TopologyAccessor,
        topology_provider: Box<dyn TopologyProvider + Send + Sync>,
+        task_client: TaskClient,
    ) -> Self {
        TopologyRefresher {
            topology_provider,
            topology_accessor,
            refresh_rate: cfg.refresh_rate,
            consecutive_failure_count: 0,
+            task_client,
        }
    }

@@ -96,28 +102,24 @@ impl TopologyRefresher {
        self.topology_accessor.ensure_is_routable().await
    }

-    pub async fn ensure_contains_gateway(
+    pub async fn ensure_contains_routable_egress(
        &self,
-        gateway: &NodeIdentity,
+        egress: NodeIdentity,
    ) -> Result<(), NymTopologyError> {
        let topology = self
            .topology_accessor
-            .current_topology()
+            .current_route_provider()
            .await
            .ok_or(NymTopologyError::EmptyNetworkTopology)?;

-        if !topology.gateway_exists(gateway) {
-            return Err(NymTopologyError::NonExistentGatewayError {
-                identity_key: gateway.to_base58_string(),
-            });
-        }
+        let _ = topology.egress_by_identity(egress)?;

        Ok(())
    }

    pub async fn wait_for_gateway(
        &mut self,
-        gateway: &NodeIdentity,
+        gateway: NodeIdentity,
        timeout_duration: Duration,
    ) -> Result<(), NymTopologyError> {
        info!(
@@ -135,7 +137,7 @@ impl TopologyRefresher {
                    })
                }
                _ = self.try_refresh() => {
-                    if self.ensure_contains_gateway(gateway).await.is_ok() {
+                    if self.ensure_contains_routable_egress(gateway).await.is_ok() {
                        return Ok(())
                    }
                    info!("gateway '{gateway}' is still not online...");
@@ -145,7 +147,7 @@ impl TopologyRefresher {
        }
    }

-    pub fn start_with_shutdown(mut self, mut shutdown: nym_task::TaskClient) {
+    pub fn start(mut self) {
        spawn_future(async move {
            debug!("Started TopologyRefresher with graceful shutdown support");

@@ -158,17 +160,17 @@ impl TopologyRefresher {
            let mut interval =
                gloo_timers::future::IntervalStream::new(self.refresh_rate.as_millis() as u32);

-            while !shutdown.is_shutdown() {
+            while !self.task_client.is_shutdown() {
                tokio::select! {
                    _ = interval.next() => {
                        self.try_refresh().await;
                    },
-                    _ = shutdown.recv() => {
+                    _ = self.task_client.recv() => {
                        log::trace!("TopologyRefresher: Received shutdown");
                    },
                }
            }
-            shutdown.recv_timeout().await;
+            self.task_client.recv_timeout().await;
            log::debug!("TopologyRefresher: Exiting");
        })
    }
@@ -4,32 +4,39 @@
 use async_trait::async_trait;
 use log::{debug, error, warn};
 use nym_topology::provider_trait::TopologyProvider;
-use nym_topology::{NymTopology, NymTopologyError};
+use nym_topology::NymTopology;
 use nym_validator_client::UserAgent;
 use rand::prelude::SliceRandom;
 use rand::thread_rng;
+use std::cmp::min;
 use url::Url;

-// the same values as our current (10.06.24) blacklist
-pub const DEFAULT_MIN_MIXNODE_PERFORMANCE: u8 = 50;
-pub const DEFAULT_MIN_GATEWAY_PERFORMANCE: u8 = 50;
-
 #[derive(Debug)]
 pub struct Config {
    pub min_mixnode_performance: u8,
    pub min_gateway_performance: u8,
+    pub use_extended_topology: bool,
+    pub ignore_egress_epoch_role: bool,
 }

-impl Default for Config {
-    fn default() -> Self {
-        // old values that decided on blacklist membership
+impl From<nym_client_core_config_types::Topology> for Config {
+    fn from(value: nym_client_core_config_types::Topology) -> Self {
        Config {
-            min_mixnode_performance: DEFAULT_MIN_MIXNODE_PERFORMANCE,
-            min_gateway_performance: DEFAULT_MIN_GATEWAY_PERFORMANCE,
+            min_mixnode_performance: value.minimum_mixnode_performance,
+            min_gateway_performance: value.minimum_gateway_performance,
+            use_extended_topology: value.use_extended_topology,
+            ignore_egress_epoch_role: value.ignore_egress_epoch_role,
        }
    }
 }

+impl Config {
+    // if we're using 'extended' topology, filter the nodes based on the lowest set performance
+    fn min_node_performance(&self) -> u8 {
+        min(self.min_mixnode_performance, self.min_gateway_performance)
+    }
+}
+
 pub struct NymApiTopologyProvider {
    config: Config,

@@ -39,7 +46,11 @@ pub struct NymApiTopologyProvider {
 }

 impl NymApiTopologyProvider {
-    pub fn new(config: Config, mut nym_api_urls: Vec<Url>, user_agent: Option<UserAgent>) -> Self {
+    pub fn new(
+        config: impl Into<Config>,
+        mut nym_api_urls: Vec<Url>,
+        user_agent: Option<UserAgent>,
+    ) -> Self {
        nym_api_urls.shuffle(&mut thread_rng());

        let validator_client = if let Some(user_agent) = user_agent {
@@ -52,7 +63,7 @@ impl NymApiTopologyProvider {
        };

        NymApiTopologyProvider {
-            config,
+            config: config.into(),
            validator_client,
            nym_api_urls,
            currently_used_api: 0,
@@ -70,70 +81,69 @@ impl NymApiTopologyProvider {
            .change_nym_api(self.nym_api_urls[self.currently_used_api].clone())
    }

-    /// Verifies whether nodes a reasonably distributed among all mix layers.
-    ///
-    /// In ideal world we would have 33% nodes on layer 1, 33% on layer 2 and 33% on layer 3.
-    /// However, this is a rather unrealistic expectation, instead we check whether there exists
-    /// a layer with more than 66% of nodes or with fewer than 15% and if so, we trigger a failure.
-    ///
-    /// # Arguments
-    ///
-    /// * `topology`: active topology constructed from validator api data
-    fn check_layer_distribution(
-        &self,
-        active_topology: &NymTopology,
-    ) -> Result<(), NymTopologyError> {
-        let lower_threshold = 0.15;
-        let upper_threshold = 0.66;
-        active_topology.ensure_even_layer_distribution(lower_threshold, upper_threshold)
-    }
-
    async fn get_current_compatible_topology(&mut self) -> Option<NymTopology> {
-        let mixnodes = match self
+        let rewarded_set = self
            .validator_client
-            .get_all_basic_active_mixing_assigned_nodes()
+            .get_current_rewarded_set()
            .await
-        {
-            Err(err) => {
-                error!("failed to get network mixnodes - {err}");
-                return None;
-            }
-            Ok(mixes) => mixes,
-        };
+            .inspect_err(|err| error!("failed to get current rewarded set: {err}"))
+            .ok()?;

-        let gateways = match self
-            .validator_client
-            .get_all_basic_entry_assigned_nodes()
-            .await
-        {
-            Err(err) => {
-                error!("failed to get network gateways - {err}");
-                return None;
-            }
-            Ok(gateways) => gateways,
-        };
+        let mut topology = NymTopology::new_empty(rewarded_set);

-        debug!(
-            "there are {} mixnodes and {} gateways in total (before performance filtering)",
-            mixnodes.len(),
-            gateways.len()
-        );
+        if self.config.use_extended_topology {
+            let all_nodes = self
+                .validator_client
+                .get_all_basic_nodes()
+                .await
+                .inspect_err(|err| error!("failed to get network nodes: {err}"))
+                .ok()?;

-        let topology = NymTopology::from_unordered(
-            mixnodes.iter().filter(|m| {
-                m.performance.round_to_integer() >= self.config.min_mixnode_performance
-            }),
-            gateways.iter().filter(|g| {
-                g.performance.round_to_integer() >= self.config.min_gateway_performance
-            }),
-        );
-        if let Err(err) = self.check_layer_distribution(&topology) {
-            warn!("The current filtered active topology has extremely skewed layer distribution. It cannot be used: {err}");
-            self.use_next_nym_api();
-            None
+            debug!(
+                "there are {} nodes on the network (before filtering)",
+                all_nodes.len()
+            );
+            topology.add_additional_nodes(all_nodes.iter().filter(|n| {
+                n.performance.round_to_integer() >= self.config.min_node_performance()
+            }));
        } else {
-            Some(topology)
+            // if we're not using extended topology, we're only getting active set mixnodes and gateways
+
+            let mixnodes = self
+                .validator_client
+                .get_all_basic_active_mixing_assigned_nodes()
+                .await
+                .inspect_err(|err| error!("failed to get network mixnodes: {err}"))
+                .ok()?;
+
+            // TODO: we really should be getting ACTIVE gateways only
+            let gateways = self
+                .validator_client
+                .get_all_basic_entry_assigned_nodes()
+                .await
+                .inspect_err(|err| error!("failed to get network gateways: {err}"))
+                .ok()?;
+
+            debug!(
+                "there are {} mixnodes and {} gateways in total (before performance filtering)",
+                mixnodes.len(),
+                gateways.len()
+            );
+
+            topology.add_additional_nodes(mixnodes.iter().filter(|m| {
+                m.performance.round_to_integer() >= self.config.min_mixnode_performance
+            }));
+            topology.add_additional_nodes(gateways.iter().filter(|m| {
+                m.performance.round_to_integer() >= self.config.min_gateway_performance
+            }));
+        };
+
+        if !topology.is_minimally_routable() {
+            error!("the current filtered active topology can't be used to construct any packets");
+            return None;
        }
+
+        Some(topology)
    }
 }

@@ -142,7 +152,11 @@ impl NymApiTopologyProvider {
 #[async_trait]
 impl TopologyProvider for NymApiTopologyProvider {
    async fn get_new_topology(&mut self) -> Option<NymTopology> {
-        self.get_current_compatible_topology().await
+        let Some(topology) = self.get_current_compatible_topology().await else {
+            self.use_next_nym_api();
+            return None;
+        };
+        Some(topology)
    }
 }

@@ -150,6 +164,10 @@ impl TopologyProvider for NymApiTopologyProvider {
 #[async_trait(?Send)]
 impl TopologyProvider for NymApiTopologyProvider {
    async fn get_new_topology(&mut self) -> Option<NymTopology> {
-        self.get_current_compatible_topology().await
+        let Some(topology) = self.get_current_compatible_topology().await else {
+            self.use_next_nym_api();
+            return None;
+        };
+        Some(topology)
    }
 }
@@ -58,8 +58,8 @@ impl<T> TransmissionBuffer<T> {
    }

    #[cfg(not(target_arch = "wasm32"))]
-    pub(crate) fn num_lanes(&self) -> usize {
-        self.buffer.keys().count()
+    pub(crate) fn lanes(&self) -> Vec<TransmissionLane> {
+        self.buffer.keys().cloned().collect()
    }

    pub(crate) fn lane_length(&self, lane: &TransmissionLane) -> Option<usize> {
@@ -83,6 +83,7 @@ impl<T> TransmissionBuffer<T> {
    }

    #[cfg(not(target_arch = "wasm32"))]
+    #[allow(unused)]
    pub(crate) fn total_size_in_bytes(&self) -> usize
    where
        T: SizedData,
@@ -4,8 +4,8 @@
 use crate::client::mix_traffic::transceiver::ErasedGatewayError;
 use nym_crypto::asymmetric::identity::Ed25519RecoveryError;
 use nym_gateway_client::error::GatewayClientError;
-use nym_topology::gateway::GatewayConversionError;
-use nym_topology::NymTopologyError;
+use nym_topology::node::RoutingNodeError;
+use nym_topology::{NodeId, NymTopologyError};
 use nym_validator_client::ValidatorClientError;
 use std::error::Error;
 use std::path::PathBuf;
@@ -36,6 +36,13 @@ pub enum ClientCoreError {
    #[error("no gateway with id: {0}")]
    NoGatewayWithId(String),

+    #[error("Invalid URL: {0}")]
+    InvalidUrl(String),
+
+    #[cfg(not(target_arch = "wasm32"))]
+    #[error("resolution failed: {0}")]
+    ResolutionFailed(#[from] nym_http_api_client::HickoryDnsError),
+
    #[error("no gateways on network")]
    NoGatewaysOnNetwork,

@@ -74,10 +81,10 @@ pub enum ClientCoreError {
    #[error("the gateway id is invalid - {0}")]
    UnableToCreatePublicKeyFromGatewayId(Ed25519RecoveryError),

-    #[error("The gateway is malformed: {source}")]
+    #[error("the node is malformed: {source}")]
    MalformedGateway {
        #[from]
-        source: GatewayConversionError,
+        source: Box<RoutingNodeError>,
    },

    #[error("failed to establish connection to gateway: {source}")]
@@ -96,6 +103,9 @@ pub enum ClientCoreError {
    #[error("timed out while trying to establish gateway connection")]
    GatewayConnectionTimeout,

+    #[error("failed to forward mix messages to gateway")]
+    GatewayFailedToForwardMessages,
+
    #[error("no ping measurements for the gateway ({identity}) performed")]
    NoGatewayMeasurements { identity: String },

@@ -159,6 +169,9 @@ pub enum ClientCoreError {
    #[error("the specified gateway '{gateway}' does not support the wss protocol")]
    UnsupportedWssProtocol { gateway: String },

+    #[error("node {id} ({identity}) does not support mixnet entry mode")]
+    UnsupportedEntry { id: NodeId, identity: String },
+
    #[error(
    "failed to load custom topology using path '{}'. detailed message: {source}", file_path.display()
    )]
@@ -209,6 +222,9 @@ pub enum ClientCoreError {
        "fresh registration with gateway {gateway_id} somehow requires an additional key upgrade!"
    )]
    UnexpectedKeyUpgrade { gateway_id: String },
+
+    #[error("failed to derive keys from master key")]
+    HkdfDerivationError {},
 }

 /// Set of messages that the client can send to listeners via the task manager
@@ -7,7 +7,7 @@ use futures::{SinkExt, StreamExt};
 use log::{debug, info, trace, warn};
 use nym_crypto::asymmetric::identity;
 use nym_gateway_client::GatewayClient;
-use nym_topology::gateway;
+use nym_topology::node::RoutingNode;
 use nym_validator_client::client::IdentityKeyRef;
 use nym_validator_client::UserAgent;
 use rand::{seq::SliceRandom, Rng};
@@ -15,6 +15,10 @@ use std::{sync::Arc, time::Duration};
 use tungstenite::Message;
 use url::Url;

+#[cfg(not(target_arch = "wasm32"))]
+use crate::init::websockets::connect_async;
+
+use nym_topology::NodeId;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::net::TcpStream;
 #[cfg(not(target_arch = "wasm32"))]
@@ -22,10 +26,7 @@ use tokio::time::sleep;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::time::Instant;
 #[cfg(not(target_arch = "wasm32"))]
-use tokio_tungstenite::connect_async;
-#[cfg(not(target_arch = "wasm32"))]
 use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
-
 #[cfg(target_arch = "wasm32")]
 use wasm_utils::websocket::JSWebsocket;
 #[cfg(target_arch = "wasm32")]
@@ -48,22 +49,30 @@ const PING_TIMEOUT: Duration = Duration::from_millis(1000);

 // The abstraction that some of these helpers use
 pub trait ConnectableGateway {
-    fn identity(&self) -> &identity::PublicKey;
-    fn clients_address(&self) -> String;
+    fn node_id(&self) -> NodeId;
+    fn identity(&self) -> identity::PublicKey;
+    fn clients_address(&self, prefer_ipv6: bool) -> Option<String>;
    fn is_wss(&self) -> bool;
 }

-impl ConnectableGateway for gateway::LegacyNode {
-    fn identity(&self) -> &identity::PublicKey {
-        self.identity()
+impl ConnectableGateway for RoutingNode {
+    fn node_id(&self) -> NodeId {
+        self.node_id
    }

-    fn clients_address(&self) -> String {
-        self.clients_address()
+    fn identity(&self) -> identity::PublicKey {
+        self.identity_key
+    }
+
+    fn clients_address(&self, prefer_ipv6: bool) -> Option<String> {
+        self.ws_entry_address(prefer_ipv6)
    }

    fn is_wss(&self) -> bool {
-        self.clients_wss_port.is_some()
+        self.entry
+            .as_ref()
+            .map(|e| e.clients_wss_port.is_some())
+            .unwrap_or_default()
    }
 }

@@ -78,12 +87,13 @@ impl<'a, G: ConnectableGateway> GatewayWithLatency<'a, G> {
    }
 }

-pub async fn current_gateways<R: Rng>(
+pub async fn gateways_for_init<R: Rng>(
    rng: &mut R,
    nym_apis: &[Url],
    user_agent: Option<UserAgent>,
    minimum_performance: u8,
-) -> Result<Vec<gateway::LegacyNode>, ClientCoreError> {
+    ignore_epoch_roles: bool,
+) -> Result<Vec<RoutingNode>, ClientCoreError> {
    let nym_api = nym_apis
        .choose(rng)
        .ok_or(ClientCoreError::ListOfNymApisIsEmpty)?;
@@ -100,11 +110,14 @@ pub async fn current_gateways<R: Rng>(

    log::trace!("Gateways: {:#?}", gateways);

+    // filter out gateways below minimum performance and ones that could operate as a mixnode
+    // (we don't want instability)
    let valid_gateways = gateways
        .iter()
+        .filter(|g| ignore_epoch_roles || !g.supported_roles.mixnode)
        .filter(|g| g.performance.round_to_integer() >= minimum_performance)
        .filter_map(|gateway| gateway.try_into().ok())
-        .collect::<Vec<gateway::LegacyNode>>();
+        .collect::<Vec<_>>();
    log::debug!("After checking validity: {}", valid_gateways.len());
    log::trace!("Valid gateways: {:#?}", valid_gateways);

@@ -120,7 +133,7 @@ pub async fn current_gateways<R: Rng>(
 async fn connect(endpoint: &str) -> Result<WsConn, ClientCoreError> {
    match tokio::time::timeout(CONN_TIMEOUT, connect_async(endpoint)).await {
        Err(_elapsed) => Err(ClientCoreError::GatewayConnectionTimeout),
-        Ok(Err(conn_failure)) => Err(conn_failure.into()),
+        Ok(Err(conn_failure)) => Err(conn_failure),
        Ok(Ok((stream, _))) => Ok(stream),
    }
 }
@@ -134,7 +147,12 @@ async fn measure_latency<G>(gateway: &G) -> Result<GatewayWithLatency<G>, Client
 where
    G: ConnectableGateway,
 {
-    let addr = gateway.clients_address();
+    let Some(addr) = gateway.clients_address(false) else {
+        return Err(ClientCoreError::UnsupportedEntry {
+            id: gateway.node_id(),
+            identity: gateway.identity().to_string(),
+        });
+    };
    trace!(
        "establishing connection to {} ({addr})...",
        gateway.identity(),
@@ -190,7 +208,7 @@ where
    Ok(GatewayWithLatency::new(gateway, avg))
 }

-pub async fn choose_gateway_by_latency<'a, R: Rng, G: ConnectableGateway + Clone>(
+pub async fn choose_gateway_by_latency<R: Rng, G: ConnectableGateway + Clone>(
    rng: &mut R,
    gateways: &[G],
    must_use_tls: bool,
@@ -205,7 +223,7 @@ pub async fn choose_gateway_by_latency<'a, R: Rng, G: ConnectableGateway + Clone
    let gateways_with_latency = Arc::new(tokio::sync::Mutex::new(Vec::new()));
    futures::stream::iter(gateways)
        .for_each_concurrent(CONCURRENT_GATEWAYS_MEASURED, |gateway| async {
-            let id = *gateway.identity();
+            let id = gateway.identity();
            trace!("measuring latency to {id}...");
            match measure_latency(gateway).await {
                Ok(with_latency) => {
@@ -252,9 +270,9 @@ fn filter_by_tls<G: ConnectableGateway>(

 pub(super) fn uniformly_random_gateway<R: Rng>(
    rng: &mut R,
-    gateways: &[gateway::LegacyNode],
+    gateways: &[RoutingNode],
    must_use_tls: bool,
-) -> Result<gateway::LegacyNode, ClientCoreError> {
+) -> Result<RoutingNode, ClientCoreError> {
    filter_by_tls(gateways, must_use_tls)?
        .choose(rng)
        .ok_or(ClientCoreError::NoGatewaysOnNetwork)
@@ -263,9 +281,9 @@ pub(super) fn uniformly_random_gateway<R: Rng>(

 pub(super) fn get_specified_gateway(
    gateway_identity: IdentityKeyRef,
-    gateways: &[gateway::LegacyNode],
+    gateways: &[RoutingNode],
    must_use_tls: bool,
-) -> Result<gateway::LegacyNode, ClientCoreError> {
+) -> Result<RoutingNode, ClientCoreError> {
    log::debug!("Requesting specified gateway: {}", gateway_identity);
    let user_gateway = identity::PublicKey::from_base58_string(gateway_identity)
        .map_err(ClientCoreError::UnableToCreatePublicKeyFromGatewayId)?;
@@ -275,7 +293,14 @@ pub(super) fn get_specified_gateway(
        .find(|gateway| gateway.identity_key == user_gateway)
        .ok_or_else(|| ClientCoreError::NoGatewayWithId(gateway_identity.to_string()))?;

-    if must_use_tls && gateway.clients_wss_port.is_none() {
+    let Some(entry_details) = gateway.entry.as_ref() else {
+        return Err(ClientCoreError::UnsupportedEntry {
+            id: gateway.node_id,
+            identity: gateway.identity().to_string(),
+        });
+    };
+
+    if must_use_tls && entry_details.clients_wss_port.is_none() {
        return Err(ClientCoreError::UnsupportedWssProtocol {
            gateway: gateway_identity.to_string(),
        });
@@ -19,13 +19,15 @@ use crate::init::types::{
 use nym_client_core_gateways_storage::GatewaysDetailsStore;
 use nym_client_core_gateways_storage::{GatewayDetails, GatewayRegistration};
 use nym_gateway_client::client::InitGatewayClient;
-use nym_topology::gateway;
+use nym_topology::node::RoutingNode;
 use rand::rngs::OsRng;
 use rand::{CryptoRng, RngCore};
 use serde::Serialize;

 pub mod helpers;
 pub mod types;
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) mod websockets;

 // helpers for error wrapping

@@ -50,7 +52,7 @@ async fn setup_new_gateway<K, D>(
    key_store: &K,
    details_store: &D,
    selection_specification: GatewaySelectionSpecification,
-    available_gateways: Vec<gateway::LegacyNode>,
+    available_gateways: Vec<RoutingNode>,
 ) -> Result<InitialisationResult, ClientCoreError>
 where
    K: KeyStore,
@@ -13,11 +13,11 @@ use nym_crypto::asymmetric::identity;
 use nym_gateway_client::client::InitGatewayClient;
 use nym_gateway_requests::shared_key::SharedGatewayKey;
 use nym_sphinx::addressing::clients::Recipient;
-use nym_topology::gateway;
+use nym_topology::node::RoutingNode;
 use nym_validator_client::client::IdentityKey;
 use nym_validator_client::nyxd::AccountId;
 use serde::Serialize;
-use std::fmt::Display;
+use std::fmt::{Debug, Display};
 use std::sync::Arc;
 use time::OffsetDateTime;
 use url::Url;
@@ -38,16 +38,23 @@ pub enum SelectedGateway {

 impl SelectedGateway {
    pub fn from_topology_node(
-        node: gateway::LegacyNode,
+        node: RoutingNode,
        must_use_tls: bool,
    ) -> Result<Self, ClientCoreError> {
+        // for now, let's use 'old' behaviour, if you want to change it, you can pass it up the enum stack yourself : )
+        let prefer_ipv6 = false;
+
        let gateway_listener = if must_use_tls {
-            node.clients_address_tls()
+            node.ws_entry_address_tls()
                .ok_or(ClientCoreError::UnsupportedWssProtocol {
                    gateway: node.identity_key.to_base58_string(),
                })?
        } else {
-            node.clients_address()
+            node.ws_entry_address(prefer_ipv6)
+                .ok_or(ClientCoreError::UnsupportedEntry {
+                    id: node.node_id,
+                    identity: node.identity_key.to_base58_string(),
+                })?
        };

        let gateway_listener =
@@ -200,7 +207,7 @@ pub enum GatewaySetup {
        specification: GatewaySelectionSpecification,

        // TODO: seems to be a bit inefficient to pass them by value
-        available_gateways: Vec<gateway::LegacyNode>,
+        available_gateways: Vec<RoutingNode>,
    },

    ReuseConnection {
@@ -214,6 +221,34 @@ pub enum GatewaySetup {
    },
 }

+impl Debug for GatewaySetup {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            GatewaySetup::MustLoad { gateway_id } => f
+                .debug_struct("GatewaySetup::MustLoad")
+                .field("gateway_id", gateway_id)
+                .finish(),
+            GatewaySetup::New {
+                specification,
+                available_gateways,
+            } => f
+                .debug_struct("GatewaySetup::New")
+                .field("specification", specification)
+                .field("available_gateways", available_gateways)
+                .field("gateways", specification)
+                .finish(),
+            GatewaySetup::ReuseConnection {
+                gateway_details, ..
+            } => f
+                .debug_struct("GatewaySetup::ReuseConnection")
+                .field("authenticated_ephemeral_client", &"***")
+                .field("gateway_details", gateway_details)
+                .field("client_keys", &"***")
+                .finish(),
+        }
+    }
+}
+
 impl GatewaySetup {
    pub fn try_reuse_connection(init_res: InitialisationResult) -> Result<Self, ClientCoreError> {
        if let Some(authenticated_ephemeral_client) = init_res.authenticated_ephemeral_client {
@@ -0,0 +1,44 @@
+use crate::error::ClientCoreError;
+
+use nym_http_api_client::HickoryDnsResolver;
+use tokio::net::TcpStream;
+use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
+use tungstenite::handshake::client::Response;
+use url::{Host, Url};
+
+use std::net::SocketAddr;
+
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) async fn connect_async(
+    endpoint: &str,
+) -> Result<(WebSocketStream<MaybeTlsStream<TcpStream>>, Response), ClientCoreError> {
+    let resolver = HickoryDnsResolver::default();
+    let uri = Url::parse(endpoint).map_err(|_| ClientCoreError::InvalidUrl(endpoint.to_owned()))?;
+    let port: u16 = uri.port_or_known_default().unwrap_or(443);
+
+    let host = uri
+        .host()
+        .ok_or(ClientCoreError::InvalidUrl(endpoint.to_owned()))?;
+
+    // Get address for tcp connection, if a domain is provided use our preferred resolver rather than
+    // the default std resolve
+    let sock_addrs: Vec<SocketAddr> = match host {
+        Host::Ipv4(addr) => vec![SocketAddr::new(addr.into(), port)],
+        Host::Ipv6(addr) => vec![SocketAddr::new(addr.into(), port)],
+        Host::Domain(domain) => {
+            // Do a DNS lookup for the domain using our custom DNS resolver
+            resolver
+                .resolve_str(domain)
+                .await?
+                .into_iter()
+                .map(|a| SocketAddr::new(a, port))
+                .collect()
+        }
+    };
+
+    let stream = TcpStream::connect(&sock_addrs[..]).await?;
+
+    tokio_tungstenite::client_async_tls(endpoint, stream)
+        .await
+        .map_err(Into::into)
+}
--- a/Show More
+++ b/Show More