Migrating from BaaS

If you have a working v1 bank adapter integration (the synchronous, baas REST surface), this is how you move it to bridge-core — Minka Ledger's network-agnostic participant bridge.

Audience

Executive summary

What changes

What stays the same

• TLS 1.2 minimum on all public surfaces.
• Ed25519 is still the signing primitive. Your financial institution still holds one Ed25519 keypair.
• PII redaction obligations (firstName, lastName, documentNumber, accountRef).
• IdempotencyRecord still governs replay safety. Only the keying changes.
• The financial institution's core system is untouched. Both adapters are façades.

What you can reuse

C4 diagrams

Context

The adapter talks to one system — the Ledger. The Ledger routes to whichever external network applies. The adapter has no opinion about which one.

Container, bridge-core

Differences at the container level:

• AnchorConsumer and ActionConsumer are gone. Those surfaces are not part of this adapter. Delete them.
• One BankEndpointsController with seven routes splits into two structural controllers (DebitCtrl, CreditCtrl) plus an EffectCtrl for receiving ledger effect signals. Each side owns three phases instead of one terminal verb.
• The three-guard stack (JWT, x-api-key, HMAC) collapses into a single AuthFilter that verifies the Hub's EdDSA JWT on every inbound call. No API key, no HMAC webhook signature.
• ProofSubmitter is new and load-bearing: an outbound HTTP client with a queue, retry, and crypto. In v1 the outbound path was "return from the controller." Here the controller acks 202 and the submitter completes the story later.
• The Crypto module is a first-class container now. v1 delegated signing to the SDK. Here the financial institution owns RFC 8785 canonical JSON, SHA-256 double-hash, and Ed25519 sign-of-digest. The library helps, but the financial institution makes the calls.
• An AuthStrategy port (not drawn) lets you pick ed25519-jwt or oauth-client-credentials per tenant. One more thing to configure.

Scope delta

In scope for both

• Move funds between accounts on the financial institution's core via a 2-phase commit.
• Idempotent under retry on (handle, phase) or (transactionId, ...) keys.
• TLS 1.2+.
• Ed25519 signing of outbound messages.
• Mock financial institution core for certification.
• Multi-impl parity (Java and Node share a contract test suite).

Dropped by bridge-core

New in bridge-core

Changed shape

Protocol shift, synchronous to asynchronous

v1, synchronous and terminal

The HTTP response is the result. Whatever happened on the core is already decided when the response goes on the wire. If the Hub retries, your idempotency store returns the same envelope verbatim.

bridge-core, asynchronous with signed-proof completion

Six async steps follow the sync 202. The 202 is just "got it, working on it." The Hub's state machine only advances when it receives the signed proof at POST /v2/intents/{handle}/proofs.

What this means for your design

• All validation moves into prepare. Commit must succeed if prepare did. If your v1 code validated in the response path of /debit, that logic has to move up into the prepare stage.
• You need a worker or queue. The HTTP thread acks 202 and hands off. The background worker does the core call and then submits the signed proof. On restart, the queue has to be persistent or the handle has to be re-discoverable. Persistence model is a per-impl decision: mock-core mode does not survive restart; postgres mode does.
• Failures land in the proof, not the HTTP response. status: failed is valid only in prepare proofs. Core rejections surface as a failed proof rather than a synchronous error.
• Retries are Hub-driven and open-ended. The Hub retries POST /v2/debits with the same data.handle until it gets 202. Your idempotency key is the handle, not the HTTP request.
• POST /v2/intents/{handle}/proofs must retry on 5xx. Exponential backoff: 1 s initial, doubling, 60 s cap, 10 attempts, dead-letter plus operator alert on exhaustion. The reference implementations include this out of the box.

Endpoint mapping

Wire each existing v1 handler to its bridge-core counterpart, or drop it.

New outbound calls from the financial institution, which have no v1 equivalent:

Request/response shape delta

Debit, before

POST /debit
Authorization: Bearer <token>
x-api-key: <key>
Content-Type: application/json

