Rust SDK Documentation

use mpp_near::{Challenge, RequestData};

let challenge = Challenge::builder()
    .realm("api.example.com")
    .method("near-intents")
    .intent("charge")
    .request(RequestData::new("0.001", "wallet.near"))
    .currency("USDC")
    .expires(300)           // TTL in seconds (default: 300)
    .secret(b"your-hmac-secret")
    .description("Image generation API")
    .build()?;

use mpp_near::RequestData;

// Create with required fields
let request = RequestData::new("0.001", "wallet.near");

// Builder pattern for optional fields
let request = RequestData::new("0.001", "wallet.near")
    .currency("USDC")
    .token_id("usdc.contract.near")
    .chain("near")
    .method_details(json!({"swap": "auto"}))
    .extra("max_slippage", json!("0.5"))
    .encode()?;  // Encode to base64url

use mpp_near::Credential;

let credential = Credential::builder()
    .challenge(&challenge)
    .proof("intent_hash_from_payment")
    .sign(client_private_key)?
    .build()?;

use mpp_near::{Credential, VerificationResult};

// From Authorization header
let credential = Credential::from_authorization(auth_header)?;

// Verify challenge binding
match credential.verify(&challenge) {
    VerificationResult::Valid => {
        // Payment verified successfully
    },
    VerificationResult::Invalid(reason) => {
        // Payment verification failed
        return Err(reason);
    },
}

use mpp_near::Receipt;

let receipt = Receipt::builder()
    .challenge_id(&challenge.id)
    .payer(Some("user.near"))
    .amount("0.001")
    .currency("USDC")
    .intent("charge")
    .build()?;

// Convert to header value
let header_value = receipt.to_header();
response.headers.insert("Payment-Receipt", header_value);

use mpp_near::PaymentProof;

// Simple proof
let proof = PaymentProof::new("intent_hash_here");

// From credential payload (JSON)
let proof = PaymentProof::from_payload(&credential_json)?;

use mpp_near::BodyDigest;

// From request body
let body = b"{\"prompt\": \"generate image\"}";
let digest = BodyDigest::sha256(body);

// Format: "sha-256=:base64hash:"
let digest_header = digest.to_header();

// Add to challenge
let challenge = Challenge::builder()
    .request(RequestData::new("0.001", "wallet.near"))
    .body_digest(digest)
    .build()?;

use mpp_near::Verifier;

pub trait Verifier {
    fn verify(&self, credential: &Credential)
        -> VerificationResult;
}

// Implementation provided for:
// - Challenge binding verification
// - Signature validation
// - Expiry checking

use mpp_near::MethodRegistry;

let mut registry = MethodRegistry::new();
registry.register(MyCustomMethod);
registry.register(AnotherMethod);

// Check if method exists
if registry.contains("my-method") {
    let method = registry.get("my-method").unwrap();
    // Use method to verify payment
}

// List all methods
let methods = registry.list();

use mpp_near::Problem;

// Payment insufficient
let problem = Problem::payment_insufficient(
    "0.01",    // required
    "0.001",   // actual
);

// Verification failed
let problem = Problem::verification_failed(
    "Invalid signature"
);

// Invalid challenge
let problem = Problem::invalid_challenge(
    "Challenge expired"
);

// Returns JSON:
// {
//   "type": "https://mpp.dev/problems/payment-insufficient",
//   "title": "Payment Insufficient",
//   "detail": "Required: 0.01, Actual: 0.001",
//   "status": 402
// }
let json = serde_json::to_string(&problem)?;

use mpp_near::Result;

// Result type alias
pub type Result<T> = std::result::Result<T, Error>;

// Usage
fn create_challenge() -> Result<Challenge> {
    // Returns Result<Challenge, Error>
    Ok(challenge)
}

use mpp_near::{VERSION, DEFAULT_CHALLENGE_TTL};

// Use in responses
response.headers.insert("MPP-Version", VERSION.parse()?);

// Use for default TTL
let ttl = DEFAULT_CHALLENGE_TTL;  // 300 seconds

// Override as needed
let challenge = Challenge::builder()
    .expires(DEFAULT_CHALLENGE_TTL)
    .build()?;

use axum::{Json, http::StatusCode, extract::State};
use mpp_near::{Challenge, Credential, RequestData, Receipt};
use std::sync::Arc;

async fn protected_image_generation(
    State(secret): State<Arc<Vec<u8>>>,
) -> Result<Json<&'static str>, StatusCode> {
    // Create payment challenge
    let challenge = Challenge::builder()
        .realm("api.example.com")
        .method("near-intents")
        .intent("charge")
        .request(
            RequestData::new("0.001", "wallet.near")
                .currency("USDC")
        )
        .description("AI image generation")
        .secret(&secret)
        .build()?;

    // Return 402 with challenge
    Err(StatusCode::PAYMENT_REQUIRED)
        // Include WWW-Authenticate header with challenge
}