Integrate MPESA Payments into ZkRamp Using TLS Notary Techniques

[AbdelStark]

Integrate MPESA Payments into ZkRamp Using TLS Notary Techniques

Background

MPESA transactions primarily operate over the USSD protocol, which poses challenges for direct integration using TLS Notary techniques due to the lack of TLS-based communication. However, MPESA provides APIs accessible over HTTPS, which can be utilized to retrieve transaction details securely.

Challenges with MPESA and USSD

• USSD Limitations: MPESA's reliance on USSD does not provide the security guarantees or data transport mechanisms necessary for TLS Notary techniques.
• Lack of Cryptographic Proofs: Transactions over USSD do not inherently produce cryptographic proofs suitable for decentralized verification.
• API Access Requirements: Access to the MPESA APIs requires registration, compliance with Safaricom's policies, and proper handling of authentication credentials.

Proposed Solution

Leverage the MPESA APIs, specifically the Transaction Status API, to retrieve transaction details over HTTPS. Utilize TLS Notary to capture the TLS session during the API request, generating a cryptographic proof of the transaction data retrieved directly from MPESA's servers. This proof is then used to generate a STARK proof, which can be submitted to ZkRamp's smart contract on Starknet for on-chain verification.

Workflow Overview

1. User Initiates MPESA Payment: The user performs a standard MPESA transaction using USSD or the MPESA app to transfer funds.
2. Transaction Retrieval via MPESA API: The user retrieves transaction details by making a secure HTTPS request to the MPESA Transaction Status API.
3. TLS Session Capture with TLS Notary: The TLS session during the API request is captured using TLS Notary, generating a cryptographic proof.
4. Generation of STARK Proof: The TLS Notary proof is used to generate a STARK proof attesting to the transaction's validity.
5. Submission to ZkRamp: The STARK proof is submitted to the ZkRamp smart contract for verification.
6. On-chain Verification and Escrow Release: Upon successful verification, the smart contract releases the escrowed tokens to the user.

Implementation Steps

1. Accessing the MPESA Transaction Status API

• API Endpoint: https://sandbox.safaricom.co.ke/mpesa/transactionstatus/v1/query
• API Documentation: Safaricom Developer Portal

Sample Request Body:

{
  "Initiator": "testapiuser",
  "SecurityCredential": "ClONZiMYBpc65lmpJ7nvnrDmUe0WvHvA5QbOsPjEo92B6IGFwDdvdeJIFL0kgwsEKWu6SQKG4ZZUxjC",
  "CommandID": "TransactionStatusQuery",
  "TransactionID": "NEF61H8J60",
  "PartyA": "600782",
  "IdentifierType": "4",
  "ResultURL": "https://your-callback-url.com/transactionstatus/result",
  "QueueTimeOutURL": "https://your-callback-url.com/transactionstatus/timeout",
  "Remarks": "Transaction status inquiry",
  "Occasion": "Verification"
}

Sample Response Body:

{
  "OriginatorConversationID": "1236-7134259-1",
  "ConversationID": "AG_20210709_1234409f86436c583e3f",
  "ResponseCode": "0",
  "ResponseDescription": "Accept the service request successfully."
}

2. Capturing TLS Session with TLS Notary

• Objective: Generate a cryptographic proof that the transaction details were retrieved from MPESA's servers.
• Process:
  • Use TLS Notary to intercept and record the TLS session during the API request.
  • Ensure that the TLS Notary proof includes the server's SSL certificate chain and the exact data received.

3. Generating a STARK Proof

• Objective: Create a zero-knowledge proof attesting to the transaction's validity without revealing sensitive information.
• Process:
  • Use the TLS Notary proof as input to the STARK proof generation.
  • Implement the logic in Cairo that verifies the TLS Notary proof and extracts the transaction details (e.g., ResponseCode is 0).

4. Smart Contract Verification on Starknet

• Objective: Verify the STARK proof on-chain and execute escrow logic.
• Process:
  • Update the ZkRamp smart contract to include a verifier for the STARK proof.
  • Upon proof verification, release the escrowed tokens to the user.
  • Ensure that the smart contract handles any potential errors gracefully.

API References

• MPESA Developer Portal: https://developer.safaricom.co.ke/

• Transaction Status API Documentation: Transaction Status

• Sample Request and Response Codes:

  • ResponseCode values:

    • 0: Success - The transaction was processed successfully.
    • 1: Insufficient Funds - The account has insufficient funds.
    • 2001: Insufficient Credit - The initiator has insufficient credit.
    • 21: Authorization Error - Access denied due to authorization failure.

Considerations

Authentication and Security

• API Credentials: Secure storage and handling of Consumer Key and Consumer Secret required for API authentication.
• Security Credentials: Use of encrypted SecurityCredential for initiating transactions.
• Certificate Management: Proper management of SSL certificates during TLS Notary proof generation.

User Experience

• API Access for Users: Simplify the process for users to obtain necessary API credentials, possibly by abstracting this complexity within the ZkRamp client.
• Privacy Preservation: Maintain user privacy by ensuring sensitive data is not exposed during proof generation or submission.

Next Steps

Prototype Development

• Goal: Build a proof-of-concept demonstrating end-to-end integration.
• Tasks:
  • Implement API interaction with the MPESA sandbox environment.
  • Capture TLS sessions using TLS Notary during API requests.
  • Generate STARK proofs from TLS Notary data.
  • Update ZkRamp smart contract to verify proofs and manage escrow.

UI/UX Design

• Goal: Design user interfaces that simplify the integration process.
• Tasks:
  • Develop UI components for API credential management within the ZkRamp client.
  • Create intuitive workflows for initiating payments and submitting proofs.
  • Provide clear feedback and guidance to users throughout the process.

References:

• MPESA Developer Portal: https://developer.safaricom.co.ke/
• Transaction Status API Documentation: Transaction Status