{
  "transactionId": "tx-abc-123",
  "target": "CHECKING:1234567@banco",
  "amount": "200000.00",
  "description": "Pago de servicios",
  "transferId": "tfr-456"
}

200 OK

{
  "code": "00",
  "message": "Acción realizada con éxito",
  "data": { "coreId": "TRA-TY-7788", "amount": "200000.00", "status": "SUCCESS" }
}

Debit, after (prepare phase only)

POST /v2/debits
Authorization: Bearer <eddsa-jwt or oauth-access-token>
x-ledger: <tenant handle>
Content-Type: application/json

{
  "data": {
    "luid": "$deb.7788",
    "amount": 20000000,
    "handle": "deb_01u9RGCevt4rEkRMV",
    "inputs": [0],
    "intent": {
      "data": {
        "access": [{ "action": "any", "signer": { "public": "<base64 hub key>" } }],
        "handle": "<intent handle>",
        "claims": [
          {
            "action": "transfer",
            "amount": 20000000,
            "source": { "handle": "checking:1234567@banco", "custom": { "name": "Acme SA", "entityType": "business", "documentType": "txid", "documentNumber": "900123456" } },
            "symbol": { "handle": "cop" },
            "target": { "handle": "checking:9876543@other-bank", "custom": { "firstName": "Julio", "lastName": "Guillén", "accountRef": "wgS5e2QvCXkLgAf7sZ642w8q4HjZVQG6qY", "entityType": "individual", "documentType": "cc", "documentNumber": "4407906192" } }
          }
        ],
        "custom": { "description": "Pago de servicios", "paymentNetwork": "TFY", "useCase": "send.b2p" },
        "schema": "payment"
      },
      "hash": "<hex sha256 of canonical(intent.data)>",
      "luid": "$int.7788",
      "meta": {
        "moment": "2026-04-17T10:22:11.000-05:00",
        "owners": ["<base64 hub key>"],
        "proofs": [],
        "status": "pending",
        "thread": "<thread id>"
      }
    },
    "schema": "debit",
    "source": { "handle": "checking:1234567@banco", "custom": { "name": "Acme SA", "entityType": "business", "documentType": "txid", "documentNumber": "900123456" } },
    "symbol": { "handle": "cop" },
    "target": { "handle": "checking:9876543@other-bank", "custom": { "firstName": "Julio", "lastName": "Guillén", "accountRef": "wgS5e2QvCXkLgAf7sZ642w8q4HjZVQG6qY", "entityType": "individual", "documentType": "cc", "documentNumber": "4407906192" } }
  },
  "hash": "<hex sha256 of canonical(data)>",
  "meta": {
    "proofs": [
      { "method": "ed25519-v2", "public": "<base64 hub key>", "digest": "<hex>", "result": "<base64 hub signature>", "custom": { "moment": "2026-04-17T10:22:11.000-05:00" } }
    ]
  }
}

202 Accepted

Later, on the worker thread:

POST /v2/intents/{intentHandle}/proofs
Authorization: Bearer <eddsa-jwt or oauth-access-token>

{
  "method": "ed25519-v2",
  "public": "<base64 ed25519-raw public key>",
  "digest": "<hex sha256 double-hash>",
  "result": "<base64 ed25519 signature of digest>",
  "custom": {
    "moment": "2026-04-17T10:22:11.000-05:00",
    "handle": "deb_01u9RGCevt4rEkRMV",
    "status": "prepared",
    "coreId": "TRA-TY-7788"
  }
}

Field-level migration crib

Authentication changes

Inbound, Hub calls the financial institution

Rip out the three-guard stack. A single AuthFilter verifies an EdDSA JWT plus optional x-ledger: <tenant handle>. That's it for inbound.

Outbound, financial institution calls the Hub

New. v1 had no outbound auth to manage.

Pick one mode per tenant via adapterConfig.auth.mode:

Both modes still require the Ed25519 keypair. Proofs are body-level signed regardless of transport auth. OAuth only replaces the Authorization: Bearer header source.

