Architecture, Security and the Patent Landscape

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 — CLI, Python API, REST, 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#

Is "100% coverage" a real gate or a badge?

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.

Does using Pain001 infringe the transformation patents above?

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.

Where do I report a security issue?

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