Security

┌─────────────────────────────────────────────────────────────┐
│                    TRANSPORT LAYER                          │
│  HTTPS/TLS encryption for all communication                │
├─────────────────────────────────────────────────────────────┤
│                    PROTOCOL LAYER                           │
│  EIP-712 typed data prevents signature reuse               │
├─────────────────────────────────────────────────────────────┤
│                    APPLICATION LAYER                        │
│  Nonces, time windows, amount validation                   │
├─────────────────────────────────────────────────────────────┤
│                    BLOCKCHAIN LAYER                         │
│  Smart contract verification, finality guarantees          │
└─────────────────────────────────────────────────────────────┘

const domain = {
  name: "USD Coin",        // Token name
  version: "2",            // Token version
  chainId: 8453n,          // Chain ID (prevents cross-chain replay)
  verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  // Token address
};

domainSeparator = keccak256(
  abi.encode(
    keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
    keccak256(bytes(name)),
    keccak256(bytes(version)),
    chainId,
    verifyingContract
  )
)

const types = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" }
  ]
};
 
const message = {
  from: "0xPayer...",
  to: "0xRecipient...",
  value: 1000000n,        // Amount in atomic units
  validAfter: 0n,         // Unix timestamp
  validBefore: 1705000000n, // Unix timestamp
  nonce: "0x..."          // Random 32 bytes
};

structHash = keccak256(
  abi.encode(
    keccak256("TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"),
    from,
    to,
    value,
    validAfter,
    validBefore,
    nonce
  )
)

messageHash = keccak256(0x19 || 0x01 || domainSeparator || structHash)

import secrets
 
def create_nonce() -> bytes:
    """Create a random 32-byte nonce for authorization signatures."""
    return secrets.token_bytes(32)

// Create and sign Solana transaction
func SignTransaction(tx *solana.Transaction, privateKey solana.PrivateKey) error {
    // Serialize message
    messageBytes, err := tx.Message.MarshalBinary()
    if err != nil {
        return err
    }
 
    // Sign with Ed25519
    signature, err := privateKey.Sign(messageBytes)
    if err != nil {
        return err
    }
 
    // Attach signature at correct index
    tx.Signatures[accountIndex] = signature
    return nil
}

Transaction Structure:
┌────────────────────────────────────────────┐
│ Signatures:                                │
│   [0] Fee Payer (Facilitator)              │
│   [1] Transfer Authority (Client)          │
├────────────────────────────────────────────┤
│ Instructions:                              │
│   1. ComputeBudget.SetLimit                │
│   2. ComputeBudget.SetPrice (≤5 lamports)  │
│   3. SPL Token TransferChecked             │
└────────────────────────────────────────────┘

// Associated Token Account (ATA) derivation
const ata = await getAssociatedTokenAddress(
  mint,        // Token mint address
  owner,       // Owner public key
  false,       // Allow owner off curve
  TOKEN_PROGRAM_ID,
  ASSOCIATED_TOKEN_PROGRAM_ID
);

// Build Jetton transfer message
const transferBody = beginCell()
  .storeUint(0xf8a7ea5, 32)        // transfer op code
  .storeUint(queryId, 64)          // query ID
  .storeCoins(amount)              // Jetton amount
  .storeAddress(destination)       // Recipient
  .storeAddress(responseDestination)
  .storeMaybeRef(null)             // custom payload
  .storeCoins(forwardTonAmount)    // TON for forward
  .storeMaybeRef(forwardPayload)
  .endCell();
 
// Create external message
const externalMessage = beginCell()
  .storeUint(seqno, 32)            // Sequence number
  .storeUint(expireAt, 32)         // Expiration
  .storeRef(internalMessage)
  .endCell();
 
// Sign
const signature = sign(externalMessage.hash(), privateKey);

Wallet State:
├─ seqno: Current sequence number
├─ Each transaction increments seqno
├─ Network rejects:
│   ├─ seqno < expected (already processed)
│   └─ seqno > expected (gap in sequence)
└─ Valid only if seqno == expected

// Sign TRON transaction
public byte[] signTransaction(Transaction tx) {
    // Serialize raw data
    byte[] rawData = tx.getRawData().toByteArray();
 
    // Hash with SHA-256
    byte[] txHash = Sha256.hash(rawData);
 
    // Sign with ECDSA
    ECDSASignature sig = ECKey.sign(txHash, privateKey);
 
    // Encode as 65 bytes (r, s, v)
    return encodeSignature(sig);
}