Configuration shape:

{
  "adapterConfig": {
    "auth": {
      "mode": "ed25519-jwt", // or "oauth-client-credentials"
      "ed25519Jwt": { "expirySeconds": 60, "skewSeconds": 5 },
      "oauth": {
        "tokenEndpoint": "/v2/oauth/token",
        "clientIdRef": "vault://bridge-core/<tenant>/oauth/client-id",
        "clientSecretRef": "vault://bridge-core/<tenant>/oauth/client-secret",
        "refreshSkewSeconds": 60,
        "exchangeRetry": { "maxAttempts": 5, "maxBackoffSeconds": 30 }
      }
    },
    "signer": {
      "handle": "bank-acme",
      "publicKey": "<base64 ed25519-raw>",
      "privateKeyRef": "vault://bridge-core/<tenant>/ed25519/private-key"
    }
  }
}

Idempotency model

Keys

Record shape

Both adapters store idempotency records for 24h. bridge-core also stores the submitted proof body, so retries skip both the core call and the proof submission.

interface ProofBody {
  method: 'ed25519-v2';
  public: string;        // base64 ed25519-raw
  digest: string;        // hex sha256 double-hash
  result: string;        // base64 ed25519 signature
  custom: {
    moment: string;      // ISO 8601
    handle: string;      // deb_* or cre_*
    status: 'prepared' | 'committed' | 'aborted' | 'failed';
    coreId?: string;
    reason?: string;     // bridge.* / core.* / record.* — only when status=failed
    detail?: string;     // only when status=failed
  };
}

interface IdempotencyEntry {
  handle: string;          // deb_* or cre_*
  phase: 'prepare' | 'commit' | 'abort';
  outcome: 'success' | 'failed';
  proofPayload: ProofBody; // the proof already submitted
  coreId?: string;
  createdAt: timestamp;
  ttl: 24h;
}

Replay semantics

• v1: a duplicate POST /debit returns the stored response envelope verbatim. Core is never touched twice.
• bridge-core: a duplicate POST /v2/debits returns 202 Accepted again. Core is never touched twice, and the proof is not re-submitted. The first proof is authoritative.

State machines

v1, transfer

CREATED → INITIATED → PENDING → ACCEPTED → COMPLETED
                                   ↓
                                 ERROR → REJECTED

Terminal: COMPLETED, REJECTED. 7 total states.

bridge-core, intent

created → pending → prepared → committed → completed
                       ↓
                    aborted → rejected

Terminal: completed, rejected. 7 total states (including created, which is Hub-internal).

bridge-core, per-handle (debit or credit)

received → prepared → committed
    ↓         ↓
  failed    aborted

Each debit or credit handle has its own local lifecycle. The intent lifecycle is the join of both handles.

Mapping

Anchor and account status are gone. They belong to other adapters.

Error model

Shape

Code mapping crib

Cryptography

What v1 did

• Bridge responses (crossing back to the ledger) signed via SDK Ed25519. The financial institution did not compute digests. The SDK did.
• Webhook bodies authenticated via HMAC-SHA256 with a shared hashKey delivered out of band at webhook creation.

What bridge-core requires

Every proof follows the same recipe, and you own every step:

1. Build the custom object (moment, handle, status, coreId, reason, detail).
2. Compute the digest: sha256(primaryHashHex + canonicalJSON(custom)).
   • primaryHashHex is the hash field of the parent object (intent hash for proofs submitted to POST /v2/intents/{h}/proofs).
   • canonicalJSON is RFC 8785: alphabetically sorted keys, no whitespace.
   • Direct concatenation, no separator. Empty custom becomes empty string.
3. Sign the digest bytes (hex-decoded) with Ed25519. On Node, the first arg to crypto.sign is undefined.
4. Serialise the proof:

{
  "method": "ed25519-v2",
  "public": "<base64 ed25519-raw>",
  "digest": "<hex>",
  "result": "<base64 signature>",
  "custom": { }
}

