feat!: breaking out readState into signed and unsigned (#1000)

Co-authored-by: Luca Bertelli <luca.bertelli@dfinity.org>
Co-authored-by: Nathan Mc Grath <contact@nathanos.dev>

Author: 3 people

docs/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Changed
 
+- feat!: changes polling strategy for `read_state` requests to support presigned requests. By default, `read_state` requests will create a new signature with a new ingress expiry each time they are made. However, the new `preSignReadStateRequest` will make one signature and use it for all polling requests. This is useful for hardware wallets or other external signing solutions that make signing cumbersome.
+  - pollForResponse now moves `strategy`, `request`, and `preSignReadStateRequest` to the `options: PollingOptions` object
+  - new export: `PollingOptions` type
+  - Actor also includes a `pollingOptions` object that can be passed to the `actor` function and will be passed to the `pollForResponse` method
 - feat!: removes the unused `defaultAgent` global concept and the `getDefaultAgent` function. The `HttpAgent` constructor is now the only way to create an agent.
 - feat!: removes the `ProxyAgent` class.
 - chore: formatting files and changelog

e2e/node/basic/basic.test.ts

@@ -3,7 +3,9 @@ import {
   Certificate,
   LookupResultFound,
   LookupStatus,
+  bufFromBufLike,
   getManagementCanister,
+  strToUtf8,
 } from '@dfinity/agent';
 import { IDL } from '@dfinity/candid';
 import { Principal } from '@dfinity/principal';
@@ -15,8 +17,8 @@ import { test, expect } from 'vitest';
  * @returns the default effective canister id
  */
 export async function getDefaultEffectiveCanisterId() {
-  const res = await fetch('http://localhost:4943/_/topology'); //?
-  const data = await res.json(); //?
+  const res = await fetch('http://localhost:4943/_/topology');
+  const data = await res.json();
   const id = data['default_effective_canister_id']['canister_id'];
   // decode from base64
   const decoded = Buffer.from(id, 'base64').toString('hex');
@@ -39,7 +41,7 @@ test('read_state', async () => {
   const ecid = await getDefaultEffectiveCanisterId();
   const resolvedAgent = await agent;
   const now = Date.now() / 1000;
-  const path = [new TextEncoder().encode('time')];
+  const path = [strToUtf8('time')];
   const response = await resolvedAgent.readState(ecid, {
     paths: [path],
   });
@@ -49,7 +51,7 @@ test('read_state', async () => {
     rootKey: resolvedAgent.rootKey,
     canisterId: ecid,
   });
-  expect(cert.lookup([new TextEncoder().encode('Time')])).toEqual({
+  expect(cert.lookup([strToUtf8('Time')])).toEqual({
     status: LookupStatus.Unknown,
   });
 
@@ -63,10 +65,12 @@ test('read_state', async () => {
 
   const decoded = IDL.decode(
     [IDL.Nat],
-    new Uint8Array([
-      ...new TextEncoder().encode('DIDL\x00\x01\x7d'),
-      ...(new Uint8Array(rawTime.value) || []),
-    ]),
+    bufFromBufLike(
+      new Uint8Array([
+        ...new TextEncoder().encode('DIDL\x00\x01\x7d'),
+        ...(new Uint8Array(rawTime.value) || []),
+      ]),
+    ),
   )[0];
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const time = Number(decoded as any) / 1e9;
@@ -77,24 +81,17 @@ test('read_state', async () => {
 test('read_state with passed request', async () => {
   const resolvedAgent = await agent;
   const now = Date.now() / 1000;
-  const path = [new TextEncoder().encode('time')];
+  const path = [strToUtf8('time')];
   const canisterId = await getDefaultEffectiveCanisterId();
   const request = await resolvedAgent.createReadStateRequest({ paths: [path] });
-  const response = await resolvedAgent.readState(
-    canisterId,
-    {
-      paths: [path],
-    },
-    undefined,
-    request,
-  );
+  const response = await resolvedAgent.readState(canisterId, { paths: [path] }, undefined, request);
   if (resolvedAgent.rootKey == null) throw new Error(`The agent doesn't have a root key yet`);
   const cert = await Certificate.create({
     certificate: response.certificate,
     rootKey: resolvedAgent.rootKey,
     canisterId: canisterId,
   });
-  expect(cert.lookup([new TextEncoder().encode('Time')])).toEqual({
+  expect(cert.lookup([strToUtf8('Time')])).toEqual({
     status: LookupStatus.Unknown,
   });
 
@@ -108,10 +105,12 @@ test('read_state with passed request', async () => {
 
   const decoded = IDL.decode(
     [IDL.Nat],
-    new Uint8Array([
-      ...new TextEncoder().encode('DIDL\x00\x01\x7d'),
-      ...(new Uint8Array(rawTime.value) || []),
-    ]),
+    bufFromBufLike(
+      new Uint8Array([
+        ...new TextEncoder().encode('DIDL\x00\x01\x7d'),
+        ...(new Uint8Array(rawTime.value) || []),
+      ]),
+    ),
   )[0];
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const time = Number(decoded as any) / 1e9;

e2e/node/basic/counter.test.ts

@@ -1,4 +1,4 @@
-import { Actor, HttpAgent } from '@dfinity/agent';
+import { Actor, HttpAgent, ActorMethod } from '@dfinity/agent';
 import counterCanister, { idl } from '../canisters/counter';
 import { it, expect, describe, vi } from 'vitest';
 
@@ -34,7 +34,71 @@ describe('counter', () => {
       expected += 1;
     }
   }, 40000);
+
+  it('should work with preSignReadStateRequest enabled', async () => {
+    const { canisterId } = await counterCanister();
+
+    // Create counter actor with preSignReadStateRequest enabled
+    const counter = await Actor.createActor(idl, {
+      canisterId,
+      agent: await HttpAgent.create({
+        host: 'http://localhost:4943',
+        shouldFetchRootKey: true,
+      }),
+      pollingOptions: {
+        preSignReadStateRequest: true,
+      },
+    });
+
+    // Reset counter to 0
+    await counter.write(0);
+    expect(Number(await counter.read())).toEqual(0);
+
+    // Call inc_read which will trigger polling and use preSignReadStateRequest
+    const result = Number(await counter.inc_read());
+
+    // Verify the operation was successful
+    expect(result).toEqual(1);
+
+    // Verify the state was actually updated
+    expect(Number(await counter.read())).toEqual(1);
+  }, 40000);
+
+  it('should allow method-specific pollingOptions override', async () => {
+    const { canisterId } = await counterCanister();
+
+    // Create counter actor without preSignReadStateRequest
+    const counter = await Actor.createActor(idl, {
+      canisterId,
+      agent: await HttpAgent.create({
+        host: 'http://localhost:4943',
+        shouldFetchRootKey: true,
+      }),
+    });
+
+    // Reset counter to 0
+    await counter.write(0);
+    expect(Number(await counter.read())).toEqual(0);
+
+    // Use withOptions to set preSignReadStateRequest for this specific call
+    const result = Number(
+      await (counter.inc_read as ActorMethod).withOptions({
+        pollingOptions: {
+          preSignReadStateRequest: true,
+          // Custom polling strategy with simple 1-second delay
+          strategy: () => new Promise(resolve => setTimeout(resolve, 1000)),
+        },
+      })(),
+    );
+
+    // Verify the operation was successful
+    expect(result).toEqual(1);
+
+    // Verify the state was actually updated
+    expect(Number(await counter.read())).toEqual(1);
+  }, 40000);
 });
+
 describe('retrytimes', () => {
   it('should retry after a failure', async () => {
     let count = 0;

e2e/node/package.json

@@ -37,7 +37,7 @@
     "size-limit": "^8.2.6",
     "text-encoding": "^0.7.0",
     "ts-node": "^10.8.2",
-    "typescript": "^5.2.2",
+    "typescript": "^5.7.2",
     "vitest": "^3.0.8"
   },
   "optionalDependencies": {