feat: Endorsement Certificates

packages/synapse-core/src/utils/cert.ts

@@ -0,0 +1,150 @@
+import type { TypedDataToPrimitiveTypes } from 'abitype'
+import type { Account, Address, Chain, Client, Hex, Transport } from 'viem'
+import { bytesToBigInt, bytesToHex, concat, hexToBytes, numberToHex, recoverTypedDataAddress } from 'viem'
+import { signTypedData } from 'viem/actions'
+import { randU256 } from '../utils/rand.ts'
+
+export type Endorsement = {
+  /**
+   * Unique nonce to suport nonce based revocation.
+   */
+  nonce: bigint
+  /**
+   * This certificate becomes invalid after `notAfter` timestamp.
+   */
+  notAfter: bigint
+}
+
+export type SignedEndorsement = Endorsement & {
+  signature: Hex
+}
+
+export const EIP712Endorsement = {
+  Endorsement: [
+    { name: 'nonce', type: 'uint64' },
+    { name: 'notAfter', type: 'uint64' },
+    { name: 'providerId', type: 'uint256' },
+  ],
+} as const
+
+export type TypedEn = TypedDataToPrimitiveTypes<typeof EIP712Endorsement>['Endorsement']
+
+export type SignCertOptions = {
+  nonce?: bigint // uint64
+  notAfter: bigint // uint64
+  providerId: bigint
+} /**
+ * Signs a certificate that a provider is super good enough.
+ * @param client - The client to use to sign the message
+ * @param options - nonce (randomised if null), not after and who to sign it for
+ * @returns encoded certificate data abiEncodePacked([nonce, notAfter, signature]), the provider id is implicit by where it will get placed in registry.
+ */
+export async function signEndorsement(client: Client<Transport, Chain, Account>, options: SignCertOptions) {
+  const nonce = (options.nonce ?? randU256()) & 0xffffffffffffffffn
+  const signature = await signTypedData(client, {
+    account: client.account,
+    domain: {
+      name: 'Storage Endorsement',
+      version: '1',
+      chainId: client.chain.id,
+    },
+    types: EIP712Endorsement,
+    primaryType: 'Endorsement',
+    message: {
+      nonce: nonce,
+      notAfter: options.notAfter,
+      providerId: options.providerId,
+    },
+  })
+
+  // 16 because size is after hex encoding
+  const encodedNonce = numberToHex(nonce, { size: 8 })
+  const encodedNotAfter = numberToHex(options.notAfter, { size: 8 })
+
+  return concat([encodedNonce, encodedNotAfter, signature])
+}
+
+export async function decodeEndorsement(
+  providerId: bigint,
+  chainId: number | bigint | undefined,
+  hexData: Hex
+): Promise<{
+  address: Address | null
+  endorsement: SignedEndorsement
+}> {
+  if (hexData.length !== 164) {
+    return {
+      address: null,
+      endorsement: {
+        nonce: 0n,
+        notAfter: 0n,
+        signature: '0x',
+      },
+    }
+  }
+  const data = hexToBytes(hexData)
+  const endorsement: SignedEndorsement = {
+    nonce: bytesToBigInt(data.slice(0, 8)),
+    notAfter: bytesToBigInt(data.slice(8, 16)),
+    signature: bytesToHex(data.slice(16)),
+  }
+  const address = await recoverTypedDataAddress({
+    domain: {
+      name: 'Storage Endorsement',
+      version: '1',
+      chainId,
+    },
+    types: EIP712Endorsement,
+    primaryType: 'Endorsement',
+    message: {
+      nonce: endorsement.nonce,
+      notAfter: endorsement.notAfter,
+      providerId: providerId,
+    },
+    signature: endorsement.signature,
+  }).catch((reason) => {
+    console.warn('Failed to recover product endorsement:', reason)
+    return null
+  })
+  return { address, endorsement }
+}
+
+/**
+ * Validates endorsement capabilities, if any, filtering out invalid ones
+ * @returns mapping of valid endorsements to expiry, nonce, signature
+ */
+export async function decodeEndorsements(
+  providerId: bigint,
+  chainId: number | bigint,
+  capabilities: Record<string, Hex>
+): Promise<Record<Address, SignedEndorsement>> {
+  const now = Date.now() / 1000
+  return await Promise.all(
+    Object.values(capabilities).map((capabilityValue) => decodeEndorsement(providerId, chainId, capabilityValue))
+  ).then((results) =>
+    results.reduce(
+      (endorsements, { address, endorsement }) => {
+        if (address != null && endorsement.notAfter > now) {
+          endorsements[address] = endorsement
+        }
+        return endorsements
+      },
+      {} as Record<Address, SignedEndorsement>
+    )
+  )
+}
+
+/**
+ * @returns a list of capability keys and a list of capability values for the ServiceProviderRegistry
+ */
+export function encodeEndorsements(endorsements: Record<Address, SignedEndorsement>): [string[], Hex[]] {
+  const keys: string[] = []
+  const values: Hex[] = []
+  Object.values(endorsements).forEach((value, index) => {
+    keys.push(`endorsement${index.toString()}`)
+    values.push(
+      concat([numberToHex(value.nonce, { size: 8 }), numberToHex(value.notAfter, { size: 8 }), value.signature])
+    )
+  })
+  return [keys, values]
+}

