Pain001

Engineering

Architecture, Security and the Patent Landscape

Zero-trust XML, exact decimal arithmetic, and validation as a hard gate, plus where an open implementation sits in a patented market.

3 min readLast reviewed

How Pain001 is engineered, why its guarantees hold, and where it sits in a message-transformation market that commercial vendors have patented around. Every architectural claim below maps to shipped, auditable code.

01. Zero-trust XML processing#

Payment files are an attack surface. Pain001 treats every input as hostile:

  • XXE and entity-expansion defence. All XML parsing (pain.002 status reports, camt.053 statements, XSD validation input) routes through defusedxml, blocking external entity injection and "billion laughs" expansion attacks. There is no lxml anywhere in the dependency tree.
  • Path-traversal validation. File paths pass a dedicated security validator before any read or write.
  • Charset containment. Text is transliterated to the ISO 20022 Latin character set accepted by SWIFT and SEPA before serialisation, so injection-adjacent characters never reach the wire format.
  • Plugin kill switch. PAIN001_DISABLE_PLUGINS=1 disables third-party plugin discovery for locked-down deployments, and pain001 plugins list makes every active extension auditable.

02. Exact arithmetic, recomputed totals#

IEEE 754 floats cannot represent most decimal amounts exactly; payment files built on floats eventually produce a control-sum mismatch. Pain001's generation and scheme-validation pipeline handles every amount as decimal.Decimal, and the group-header totals (NbOfTxs, CtrlSum) are recomputed from validated records, never copied from input. A file whose totals disagree with its transactions cannot be produced.

03. Validation as a gate, not an option#

Every generation path, whether CLI, Python API, REST, or MCP, runs the same three-layer pipeline: JSON Schema per record, optional scheme rulebook (SEPA SCT / Instant / SDD Core / B2B, cross-border), then XSD validation of the rendered document against the official ISO 20022 schema before writing. Surfaces cannot diverge because there is one pipeline.

Quality is enforced the same way: 100% line and branch coverage as a hard CI gate on the core (3,828 lines, 926 branches), strict mypy, Bandit and pip-audit, CodeQL, and a CycloneDX SBOM per release build. The Docker image runs as a dedicated non-root user.

04. The patent landscape and the open alternative#

Message transformation between SWIFT MT and ISO 20022 is patented commercial territory. Representative grants:

  • US 11,704,671 B2: "Financial messaging transformation-as-a-service" (Bottomline Technologies, granted 2023): converting financial messages between formats, including MT ↔ ISO 20022, delivered as a controlled-access service (USPTO).
  • US 9,412,091 B2: "Dynamic adaption of electronic routing slips for financial messaging" (Google Patents).

Academic work is converging on the same problem from the open side, including structural mapping frameworks for MT101 → pain.001 transformation (ResearchGate).

Pain001's position is deliberate: implement the published, open ISO 20022 standard (schemas, market-practice rulebooks, documented MT field mappings) as liberally licensed open source. Pain001 claims no patents and depends on none. The standard is public; tooling for it should be too.

05. Architectural shape#

   CSV / JSON / JSONL / SQLite / Parquet / GPG      Excel (.xlsx/.xlsm)      SWIFT MT101
                    │                                      │                     │
                    ▼                                      ▼                     ▼
              bundled loaders                    pain001-loader-xlsx    pain001-loader-mt101
                    └──────────────────┬───────────────────┘                     │
                                       ▼                                        │
                        normalisation & field aliases  ◄────────────────────────┘
                                       ▼
                 JSON Schema validation → scheme rulebook → Jinja2 render
                                       ▼
                        XSD validation (official ISO 20022 schema)
                                       ▼
              pain.001.001.03 – .12  /  pain.008.001.02 XML

One pipeline, four entry surfaces (CLI, library, REST, MCP), four plugin extension points (loaders, validators, schemes, writers). The Technical Reference documents every stage.

FAQ#

A hard gate: CI fails below 100% line and branch coverage on the core, and the repository's coverage report is verifiable (3,828 of 3,828 lines, 926 of 926 branches). Coverage does not prove correctness (the XSD validation against official schemas is what does that), but it proves every branch is exercised.

Pain001 implements the public ISO 20022 standard and publishes its MT101 field mapping openly; it is not a transformation-as-a-service platform. Nothing here is legal advice. The citations exist so your counsel can assess the landscape from primary sources.

Via the repository's security policy on GitHub. Coordinated disclosure is welcomed and credited.