// Recover address from signature
public String recoverAddress(byte[] txHash, byte[] signature) {
    // Extract r, s, v
    BigInteger r = new BigInteger(1, Arrays.copyOfRange(signature, 0, 32));
    BigInteger s = new BigInteger(1, Arrays.copyOfRange(signature, 32, 64));
    int v = signature[64] & 0xFF;
 
    // Recover public key
    ECKey.ECDSASignature ecSig = new ECKey.ECDSASignature(r, s);
    ECKey recoveredKey = ECKey.recoverFromSignature(v - 27, ecSig, txHash);
 
    // Derive TRON address
    byte[] pubKeyHash = Hash.sha3(recoveredKey.getPubKey());
    byte[] addressBytes = new byte[21];
    addressBytes[0] = 0x41;  // TRON prefix
    System.arraycopy(pubKeyHash, 12, addressBytes, 1, 20);
 
    return Base58Check.encode(addressBytes);
}

from eth_account import Account
 
# Enable HD wallet features
Account.enable_unaudited_hdwallet_features()
 
# Derive EVM account from mnemonic
account = Account.from_mnemonic(
    seed_phrase,
    account_path="m/44'/60'/0'/0/0"  # BIP-44 path
)

// Good: Load from environment
const privateKey = process.env.PRIVATE_KEY;
 
// Bad: Hardcoded key
const privateKey = "0x1234..."; // NEVER DO THIS

┌─────────────────────────────────────────────────────────────────────────────┐
│                              T402 PAYMENT FLOW                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐    ┌──────────────────┐    ┌─────────────┐    ┌───────────┐  │
│  │  Client  │───▶│  Resource Server │───▶│ Facilitator │───▶│ Blockchain│  │
│  │ (Payer)  │◀───│    (Payee)       │◀───│  (Settler)  │◀───│  Network  │  │
│  └──────────┘    └──────────────────┘    └─────────────┘    └───────────┘  │
│       │                   │                     │                 │        │
│       │  1. Request       │                     │                 │        │
│       │─────────────────▶│                     │                 │        │
│       │  2. 402 + Requirements                 │                 │        │
│       │◀─────────────────│                     │                 │        │
│       │  3. Sign Payment  │                     │                 │        │
│       │  (local)          │                     │                 │        │
│       │  4. Request + Payment Header            │                 │        │
│       │─────────────────▶│                     │                 │        │
│       │                   │  5. Verify          │                 │        │
│       │                   │─────────────────────▶                 │        │
│       │                   │  6. Valid/Invalid   │                 │        │
│       │                   │◀─────────────────────                 │        │
│       │                   │  7. Process Request │                 │        │
│       │                   │                     │                 │        │
│       │                   │  8. Settle          │                 │        │
│       │                   │─────────────────────▶                 │        │
│       │                   │                     │  9. Submit Tx   │        │
│       │                   │                     │────────────────▶│        │
│       │                   │                     │  10. Confirmed  │        │
│       │                   │                     │◀────────────────│        │
│       │                   │  11. Settlement Response               │        │
│       │                   │◀─────────────────────                 │        │
│       │  12. Response + Settlement Header       │                 │        │
│       │◀─────────────────│                     │                 │        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

∀ payment P:
  P.settles ⟹ (P.amount = P.requirements.amount ∧
               P.recipient = P.requirements.payTo ∧
               P.signature.valid)

∀ transfer T:
  T.executes ⟹ ∃ signature S:
    (S.valid ∧ S.signer = T.from ∧ S.covers(T))

∀ authorization A:
  A.used_count ≤ 1

∀ authorization A:
  A.valid ⟹ (now ≥ A.validAfter ∧ now < A.validBefore)

∀ signature S on chain C1:
  ¬S.valid(chain C2) where C1 ≠ C2

github.com/t402-io/t402/
├── typescript/              # TypeScript SDK (36 npm packages)
│   └── packages/
│       ├── core/           # Protocol types
│       ├── mechanisms/
│       │   ├── evm/        # EVM signing (IN SCOPE)
│       │   ├── svm/        # Solana signing (IN SCOPE)
│       │   ├── ton/        # TON signing (IN SCOPE)
│       │   ├── tron/       # TRON signing (IN SCOPE)
│       │   ├── near/       # NEAR signing (IN SCOPE)
│       │   ├── aptos/      # Aptos signing (IN SCOPE)
│       │   ├── tezos/      # Tezos signing (IN SCOPE)
│       │   ├── polkadot/   # Polkadot signing (IN SCOPE)
│       │   ├── stacks/     # Stacks signing (IN SCOPE)
│       │   └── cosmos/     # Cosmos signing (IN SCOPE)
│       └── ...
├── go/                      # Go SDK
│   ├── signers/            # Signer implementations (IN SCOPE)
│   │   ├── evm/
│   │   └── svm/
│   ├── mechanisms/         # Chain-specific logic (IN SCOPE)
│   │   ├── evm/
│   │   ├── svm/
│   │   ├── ton/
│   │   ├── tron/
│   │   ├── near/
│   │   ├── aptos/
│   │   ├── tezos/
│   │   ├── polkadot/
│   │   ├── stacks/
│   │   └── cosmos/
│   └── ...
├── python/                  # Python SDK
│   └── t402/src/t402/
│       ├── schemes/        # Scheme implementations (IN SCOPE)
│       ├── wdk/            # Wallet signing (IN SCOPE)
│       └── erc4337/        # Account abstraction (IN SCOPE)
├── java/                    # Java SDK
│   └── src/main/java/io/t402/
│       └── crypto/         # Crypto signers (IN SCOPE)
├── services/
│   └── facilitator/        # Facilitator service (IN SCOPE)
└── specs/                   # Protocol specifications (REFERENCE)