packages/synapse-core/src/utils/index.ts

@@ -1,5 +1,6 @@
 export * from './calibration.ts'
 export * from './capabilities.ts'
+export * from './cert.ts'
 export * from './constants.ts'
 export * from './decode-pdp-errors.ts'
 export * from './format.ts'

packages/synapse-core/src/utils/pdp-capabilities.ts

@@ -2,6 +2,7 @@ import type { Hex } from 'viem'
 import { bytesToHex, hexToString, isHex, numberToBytes, stringToHex, toBytes } from 'viem'
 import type { PDPOffering } from '../warm-storage/providers.ts'
 import { decodeAddressCapability } from './capabilities.ts'
+import { decodeEndorsements, encodeEndorsements } from './cert.ts'
 
 // Standard capability keys for PDP product type (must match ServiceProviderRegistry.sol REQUIRED_PDP_KEYS)
 export const CAP_SERVICE_URL = 'serviceURL'
@@ -18,7 +19,11 @@ export const CAP_PAYMENT_TOKEN = 'paymentTokenAddress'
  * Decode PDP capabilities from keys/values arrays into a PDPOffering object.
  * Based on Curio's capabilitiesToOffering function.
  */
-export function decodePDPCapabilities(capabilities: Record<string, Hex>): PDPOffering {
+export async function decodePDPCapabilities(
+  providerId: bigint,
+  chainId: number | bigint,
+  capabilities: Record<string, Hex>
+): Promise<PDPOffering> {
   return {
     serviceURL: hexToString(capabilities.serviceURL),
     minPieceSizeInBytes: BigInt(capabilities.minPieceSizeInBytes),
@@ -29,6 +34,7 @@ export function decodePDPCapabilities(capabilities: Record<string, Hex>): PDPOff
     minProvingPeriodInEpochs: BigInt(capabilities.minProvingPeriodInEpochs),
     location: hexToString(capabilities.location),
     paymentTokenAddress: decodeAddressCapability(capabilities.paymentTokenAddress),
+    endorsements: await decodeEndorsements(providerId, chainId, capabilities),
   }
 }
 
@@ -62,6 +68,12 @@ export function encodePDPCapabilities(
   capabilityKeys.push(CAP_PAYMENT_TOKEN)
   capabilityValues.push(pdpOffering.paymentTokenAddress)
 
+  if (pdpOffering.endorsements != null) {
+    const [endorsementKeys, endorsementValues] = encodeEndorsements(pdpOffering.endorsements)
+    capabilityKeys.push(...endorsementKeys)
+    capabilityValues.push(...endorsementValues)
+  }
+
   if (capabilities != null) {
     for (const [key, value] of Object.entries(capabilities)) {
       capabilityKeys.push(key)

packages/synapse-core/src/warm-storage/data-sets.ts

@@ -99,7 +99,9 @@ export async function getDataSets(client: Client<Transport, Chain>, options: Get
       ],
     })
     // getProviderWithProduct returns {providerId, providerInfo, product, productCapabilityValues}
-    const pdpCaps = decodePDPCapabilities(
+    const pdpCaps = await decodePDPCapabilities(
+      dataSet.providerId,
+      client.chain.id,
       capabilitiesListToObject(pdpOffering.product.capabilityKeys, pdpOffering.productCapabilityValues)
     )
 
@@ -178,7 +180,9 @@ export async function getDataSet(client: Client<Transport, Chain>, options: GetD
   })
 
   // getProviderWithProduct returns {providerId, providerInfo, product, productCapabilityValues}
-  const pdpCaps = decodePDPCapabilities(
+  const pdpCaps = await decodePDPCapabilities(
+    dataSet.providerId,
+    client.chain.id,
     capabilitiesListToObject(pdpOffering.product.capabilityKeys, pdpOffering.productCapabilityValues)
   )
 

packages/synapse-core/src/warm-storage/providers.ts

@@ -1,9 +1,10 @@
 import type { AbiParametersToPrimitiveTypes, ExtractAbiFunction } from 'abitype'
-import type { Chain, Client, Hex, Transport } from 'viem'
+import type { Address, Chain, Client, Hex, Transport } from 'viem'
 import { readContract } from 'viem/actions'
 import type * as Abis from '../abis/index.ts'
 import { getChain } from '../chains.ts'
 import { capabilitiesListToObject } from '../utils/capabilities.ts'
+import type { SignedEndorsement } from '../utils/cert.ts'
 import { decodePDPCapabilities } from '../utils/pdp-capabilities.ts'
 
 export type getProviderType = ExtractAbiFunction<typeof Abis.serviceProviderRegistry, 'getProvider'>
@@ -23,6 +24,7 @@ export interface PDPOffering {
   minProvingPeriodInEpochs: bigint
   location: string
   paymentTokenAddress: Hex
+  endorsements?: Record<Address, SignedEndorsement>
 }
 
 export interface PDPProvider extends ServiceProviderInfo {
@@ -59,7 +61,9 @@ export async function readProviders(client: Client<Transport, Chain>): Promise<P
       providers.push({
         id: provider.providerId,
         ...provider.providerInfo,
-        pdp: decodePDPCapabilities(
+        pdp: await decodePDPCapabilities(
+          provider.providerId,
+          client.chain.id,
           capabilitiesListToObject(provider.product.capabilityKeys, provider.productCapabilityValues)
         ),
       })
@@ -83,7 +87,9 @@ export async function getProvider(client: Client<Transport, Chain>, options: Get
   return {
     id: provider.providerId,
     ...provider.providerInfo,
-    pdp: decodePDPCapabilities(
+    pdp: await decodePDPCapabilities(
+      provider.providerId,
+      client.chain.id,
       capabilitiesListToObject(provider.product.capabilityKeys, provider.productCapabilityValues)
     ),
   }

packages/synapse-core/test/cert.test.ts

@@ -0,0 +1,40 @@
+import assert from 'assert'
+
+import type { Account, Chain, Client, Transport } from 'viem'
+import { createWalletClient, http } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { calibration } from '../src/chains.ts'
+import { decodeEndorsement, encodeEndorsements, signEndorsement } from '../src/utils/cert.ts'
+
+describe('Endorsement Certificates', () => {
+  let client: Client<Transport, Chain, Account>
+  beforeEach(async () => {
+    client = createWalletClient({
+      account: privateKeyToAccount(generatePrivateKey()),
+      transport: http(),
+      chain: calibration,
+    })
+  })
+
+  it('should decode from the signed encoding the same account that signed', async () => {
+    const providerId = 10n
+    const notAfter = 0xffffffffffffffffn
+    const encoded = await signEndorsement(client, {
+      notAfter,
+      providerId,
+    })
+    assert.equal(encoded.length, 164)
+
+    const { address, endorsement } = await decodeEndorsement(providerId, client.chain.id, encoded)
+    assert.equal(address, client.account.address)
+    assert.equal(endorsement.notAfter, notAfter)
+
+    const [keys, values] = encodeEndorsements({
+      [address ?? '']: endorsement,
+    })
+    assert.equal(keys.length, values.length)
+    assert.equal(keys.length, 1)
+    assert.equal(values.length, 1)
+    assert.equal(values[0], encoded)
+  })
+})

packages/synapse-core/tools/endorse-sp.js

@@ -0,0 +1,63 @@
+import { createWalletClient, http } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { getChain } from '../src/chains.ts'
+import { signEndorsement } from '../src/utils/cert.ts'
+
+function printUsageAndExit() {
+  console.error('Usage: PRIVATE_KEY=0x... node utils/endorse-sp.js providerId...')
+  process.exit(1)
+}
+
+const PRIVATE_KEY = process.env.PRIVATE_KEY
+const ETH_RPC_URL = process.env.ETH_RPC_URL || 'https://api.calibration.node.glif.io/rpc/v1'
+const EXPIRY = process.env.EXPIRY || BigInt(Math.floor(Date.now() / 1000)) + 10368000n
+
+if (!PRIVATE_KEY) {
+  console.error('ERROR: PRIVATE_KEY environment variable is required')
+  printUsageAndExit()
+}
+
+let CHAIN_ID = process.env.CHAIN_ID
+
+// TODO also support providerAddress and serviceURL
+const providerIds = process.argv.slice(2)
+if (providerIds.length === 0) {
+  console.error('ERROR: must specify at least one providerId')
+  printUsageAndExit()
+}
+
+async function main() {
+  if (CHAIN_ID == null) {
+    console.log('fetching eth_chainId from', ETH_RPC_URL)
+    const response = await fetch(ETH_RPC_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        id: 1,
+        method: 'eth_chainId',
+        params: [],
+      }),
+    })
+    const result = await response.json()
+    CHAIN_ID = result.result
+  }
+  console.log('ChainId:', Number(CHAIN_ID))
+  const client = createWalletClient({
+    account: privateKeyToAccount(PRIVATE_KEY),
+    transport: http(ETH_RPC_URL),
+    chain: getChain(Number(CHAIN_ID)),
+  })
+  console.log('Expiry:', new Date(Number(EXPIRY) * 1000).toDateString())
+  for (const providerId of providerIds) {
+    const encoded = await signEndorsement(client, {
+      providerId,
+      notAfter: EXPIRY,
+    })
+    console.log('Provider:', providerId)
+    console.log('Endorsement:', encoded)
+  }
+}
+
+main().catch(console.error)

packages/synapse-sdk/package.json

@@ -132,6 +132,7 @@
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.9.1",
+    "@types/sinon": "^20.0.0",
     "@wagmi/cli": "^2.7.0",
     "abitype": "^1.1.1",
     "chai": "^6.2.0",
@@ -140,6 +141,7 @@
     "msw": "~2.10.5",
     "p-defer": "^4.0.1",
     "playwright-test": "^14.1.12",
+    "sinon": "^21.0.0",
     "type-fest": "^5.1.0",
     "typescript": "5.9.3"
   },