Only ed25519-v2 is accepted. Keys are base64 ed25519-raw. Do not extend the proof envelope with fields outside custom.*.

Reference Node proof builder (illustrative):

import { createHash, sign } from 'node:crypto';
import canonicalize from 'canonicalize'; // RFC 8785 canonical JSON

interface ProofCustom {
  moment: string;        // ISO 8601
  handle: string;        // deb_* or cre_*
  status: 'prepared' | 'committed' | 'aborted' | 'failed';
  coreId?: string;
  reason?: string;       // bridge.* / core.* / record.* — only when status=failed
  detail?: string;       // only when status=failed
}

export function buildProof(
  primaryHashHex: string,
  custom: ProofCustom,
  privateKey: Buffer,    // ed25519-raw, 32 bytes
  publicKey: Buffer,     // ed25519-raw, 32 bytes
) {
  const customJson = canonicalize(custom) ?? '';
  const digestHex = createHash('sha256')
    .update(primaryHashHex + customJson)
    .digest('hex');

  // Node Ed25519: first arg to crypto.sign is undefined (no hash — raw digest)
  const signature = sign(undefined, Buffer.from(digestHex, 'hex'), {
    key: privateKey,
    format: 'der',
  });

  return {
    method: 'ed25519-v2',
    public: publicKey.toString('base64'),
    digest: digestHex,
    result: signature.toString('base64'),
    custom,
  };
}

HMAC webhook signing is gone. Everything goes through EdDSA JWT now.

Mock core contract

Your mock-core ledger operations are byte-compatible between adapters. This is the one place you probably do not need to rewrite.

Seeding differs slightly. bridge-core uses CSV-driven scenario seeding so all three reference impls (Java, Node, .NET) share identical starting state. v1 scenario replay is driven by fixtures from the Transfiya contract examples.

Step-by-step migration plan

For an existing v1 deployment. A senior engineer with an existing contract-test harness and CI can work through these phases in roughly 15–25 days per impl, depending on test depth and how much of the reference implementation you reuse.

Phase 0, alignment (1–2 days)

1. Align on the bridge-core API contracts, flows, and authentication strategies before writing code. See the protocol reference for details.
2. Decide with ops and security: which auth mode (ed25519-jwt or oauth-client-credentials)? Which impl stack (Java, Node, .NET)?
3. Anchors and actions do not migrate here. Plan them separately if you still need them.

Phase 1, keypair and Hub registration (1 day)