File: go/mechanisms/evm/exact/facilitator/scheme.go

Function: Verify(ctx, payload, requirements)
├─ 1. Validate scheme = "exact"
├─ 2. Parse EVM payload from bytes
├─ 3. Extract authorization from payload
├─ 4. Get network configuration
├─ 5. Validate recipient matches payTo
├─ 6. Validate amount ≥ required
├─ 7. Check nonce not already used          ← CRITICAL: Replay prevention
├─ 8. Query payer balance                    ← CRITICAL: Sufficient funds
├─ 9. Get token metadata (name, version)
├─ 10. Compute EIP-712 hash                  ← CRITICAL: Correct hashing
├─ 11. Recover signer from signature         ← CRITICAL: Signature validation
├─ 12. Compare recovered address with from   ← CRITICAL: Authorization match
└─ 13. Return VerifyResponse

File: go/mechanisms/evm/exact/facilitator/scheme.go

Function: Settle(ctx, payload, requirements)
├─ 1. All verification steps (above)
├─ 2. Build transferWithAuthorization call
├─ 3. Estimate gas
├─ 4. Submit transaction                     ← CRITICAL: Correct parameters
├─ 5. Wait for confirmation
├─ 6. Mark nonce as used                     ← CRITICAL: Prevent double-spend
└─ 7. Return SettlementResponse

File: go/mechanisms/svm/exact/facilitator/scheme.go

Function: ValidateTransaction(tx, feePayer, requirements)
├─ 1. Verify exactly 3 instructions
│   ├─ [0] ComputeBudget.SetLimit
│   ├─ [1] ComputeBudget.SetPrice
│   └─ [2] SPL Token TransferChecked
├─ 2. Verify compute price ≤ 5 lamports     ← CRITICAL: Fee limit
├─ 3. For each instruction:
│   └─ Verify feePayer NOT in accounts      ← CRITICAL: Fee payer safety
├─ 4. Verify transfer authority ≠ feePayer  ← CRITICAL: Fee payer safety
├─ 5. Verify token source ≠ feePayer        ← CRITICAL: Fee payer safety
├─ 6. Verify transfer amount = required     ← CRITICAL: Exact amount
└─ 7. Verify destination = payTo ATA        ← CRITICAL: Correct recipient

File: go/mechanisms/evm/eip712.go

Function: HashEIP3009Authorization(domain, authorization)
├─ 1. Encode domain separator
│   ├─ Hash type string
│   ├─ Hash name
│   ├─ Hash version
│   ├─ Encode chainId
│   └─ Encode verifyingContract
├─ 2. Encode struct hash
│   ├─ Hash type string
│   ├─ Encode from
│   ├─ Encode to
│   ├─ Encode value
│   ├─ Encode validAfter
│   ├─ Encode validBefore
│   └─ Encode nonce
├─ 3. Compute final hash
│   └─ keccak256(0x19 || 0x01 || domainSeparator || structHash)
└─ 4. Return hash                           ← CRITICAL: Must match contract

// Signature edge cases
func TestVerifySignature_InvalidLength(t *testing.T) {
    // Signatures shorter than 65 bytes
    // Signatures longer than 65 bytes
}
 
func TestVerifySignature_InvalidV(t *testing.T) {
    // v = 0, 1, 26, 29, 30, 255
}
 
func TestVerifySignature_MalleableS(t *testing.T) {
    // s > n/2 (signature malleability)
}

// Nonce tests
func TestNonceUniqueness(t *testing.T) {
    // Same nonce, same payer
    // Same nonce, different payer
    // Concurrent nonce usage
}

// Time window tests
func TestTimeWindow_BoundaryConditions(t *testing.T) {
    // validAfter = now (exact boundary)
    // validBefore = now (exact boundary)
    // validAfter = validBefore
    // validAfter > validBefore
}

// Full payment flow on testnet
func TestFullPaymentFlow_EVM(t *testing.T) {
    // 1. Generate valid payment
    // 2. Verify payment
    // 3. Settle payment
    // 4. Verify nonce marked as used
    // 5. Attempt replay (should fail)
}