fix: align charge module with draft-stellar-charge-00 spec (#25)

## What

- Switch network identifiers to CAIP-2 format (`stellar:testnet` / `stellar:pubnet`) in `methodDetails.network` and credential `source` field; add `CAIP2_NETWORK` / `CAIP2_TO_NETWORK` constants exported from root index
- Remove `reference` and `memo` fields from `methodDetails` schema
- Move `source` (DID-PKH) from inside `payload` to the top-level credential field
- Add `SettlementError` (exported) to distinguish broadcast/confirmation failures from verification errors
- Add server-side validation for spec gaps:
  - Exactly one `invokeHostFunction` operation
  - Auth entries must not contain sub-invocations
  - Auth entry expiration must not exceed `challenge.expires`
  - Server address must not appear in auth entries or simulation transfer events
  - `timeBounds.maxTime` must not exceed `challenge.expires` on unsponsored path
  - Pre-submission simulation with CAP-46 transfer event validation
  - SettlementError for broadcast and confirmation failures
- Derive ledger expiration from `challenge.expires` instead of a fixed timeout
- Add `DEFAULT_LEDGER_CLOSE_TIME` and `DEFAULT_CHALLENGE_EXPIRY` constants

## Why

The charge module had several gaps relative to `draft-stellar-charge-00`. This PR closes them to improve interoperability and security: CAIP-2 is the spec's standard chain reference format; the DID-PKH `source` must be a top-level credential field (the `mppx` `Credential` type already modeled this correctly but the client was placing it inside `payload`); the server must validate transaction structure and auth entries before broadcasting to prevent abuse.

Author: marcelosalloum

sdk/src/channel/server/Channel.ts

@@ -96,30 +96,31 @@ describe('Methods.charge', () => {
     expect(result.externalId).toBe('order-123')
   })
 
-  it('request schema accepts methodDetails with reference', () => {
+  it('request schema accepts methodDetails with network and feePayer', () => {
     const result = Methods.charge.schema.request.parse({
       amount: '100000',
       currency: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
       recipient: 'GBXYZ',
       methodDetails: {
-        reference: 'abc-123',
-        network: 'testnet',
+        network: 'stellar:testnet',
+        feePayer: true,
       },
     })
-    expect(result.methodDetails?.reference).toBe('abc-123')
-    expect(result.methodDetails?.network).toBe('testnet')
+    expect(result.methodDetails?.network).toBe('stellar:testnet')
+    expect(result.methodDetails?.feePayer).toBe(true)
   })
 
-  it('request schema accepts methodDetails with feePayer', () => {
+  it('request schema accepts methodDetails with network only', () => {
     const result = Methods.charge.schema.request.parse({
       amount: '100000',
       currency: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
       recipient: 'GBXYZ',
       methodDetails: {
-        feePayer: true,
+        network: 'stellar:pubnet',
       },
     })
-    expect(result.methodDetails?.feePayer).toBe(true)
+    expect(result.methodDetails?.network).toBe('stellar:pubnet')
+    expect(result.methodDetails?.feePayer).toBeUndefined()
   })
 
   it('request schema allows omitting methodDetails', () => {
@@ -137,7 +138,9 @@ describe('Methods.charge', () => {
       hash: 'abc123',
     })
     expect(result.type).toBe('hash')
-    expect(result.hash).toBe('abc123')
+    if (result.type === 'hash') {
+      expect(result.hash).toBe('abc123')
+    }
   })
 
   it('credential payload accepts transaction type (pull)', () => {
@@ -146,6 +149,8 @@ describe('Methods.charge', () => {
       transaction: 'AAAA...',
     })
     expect(result.type).toBe('transaction')
-    expect(result.transaction).toBe('AAAA...')
+    if (result.type === 'transaction') {
+      expect(result.transaction).toBe('AAAA...')
+    }
   })
 })

sdk/src/charge/Methods.test.ts

@@ -37,15 +37,11 @@ export const charge = Method.from({
       description: z.optional(z.string()),
       /** Merchant-provided reconciliation ID (e.g. order ID, invoice number). */
       externalId: z.optional(z.string()),
-      /** Method-specific details injected by the server. */
+      /** Method-specific details injected by the server via request(). */
       methodDetails: z.optional(
         z.object({
-          /** Server-generated unique tracking ID. */
-          reference: z.optional(z.string()),
-          /** Stellar network identifier ("public" | "testnet"). */
-          network: z.optional(z.string()),
-          /** Optional memo text to attach to the transaction. */
-          memo: z.optional(z.string()),
+          /** CAIP-2 network identifier (e.g. "stellar:testnet", "stellar:pubnet"). */
+          network: z.string(),
           /** Whether the server will sponsor transaction fees. */
           feePayer: z.optional(z.boolean()),
         }),

sdk/src/charge/Methods.ts

@@ -1,6 +1,7 @@
 import { Keypair } from '@stellar/stellar-sdk'
 import { describe, expect, it } from 'vitest'
 import { charge } from './Charge.js'
+import { CAIP2_TO_NETWORK } from '../../constants.js'
 
 const TEST_KEYPAIR = Keypair.random()
 
@@ -55,4 +56,42 @@ describe('stellar client charge', () => {
     const method = charge({ keypair: TEST_KEYPAIR, mode: 'push' })
     expect(method.name).toBe('stellar')
   })
+
+  it('throws when neither keypair nor secretKey is provided', () => {
+    expect(() => charge({} as any)).toThrow('Either keypair or secretKey must be provided')
+  })
+})
+
+describe('CAIP-2 network mapping', () => {
+  it('maps stellar:testnet to testnet', () => {
+    expect(CAIP2_TO_NETWORK['stellar:testnet']).toBe('testnet')
+  })
+
+  it('maps stellar:pubnet to public', () => {
+    expect(CAIP2_TO_NETWORK['stellar:pubnet']).toBe('public')
+  })
+
+  it('returns undefined for unknown CAIP-2 identifiers', () => {
+    expect(CAIP2_TO_NETWORK['stellar:unknown']).toBeUndefined()
+  })
+})
+
+describe('DID-PKH format', () => {
+  it('constructs correct DID-PKH from CAIP-2 network and public key', () => {
+    const kp = Keypair.random()
+    const caip2Network = 'stellar:testnet'
+    const caip2Component = caip2Network.split(':')[1] ?? 'testnet'
+    const source = `did:pkh:stellar:${caip2Component}:${kp.publicKey()}`
+
+    expect(source).toMatch(/^did:pkh:stellar:testnet:G[A-Z0-9]{55}$/)
+  })
+
+  it('uses pubnet component for mainnet', () => {
+    const kp = Keypair.random()
+    const caip2Network = 'stellar:pubnet'
+    const caip2Component = caip2Network.split(':')[1] ?? 'testnet'
+    const source = `did:pkh:stellar:${caip2Component}:${kp.publicKey()}`
+
+    expect(source).toMatch(/^did:pkh:stellar:pubnet:G[A-Z0-9]{55}$/)
+  })
 })

sdk/src/charge/client/Charge.test.ts

@@ -4,7 +4,6 @@ import {
   BASE_FEE,
   Contract,
   Keypair,
-  Memo,
   TransactionBuilder,
   authorizeEntry,
   nativeToScVal,
@@ -15,7 +14,9 @@ import { Credential, Method } from 'mppx'
 import { z } from 'zod/mini'
 import {
   ALL_ZEROS,
+  CAIP2_TO_NETWORK,
   DEFAULT_DECIMALS,
+  DEFAULT_LEDGER_CLOSE_TIME,
   DEFAULT_TIMEOUT,
   NETWORK_PASSPHRASE,
   SOROBAN_RPC_URLS,
@@ -85,8 +86,10 @@ export function charge(parameters: charge.Parameters) {
     async createCredential({ challenge, context }) {
       const { request } = challenge
       const { amount, currency, recipient } = request
-      const network: NetworkId = (request.methodDetails?.network as NetworkId) ?? 'testnet'
-      const memo = request.methodDetails?.memo as string | undefined
+
+      const caip2Network = request.methodDetails?.network ?? 'stellar:testnet'
+      const network: NetworkId = CAIP2_TO_NETWORK[caip2Network] ?? 'testnet'
+
       onProgress?.({
         type: 'challenge',
         recipient,
@@ -112,6 +115,10 @@ export function charge(parameters: charge.Parameters) {
         )
       }
 
+      const expiresTimestamp: number | undefined = challenge.expires
+        ? Math.floor(new Date(challenge.expires).getTime() / 1000)
+        : undefined
+
       if (isServerSponsored) {
         // ── Spec-compliant sponsored path ──────────────────────────────────
         // Client uses an all-zeros source account so the server can swap in
@@ -128,20 +135,27 @@ export function charge(parameters: charge.Parameters) {
         const sponsoredBuilder = new TransactionBuilder(placeholderSource, {
           fee: BASE_FEE,
           networkPassphrase,
-        })
-          .addOperation(transferOp)
-          .setTimeout(timeout)
+        }).addOperation(transferOp)
 
-        if (memo) {
-          sponsoredBuilder.addMemo(Memo.text(memo))
+        if (expiresTimestamp) {
+          sponsoredBuilder.setTimebounds(0, expiresTimestamp)
+        } else {
+          sponsoredBuilder.setTimeout(timeout)
         }
 
         const unsignedTx = sponsoredBuilder.build()
         const prepared = await server.prepareTransaction(unsignedTx)
 
-        // Determine auth-entry expiry from the current ledger sequence
         const latestLedger = await server.getLatestLedger()
-        const validUntilLedger = latestLedger.sequence + Math.ceil(timeout / 5) + 10
+        let validUntilLedger: number
+        if (expiresTimestamp) {
+          const nowSecs = Math.floor(Date.now() / 1000)
+          const secsUntilExpiry = Math.max(expiresTimestamp - nowSecs, 0)
+          validUntilLedger =
+            latestLedger.sequence + Math.ceil(secsUntilExpiry / DEFAULT_LEDGER_CLOSE_TIME)
+        } else {
+          validUntilLedger = latestLedger.sequence + Math.ceil(timeout / 5) + 10
+        }
 
         onProgress?.({ type: 'signing' })
 
@@ -173,9 +187,13 @@ export function charge(parameters: charge.Parameters) {
         const signedXdr = prepared.toEnvelope().toXDR('base64')
         onProgress?.({ type: 'signed', transaction: signedXdr })
 
+        const didComponent = network === 'public' ? 'pubnet' : network
+        const source = `did:pkh:stellar:${didComponent}:${keypair.publicKey()}`
+
         return Credential.serialize({
           challenge,
           payload: { type: 'transaction' as const, transaction: signedXdr },
+          source,
         })
       }
 
@@ -194,12 +212,12 @@ export function charge(parameters: charge.Parameters) {
       const builder = new TransactionBuilder(sourceAccount, {
         fee: BASE_FEE,
         networkPassphrase,
-      })
-        .addOperation(transferOp)
-        .setTimeout(timeout)
+      }).addOperation(transferOp)
 
-      if (memo) {
-        builder.addMemo(Memo.text(memo))
+      if (expiresTimestamp) {
+        builder.setTimebounds(0, expiresTimestamp)
+      } else {
+        builder.setTimeout(timeout)
       }
 
       const transaction = builder.build()
@@ -213,6 +231,9 @@ export function charge(parameters: charge.Parameters) {
       const signedXdr = prepared.toXDR()
       onProgress?.({ type: 'signed', transaction: signedXdr })
 
+      const didComponent = network === 'public' ? 'pubnet' : network
+      const source = `did:pkh:stellar:${didComponent}:${keypair.publicKey()}`
+
       if (effectiveMode === 'push') {
         // Client broadcasts
         onProgress?.({ type: 'paying' })
@@ -231,13 +252,15 @@ export function charge(parameters: charge.Parameters) {
         return Credential.serialize({
           challenge,
           payload: { type: 'hash' as const, hash: result.hash },
+          source,
         })
       }
 
       // Pull mode: send signed XDR for server to broadcast
       return Credential.serialize({
         challenge,
         payload: { type: 'transaction' as const, transaction: signedXdr },
+        source,
       })
     },
   })

sdk/src/charge/client/Charge.ts

@@ -21,8 +21,7 @@ function mockChallenge(overrides: Record<string, unknown> = {}) {
       currency: USDC_SAC_TESTNET,
       recipient: RECIPIENT.publicKey(),
       methodDetails: {
-        reference: crypto.randomUUID(),
-        network: 'testnet',
+        network: 'stellar:testnet',
       },
       ...overrides,
     },
@@ -121,3 +120,88 @@ describe('credential type validation', () => {
     expect(serialized).toContain('Payment')
   })
 })
+
+describe('spec compliance: credential structure', () => {
+  it('source is a top-level credential field, not inside payload', () => {
+    const challenge = mockChallenge()
+    const source = `did:pkh:stellar:testnet:${SENDER.publicKey()}`
+
+    const serialized = Credential.serialize({
+      challenge,
+      payload: { type: 'transaction' as const, transaction: 'AAAA' },
+      source,
+    })
+
+    const deserialized = Credential.deserialize(serialized)
+
+    expect(deserialized.source).toBe(source)
+
+    const payload = deserialized.payload as Record<string, unknown>
+    expect(payload.source).toBeUndefined()
+  })
+
+  it('source roundtrips through serialize/deserialize for hash type', () => {
+    const challenge = mockChallenge()
+    const source = `did:pkh:stellar:testnet:${SENDER.publicKey()}`
+
+    const serialized = Credential.serialize({
+      challenge,
+      payload: { type: 'hash' as const, hash: 'tx-hash-abc' },
+      source,
+    })
+
+    const deserialized = Credential.deserialize(serialized)
+    expect(deserialized.source).toBe(source)
+
+    const payload = deserialized.payload as Record<string, unknown>
+    expect(payload.source).toBeUndefined()
+    expect(payload.type).toBe('hash')
+    expect(payload.hash).toBe('tx-hash-abc')
+  })
+
+  it('credential without source omits the field entirely', () => {
+    const challenge = mockChallenge()
+
+    const serialized = Credential.serialize({
+      challenge,
+      payload: { type: 'transaction' as const, transaction: 'AAAA' },
+    })
+
+    const deserialized = Credential.deserialize(serialized)
+    expect(deserialized.source).toBeUndefined()
+  })
+
+  it('source follows DID-PKH format for Stellar', () => {
+    const kp = Keypair.random()
+    const source = `did:pkh:stellar:testnet:${kp.publicKey()}`
+
+    expect(source).toMatch(/^did:pkh:stellar:(testnet|pubnet):G[A-Z2-7]{55}$/)
+  })
+
+  it('payload.type discriminator is preserved without source contamination', () => {
+    const challenge = mockChallenge()
+    const source = `did:pkh:stellar:testnet:${SENDER.publicKey()}`
+
+    const txSerialized = Credential.serialize({
+      challenge,
+      payload: { type: 'transaction' as const, transaction: 'AAAA' },
+      source,
+    })
+    const txDeserialized = Credential.deserialize(txSerialized)
+    const txPayload = txDeserialized.payload as { type: string; transaction?: string }
+    expect(txPayload.type).toBe('transaction')
+    expect(txPayload.transaction).toBe('AAAA')
+    expect(Object.keys(txPayload).sort()).toEqual(['transaction', 'type'])
+
+    const hashSerialized = Credential.serialize({
+      challenge,
+      payload: { type: 'hash' as const, hash: 'deadbeef' },
+      source,
+    })
+    const hashDeserialized = Credential.deserialize(hashSerialized)
+    const hashPayload = hashDeserialized.payload as { type: string; hash?: string }
+    expect(hashPayload.type).toBe('hash')
+    expect(hashPayload.hash).toBe('deadbeef')
+    expect(Object.keys(hashPayload).sort()).toEqual(['hash', 'type'])
+  })
+})