docs: add draft-stellar-charge-00 spec references (#35)

## What
Reference
[draft-stellar-charge-00](https://paymentauth.org/draft-stellar-charge-00)
in `README.md`, `sdk/src/charge/Methods.ts`,
`sdk/src/charge/client/Charge.ts`, `sdk/src/charge/server/Charge.ts`,
and update `diagrams/charge-flow.md` for spec compliance.

## Why
The SDK implements draft-stellar-charge-00 but lacked direct references
to the spec. Adding links helps contributors and consumers trace
behavior back to the normative source. The diagram fixes bring the flow
visualization in line with the spec's requirements.

Author: marcelosalloum

README.md

@@ -2,6 +2,10 @@
 
 Stellar blockchain payment method for the [Machine Payments Protocol (MPP)](https://mpp.dev). Enables machine-to-machine payments using Soroban SAC token transfers on the Stellar network, with optional support for [one-way payment channels](https://github.com/stellar-experimental/one-way-channel) for high-frequency off-chain payments.
 
+## Specification
+
+The charge payment mode implements the [draft-stellar-charge-00](https://paymentauth.org/draft-stellar-charge-00) specification ([source](https://github.com/tempoxyz/mpp-specs/blob/main/specs/methods/stellar/draft-stellar-charge-00.md)), which defines the `stellar` payment method with a `charge` intent for one-time SEP-41 token transfers under the HTTP Payment Authentication scheme.
+
 ## Payment modes
 
 ### Charge (one-time transfers)

diagrams/charge-flow.md

@@ -1,5 +1,7 @@
 # Charge Payment Flow — On-Chain SAC Transfer
 
+> Implements [draft-stellar-charge-00](https://paymentauth.org/draft-stellar-charge-00)
+
 ```mermaid
 sequenceDiagram
     participant App as Client App
@@ -32,8 +34,13 @@ sequenceDiagram
         SC->>RPC: getAccount(feePayerKey)
         RPC-->>SC: Server account with current sequence
         SC->>SC: Rebuild TX with feePayer as source<br/>copy XDR ops + sorobanData + memo/timebounds
+        SC->>RPC: simulateTransaction(rebuiltTx)
+        RPC-->>SC: Verify transfer events match challenge
         SC->>SC: feePayerKeypair.sign(rebuiltTx)
-        SC->>RPC: sendTransaction(rebuiltTx)
+        opt feeBumpSigner configured
+            SC->>SC: Wrap in FeeBumpTransaction (submissionTx)
+        end
+        SC->>RPC: sendTransaction(submissionTx)
         RPC->>Chain: Broadcast
         SC->>RPC: Poll getTransaction(hash)
         RPC-->>SC: TX confirmed
@@ -45,10 +52,9 @@ sequenceDiagram
         CC-->>App: Credential {type:'transaction', transaction: xdr}
         App->>SC: Credential with fully-signed XDR
         SC->>SC: verifySacInvocation(tx) — validate structure
-        opt feePayer configured but source is not all-zeros
-            SC->>SC: Wrap in FeeBump transaction (compatibility fallback)
-        end
-        SC->>RPC: sendTransaction(signedTx)
+        SC->>RPC: simulateTransaction(signedTx)
+        RPC-->>SC: Verify transfer events match challenge
+        SC->>RPC: sendTransaction(signedTx as-is)
         RPC->>Chain: Broadcast
         SC->>RPC: Poll getTransaction(hash)
         RPC-->>SC: TX confirmed
@@ -61,7 +67,7 @@ sequenceDiagram
         RPC->>Chain: Broadcast
         CC->>RPC: Poll getTransaction(hash)
         RPC-->>CC: TX confirmed
-        CC-->>App: Credential {type:'signature', hash}
+        CC-->>App: Credential {type:'hash', hash}
         App->>SC: Credential with tx hash
         SC->>RPC: getTransaction(hash)
         RPC-->>SC: TX result

sdk/src/channel/server/Channel.test.ts

@@ -10,6 +10,7 @@ const mockSendTransaction = vi.fn()
 const mockGetTransaction = vi.fn()
 const mockPrepareTransaction = vi.fn()
 const mockFromXDR = vi.fn()
+const mockWrapFeeBump = vi.fn()
 
 vi.mock('@stellar/stellar-sdk', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@stellar/stellar-sdk')>()
@@ -42,6 +43,10 @@ vi.mock('./State.js', () => ({
   getChannelState: (...args: unknown[]) => mockGetChannelState(...args),
 }))
 
+vi.mock('../../shared/fee-bump.js', () => ({
+  wrapFeeBump: (...args: unknown[]) => mockWrapFeeBump(...args),
+}))
+
 // Re-import after mock is set up
 const { channel } = await import('./Channel.js')
 
@@ -1037,4 +1042,53 @@ describe('close()', () => {
       }),
     ).rejects.toThrow(/failed/i)
   })
+
+  it('wraps in FeeBumpTransaction when feeBumpSigner is provided', async () => {
+    const signer = Keypair.random()
+    const feeBumpSigner = Keypair.random()
+    const signature = new Uint8Array(64).fill(5)
+    const fakeBumpTx = { isBumped: true }
+
+    mockGetAccount.mockResolvedValueOnce(new Account(signer.publicKey(), '104'))
+    mockPrepareTransaction.mockImplementationOnce((tx: any) => tx)
+    mockWrapFeeBump.mockReturnValueOnce(fakeBumpTx)
+    mockSendTransaction.mockResolvedValueOnce({ hash: 'bump-hash', status: 'PENDING' })
+    mockGetTransaction.mockResolvedValueOnce({ status: 'SUCCESS' })
+
+    const hash = await closeFn({
+      channel: CHANNEL_ADDRESS,
+      amount: 5000000n,
+      signature,
+      feePayer: { envelopeSigner: signer, feeBumpSigner },
+      network: 'stellar:testnet',
+    })
+
+    expect(hash).toBe('bump-hash')
+    expect(mockWrapFeeBump).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ publicKey: feeBumpSigner.publicKey }),
+      expect.objectContaining({ networkPassphrase: expect.any(String) }),
+    )
+    expect(mockSendTransaction).toHaveBeenCalledWith(fakeBumpTx)
+  })
+
+  it('accepts secret key strings for envelopeSigner and feeBumpSigner', async () => {
+    const signer = Keypair.random()
+    const signature = new Uint8Array(64).fill(6)
+
+    mockGetAccount.mockResolvedValueOnce(new Account(signer.publicKey(), '105'))
+    mockPrepareTransaction.mockImplementationOnce((tx: any) => tx)
+    mockSendTransaction.mockResolvedValueOnce({ hash: 'str-hash', status: 'PENDING' })
+    mockGetTransaction.mockResolvedValueOnce({ status: 'SUCCESS' })
+
+    const hash = await closeFn({
+      channel: CHANNEL_ADDRESS,
+      amount: 5000000n,
+      signature,
+      feePayer: { envelopeSigner: signer.secret() },
+      network: 'stellar:testnet',
+    })
+
+    expect(hash).toBe('str-hash')
+  })
 })

sdk/src/channel/server/Channel.ts

@@ -403,7 +403,7 @@ export function channel(parameters: channel.Parameters) {
     if (action === 'close') {
       if (!signerKeypair) {
         throw new ChannelVerificationError(
-          `${LOG_PREFIX} Close action requires a feePayer to be configured.`,
+          `${LOG_PREFIX} Close action requires a feePayer.envelopeSigner (transaction source and envelope signer) to be configured.`,
           {},
         )
       }
@@ -708,8 +708,8 @@ export async function close(parameters: {
    * `feeBumpSigner` optionally wraps the tx in a FeeBumpTransaction.
    */
   feePayer: {
-    envelopeSigner: Keypair
-    feeBumpSigner?: Keypair
+    envelopeSigner: Keypair | string
+    feeBumpSigner?: Keypair | string
   }
   /** Network identifier. */
   network?: NetworkId
@@ -751,7 +751,7 @@ export async function close(parameters: {
     nativeToScVal(Buffer.from(signature), { type: 'bytes' }),
   )
 
-  const signer = feePayer.envelopeSigner
+  const signer = resolveKeypair(feePayer.envelopeSigner)
   const account = await server.getAccount(signer.publicKey())
   const tx = new TransactionBuilder(account, {
     fee: DEFAULT_FEE,
@@ -766,7 +766,7 @@ export async function close(parameters: {
 
   let txToSubmit: Transaction | FeeBumpTransaction = prepared
   if (feePayer.feeBumpSigner) {
-    txToSubmit = wrapFeeBump(prepared, feePayer.feeBumpSigner, {
+    txToSubmit = wrapFeeBump(prepared, resolveKeypair(feePayer.feeBumpSigner), {
       networkPassphrase,
       maxFeeStroops: maxFeeBumpStroops,
     })

sdk/src/charge/Methods.ts

@@ -12,7 +12,7 @@ import { z } from 'zod/mini'
  *   Client broadcasts itself and sends the transaction hash.
  *   The server looks it up on-chain for verification.
  *
- * @see https://stellar.org
+ * @see https://paymentauth.org/draft-stellar-charge-00
  */
 export const charge = Method.from({
   name: 'stellar',

sdk/src/charge/client/Charge.ts

@@ -40,6 +40,8 @@ import {
  * - **pull** (default): sends the signed XDR to the server to broadcast
  * - **push**: broadcasts itself and sends the tx hash
  *
+ * @see https://paymentauth.org/draft-stellar-charge-00
+ *
  * @example
  * ```ts
  * import { Keypair } from '@stellar/stellar-sdk'

sdk/src/charge/server/Charge.ts

@@ -38,6 +38,14 @@ import {
 const LOG_PREFIX = '[stellar:charge]'
 const STORE_PREFIX = 'stellar:charge'
 
+/**
+ * Creates a Stellar charge method for use on the **server**.
+ *
+ * Verifies and settles Soroban SAC `transfer` invocations received as
+ * pull-mode (signed XDR) or push-mode (on-chain tx hash) credentials.
+ *
+ * @see https://paymentauth.org/draft-stellar-charge-00
+ */
 export function charge(parameters: charge.Parameters) {
   const {
     currency,