1. Generate an Ed25519 keypair (ed25519-raw). Store the private half in a secret vault.
2. Register the public half with the Hub as a participant signer.
3. If oauth-client-credentials:
   • Ask the Hub admin to create an oauth-client-credentials factor on your signer. The Hub returns clientId and clientSecret with include: ['meta.secret'] (secret retrievable once at creation).
   • Store clientId and clientSecret as vault refs (vault://...). Inline secrets fail config validation.

Phase 2, rewrite controllers (5–8 days)

1. Delete: POST /refund, GET /status/:coreId, GET /account/verification/:accountId, GET /user/info/:userId, all anchor routes (/api/bridge/v2/onboard, /api/anchors/*), action consumer code, POST /login, POST /transfiya/oauth/token, reconciliation routes.
2. Split: the single POST /debit handler into a prepare controller, a commit controller, and an abort controller. Same for POST /credit.
3. Replace: POST /status (webhook) with an effect controller at POST /v2/effects/{handle}. Register an effect on the ledger that filters on intent status changes and delivers to your bridge (requires the events trait). The effect event payload carries the intent data and final status.
4. Add: a proof-submitter component (queue, retry, Ed25519 signing) and wire every prepare, commit, and abort success path to enqueue a proof for POST /v2/intents/{handle}/proofs.

Phase 3, rewrite idempotency (2–4 days)

1. Replace transactionId keys with data.handle (for prepare) and path {handle} (for commit, abort).
2. Store the already-submitted proof payload in the entry, not the HTTP response body.
3. Add a (handle, signal) idempotency scope for POST /v2/effects/{handle}.
4. Keep 24h TTL.

Phase 4, rewrite auth (3–5 days)

1. Delete: the three-guard stack (api-key, bearer, HMAC).
2. Add: a single AuthFilter that verifies an EdDSA JWT against the Hub's registered public key.
3. Add: AuthStrategy port with two implementations: Ed25519JwtAuthStrategy, OAuthClientCredentialsAuthStrategy. Wire the proof submitter and any outbound HTTP via the port only.
4. Add: OAuth token cache (keyed on clientId) with single-flight refresh, 60 s pre-expiry skew, exponential backoff on 5xx (1 s initial, 30 s max, 5 attempts).

Phase 5, rewrite error mapping (2–3 days)

1. Replace the numeric error table with string reasons: bridge.*, core.*, record.*.
2. Move all validation into prepare. Commit and abort must never produce status: failed proofs.
3. Schema-validation failures still return sync 400 with reason: record.schema-invalid. Everything else flows through the proof.

Phase 6, rewrite crypto (3–5 days)

The individual pieces are straightforward — tested libraries handle canonical JSON and Ed25519 for each platform. Most of the time here goes into getting the digest to match byte-for-byte against the Hub's expectation, which the reference implementation and contract tests make easy to verify.

1. Implement RFC 8785 canonical JSON via a tested library (@noble/ed25519 plus a canonical-JSON lib on Node; jose, com.google.crypto.tink, or a canonical-JSON lib on Java; NSec.Cryptography on .NET).
2. Implement the double-hash digest sha256(primaryHashHex + canonicalJSON(custom)).
3. Implement Ed25519 sign-of-digest (digest bytes hex-decoded, then Ed25519-signed).
4. Centralise the proof-building code in one module. Every controller calls through it.

Phase 7, amounts, handles, currency (1–2 days)

1. Convert amount handling from decimal strings to integer minor units. Grep for "amount" and every route parser.
2. Convert account handles from bare strings to <accountType>:<accountNumber>@<bank-domain>.
3. Propagate symbol.handle (ISO 4217 lowercase) instead of implicit COP. Mock core must key accounts by (handle, symbol).

Phase 8, tests (5–8 days)

1. Rewrite contract fixtures to bridge-core shapes. Drop anchor and action fixtures.
2. Port scenario replay to cover: happy path, payer-side failure (insufficient funds), payee-side failure (target inactive), proof retry, OAuth 401 recovery (if applicable), proof-submitter dead-letter.
3. Keep mutation-test coverage ≥ 80% per impl.
4. Add a byte-for-byte parity test between impls if you are shipping more than one.

Phase 9, observability, operations, rollout (3–5 days)

Your v1 dashboards watched HTTP 5xx rate — that is no longer the primary signal. Rebuild around proof-submission latency (target p95 ≤ 1.5 s), inbound endpoint ack latency (p95 ≤ 250 ms), and dead-letter count. Suggested metric names:

Update runbooks. The error path is now asynchronous — ops learns about failures from dead-letter alerts and the proof audit log instead of 5xx spikes. Document: graceful shutdown behaviour (does the worker flush in-flight proofs? recovery from idempotency store?), key rotation procedure (both auth modes), and OAuth clientSecret rotation.

Plan a blue-green rollout. The adapter is a new binary. You do not flip a feature flag.

Worked example, debit happy path side by side

v1

POST /debit  (Hub to financial institution)
Authorization: Bearer eyJhbGci...
x-api-key: banco-acme-key

{ "transactionId": "tx-001", "target": "CHK:12345@acme",
  "amount": "200000.00", "transferId": "tfr-001" }

Financial institution validates api-key and bearer.
Financial institution loads mock core, settles debit, coreId=TRA-TY-7788.

200 OK

{ "code": "00", "message": "Acción realizada con éxito",
  "data": { "coreId": "TRA-TY-7788", "amount": "200000.00", "status": "SUCCESS" } }

Done. Three log lines, one HTTP round trip.

bridge-core

POST /v2/debits  (Hub to financial institution)
Authorization: Bearer <eddsa-jwt>
x-ledger: acme

{ "data": { "luid": "$deb.001", "amount": 20000000,
            "handle": "deb_01u9RGCevt4rEkRMV",
            "schema": "debit",
            "source": { "handle": "checking:12345@acme" },
            "symbol": { "handle": "cop" },
            "target": { "handle": "checking:98765@other" },
            "intent": { "data": {}, "hash": "...", "luid": "$int.X", "meta": {} } },
  "hash": "<hex>", "meta": { "proofs": [ ] } }

202 Accepted

Worker picks up deb_01u9RGCevt4rEkRMV.
Financial institution verifies hash and Hub's EdDSA proof.
Financial institution validates account, amount, currency, limits.
Financial institution calls mock core: hold(checking:12345@acme, 20000000, handle=deb_01u...)
  coreId=TRA-TY-7788.
Financial institution builds { moment, handle, status: "prepared", coreId: "TRA-TY-7788" }.
Financial institution computes digest = sha256(intentHash + canonicalJSON(custom)).
Financial institution signs digest with Ed25519 private key.

POST /v2/intents/$int.X/proofs  (financial institution to Hub)
Authorization: Bearer <eddsa-jwt or oauth-token>

{ "method": "ed25519-v2",
  "public": "<base64>",
  "digest": "<hex>",
  "result": "<base64 sig>",
  "custom": { "moment": "2026-04-17T10:22:11Z",
              "handle": "deb_01u9RGCevt4rEkRMV",
              "status": "prepared",
              "coreId": "TRA-TY-7788" } }

200 OK  (from Hub)

The Hub now knows Financial institution A has prepared. It sends the same shape to Financial institution B for credit prepare.

Once both sides are prepared, the Hub fires POST /v2/debits/deb_01u.../commit (202 ack plus committed proof) and POST /v2/credits/cre_.../commit (202 ack plus committed proof). After both commits complete, effects fire — each financial institution that registered an intent-status effect receives a POST /v2/effects/{handle} with the completed status.

Testing strategy delta

v1 certification evidence was Transfiya-specific. bridge-core's is protocol-level and applies to any network the Hub fronts. If you're on Transfiya, network-specific certification still happens — it just lives outside the adapter now.

Rollback considerations

v1 and bridge-core cannot run in parallel in front of the same ledger tenant. The Hub speaks one protocol per tenant. Rollback is therefore deployment-level:

• Keep the v1 build deployable for the duration of the cutover.
• Register a second tenant on the Hub for bridge-core integration testing.
• Flip the live tenant's adapter once parity tests pass.
• If rollback is needed, re-point the live tenant at the old deployment. The Hub side has no persisted state that assumes either protocol, beyond proofs already accepted, and those are immutable history either way.

Open questions for the architect

Before cutting over, confirm with Minka:

1. OAuth retry budget on the Hub token endpoint. Default is 5 attempts, 30 s max backoff. Aligned with Hub SLAs?
2. Proof retry budget on POST /v2/intents/{h}/proofs. Default 10 attempts, 60 s max. Dead-letter routing after exhaustion: who receives the alert?
3. Clock skew tolerance on inbound JWT exp. Default 5 s. Sufficient for your NTP posture?
4. coreId cardinality. If your core does the operation in two internal steps, can one proof carry both? Current design allows one optional coreId string per proof.
5. Reversal flow. Your v1 POST /refund users: do they expect the financial institution to still surface a "refund" verb internally? If yes, translate it into a new intent upstream of the adapter. The adapter itself has no refund concept.
6. Effect registration. To receive intent status notifications, register an effect that filters on intent status changes and delivers to your bridge (via the events trait) or to a webhook URL. Confirm the effect is active via the Hub operator UI before cutover.

Reference

• About Orchestrating Systems — two-phase commit protocol
• Build the Credit and Debit Interface — endpoint surface
• Bridge Authentication — EdDSA JWT and OAuth modes
• Handle Errors and Retries — idempotency and retry semantics