Dip 9002

dip: 9002 title: Dual Wallet Identity Model for Digitalia description: Defines Wallet ID Type 1 (Digitalia Standard) and Wallet ID Type 2 (ISO 20022-conformant) with Juro Core Banking as the official on/off-ramp conduit author: Cosimo Constantinos cosimo@juro.net Digitalia editing author: Cosimo Constantinos cosimo@juro.net type: Standards Track category: Interface status: Draft created: 2026-05-15 Created for Digitalia: 2025-01-07 requires: 155

Abstract¶

This DIP introduces a dual wallet identity model for the Digitalia ecosystem.

Wallet ID Type 1 (Standard Wallet): a native Digitalia wallet identity profile that conforms to core Digitalia standards and operates directly on Digitalia networks.
Wallet ID Type 2 (ISO Wallet): a Digitalia wallet identity profile constrained by ISO 20022 interoperability requirements for use in traditional financial services and public service rails.

Type 2 interoperability is anchored to the ISO resource sets maintained in:

digitalia/ISO-20022-API-Resources
Juro_Core_Banking/ISO-20022-API-Resources

This DIP designates Juro Core Banking as the official fiat/public-services on-ramp and off-ramp conduit for Wallet ID Type 2.

Motivation¶

Digitalia requires a first-class separation between:

purely Digitalia-native wallet operation, and
Digitalia wallets that must interact with regulated ISO 20022 environments.

Without this distinction, integrators must implement inconsistent ad hoc policies for settlement, identity attestation, and compliance controls. This causes interoperability failures and legal ambiguity at system boundaries.

The dual identity model solves this by creating explicit wallet profiles with normative behavioral rules, while preserving direct Digitalia-native wallet freedom for standard users.

ISO 20022 Summary¶

ISO 20022 is a global financial messaging standard used for structured payment, settlement, remittance, account, and reporting data exchange across institutions. In this DIP, ISO 20022 is implemented as the standard financial reporting and interoperability format required by central banks and banking regulators around the world, including the Federal Reserve, the European Central Bank, and the Atlantis Central Bank.

Specification¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

1. Wallet Identity Types¶

1.1 Wallet ID Type 1: Standard Wallet¶

A Wallet ID Type 1:

MUST conform to Digitalia-native transaction and account standards.
MUST be represented by a standard Digitalia account identity (address, chainId) and optional application metadata.
MUST NOT require ISO 20022 transformation before on-chain submission.
MAY interact with Digitalia-native smart contracts and DRC interfaces without ISO mediation.

Type 1 is the default wallet identity class.

1.2 Wallet ID Type 2: ISO Wallet¶

A Wallet ID Type 2:

MUST be a Digitalia wallet identity bound to an ISO 20022 interoperability profile.
MUST support bidirectional mapping between Digitalia payment intents and ISO 20022 messages.
MUST enforce policy controls required for traditional financial and public-service interoperability.
MUST route fiat/public-service on-ramp and off-ramp flows through Juro Core Banking.
MUST NOT bypass the Juro Core Banking conduit for Type 2 fiat/public-service boundary transitions.

2. Canonical Type Identifier¶

Wallet identity objects MUST include a type discriminator:

{
  "walletIdType": "TYPE_1_STANDARD" | "TYPE_2_ISO"
}

Alternative aliases MAY be supported internally for backward compatibility, but external APIs and governance documents MUST use these canonical values.

3. Wallet Identity Envelope¶

All wallet identities MUST expose the following minimum envelope:

{
  "walletId": "string",
  "walletIdType": "TYPE_1_STANDARD | TYPE_2_ISO",
  "address": "0x...",
  "chainId": 1,
  "status": "active | suspended | retired"
}

For TYPE_2_ISO, the envelope MUST additionally include:

{
  "isoProfileVersion": "string",
  "isoConformance": {
    "resourceSet": "ISO-20022-API-Resources",
    "validated": true,
    "lastValidatedAt": "RFC3339 timestamp"
  },
  "conduit": {
    "name": "Juro Core Banking",
    "role": "official_on_off_ramp"
  }
}

4. ISO 20022 Resource Binding¶

Type 2 implementations MUST source and validate message handling behavior against both repository resource sets:

digitalia/ISO-20022-API-Resources
Juro_Core_Banking/ISO-20022-API-Resources

At minimum, supported integration surface MUST include ISO business areas relevant to:

payments initiation,
payments clearing and settlement,
payment tracker/remittance,
account and reference data exchange.

These correspond to the archive families present in both resource directories (for example, archive_business_area_payments_initiation_* and archive_business_area_payments_clearing_and_settlement_*).

5. On-Ramp/Off-Ramp Conduit Authority¶

For Wallet ID Type 2:

Juro Core Banking is the official bridge authority for fiat/public-service boundary transitions.
Any Type 2 settlement or disbursement that touches traditional rails MUST be processed through Juro Core Banking interfaces.
Implementations MUST produce auditable linkage between Digitalia transaction references and corresponding ISO message references.

6. State Transitions¶

Wallets MAY be provisioned as Type 1 or Type 2 at creation time.

Type transitions are constrained as follows:

TYPE_1_STANDARD -> TYPE_2_ISO: MUST require successful ISO profile validation and conduit registration in Juro Core Banking.
TYPE_2_ISO -> TYPE_1_STANDARD: MAY be allowed by policy, but MUST preserve historical audit records and MUST NOT invalidate existing regulatory references.

7. Interoperability Rules¶

Type 1 and Type 2 wallets MAY coexist in the same application domain.
A transfer between Type 1 and Type 2 wallets that invokes fiat/public-service routing MUST be treated as Type 2-regulated flow.
Pure on-chain Digitalia transfers with no fiat/public-service boundary crossing MAY remain Type 1 semantics even when one party is Type 2, provided policy allows.

Rationale¶

Why two types?¶

Digitalia-native operation and ISO-constrained operation serve different legal and operational domains. Collapsing both into one wallet type increases ambiguity and weakens assurance for institutions that need deterministic ISO behavior.

Why make Juro Core Banking official for Type 2?¶

Type 2 needs a canonical bridge authority to avoid fragmented off-ramp behavior and incompatible compliance posture across providers. Naming Juro Core Banking as the official conduit creates a single interoperability anchor.

Why bind both repositories?¶

The digitalia and Juro_Core_Banking resource sets jointly represent the practical integration boundary. Requiring both prevents one-sided implementations that pass local tests but fail end-to-end settlement.

Backwards Compatibility¶

This DIP is additive at the protocol-governance layer:

Existing wallets can be treated as Type 1 by default.
Systems that already maintain ISO-specific wallet metadata can map those records to Type 2.
No change is required to DIP-155 transaction signing or base account addressing.

Security Considerations¶

Misclassification risk: Implementations MUST prevent an ISO-constrained wallet from operating as Type 1 when regulatory routing is required.
Audit integrity: Type 2 flows MUST maintain immutable reference linkage between on-chain transaction IDs and ISO message IDs.
Boundary bypass: Systems MUST reject Type 2 fiat/public-service transitions that do not route through Juro Core Banking.

Appendix A: Implementation Checklist¶

This appendix is normative for implementations claiming conformance with this DIP.

A.1 Conformance Matrix¶

ID	Requirement	Type 1	Type 2	Conformance Test
A-001	`walletIdType` MUST be present and canonical	REQUIRED	REQUIRED	Reject if missing or not `TYPE_1_STANDARD` or `TYPE_2_ISO`
A-002	Identity envelope fields (`walletId`, `address`, `chainId`, `status`) MUST be present	REQUIRED	REQUIRED	Reject if any required field is missing
A-003	`address` MUST be valid Digitalia hex address format	REQUIRED	REQUIRED	Reject malformed address or non-hex encoding
A-004	`chainId` MUST be positive integer	REQUIRED	REQUIRED	Reject zero, negative, non-integer, or string value
A-005	ISO 20022 transformation MAY be skipped for pure on-chain flow	ALLOWED	N/A	Verify Type 1 transfer can execute without ISO mapper
A-006	`isoProfileVersion` MUST exist	N/A	REQUIRED	Reject Type 2 payload without `isoProfileVersion`
A-007	`isoConformance.resourceSet` MUST be `ISO-20022-API-Resources`	N/A	REQUIRED	Reject mismatched resource set
A-008	`isoConformance.validated` MUST be `true` for active Type 2 operation	N/A	REQUIRED	Reject Type 2 settlement request when `validated=false`
A-009	`isoConformance.lastValidatedAt` MUST be RFC3339 timestamp	N/A	REQUIRED	Reject invalid timestamp format
A-010	Conduit name MUST be `Juro Core Banking`	N/A	REQUIRED	Reject Type 2 fiat/public flow with different conduit
A-011	Conduit role MUST be `official_on_off_ramp`	N/A	REQUIRED	Reject if role differs
A-012	Type 2 fiat/public transitions MUST route via Juro Core Banking	N/A	REQUIRED	Block direct external settlement path
A-013	Type transition `TYPE_1_STANDARD -> TYPE_2_ISO` requires ISO validation + conduit registration	CONDITIONAL	CONDITIONAL	Reject transition if either prerequisite missing
A-014	Type transition `TYPE_2_ISO -> TYPE_1_STANDARD` MUST preserve audit linkage	CONDITIONAL	CONDITIONAL	Verify historical references remain retrievable
A-015	Dual ISO resource binding to both repos MUST be configured	N/A	REQUIRED	Verify both resource directories are enabled in runtime configuration

A.2 Exit Criteria for Claiming Conformance¶

An implementation MAY claim conformance only if all rows marked REQUIRED for the relevant wallet type pass and no blocking severity defect remains in the Appendix B vector suite.

Appendix B: API Field Test Vectors¶

The vectors below are field-level conformance vectors for wallet identity API layers.

B.1 Vector Format¶

Each vector includes:

vectorId: stable identifier.
purpose: what is being validated.
input: JSON payload snippet.
expected: ACCEPT or REJECT.
reason: required implementation behavior.

B.2 Type 1 Vectors¶

Vector B-T1-001 (Valid Type 1 Envelope)¶

{
  "vectorId": "B-T1-001",
  "purpose": "Accept valid Type 1 wallet identity envelope",
  "input": {
    "walletId": "wlt_std_0001",
    "walletIdType": "TYPE_1_STANDARD",
    "address": "0x1111111111111111111111111111111111111111",
    "chainId": 1,
    "status": "active"
  },
  "expected": "ACCEPT",
  "reason": "All required Type 1 fields are present and valid"
}

Vector B-T1-002 (Invalid walletIdType)¶

{
  "vectorId": "B-T1-002",
  "purpose": "Reject non-canonical wallet type",
  "input": {
    "walletId": "wlt_std_0002",
    "walletIdType": "standard",
    "address": "0x1111111111111111111111111111111111111111",
    "chainId": 1,
    "status": "active"
  },
  "expected": "REJECT",
  "reason": "walletIdType must be TYPE_1_STANDARD or TYPE_2_ISO"
}

Vector B-T1-003 (Invalid chainId type)¶

{
  "vectorId": "B-T1-003",
  "purpose": "Reject non-integer chainId",
  "input": {
    "walletId": "wlt_std_0003",
    "walletIdType": "TYPE_1_STANDARD",
    "address": "0x1111111111111111111111111111111111111111",
    "chainId": "1",
    "status": "active"
  },
  "expected": "REJECT",
  "reason": "chainId must be a positive integer"
}

B.3 Type 2 Vectors¶

Vector B-T2-001 (Valid Type 2 Envelope)¶

{
  "vectorId": "B-T2-001",
  "purpose": "Accept valid Type 2 wallet identity envelope",
  "input": {
    "walletId": "wlt_iso_0001",
    "walletIdType": "TYPE_2_ISO",
    "address": "0x2222222222222222222222222222222222222222",
    "chainId": 1,
    "status": "active",
    "isoProfileVersion": "iso20022-v1.0",
    "isoConformance": {
      "resourceSet": "ISO-20022-API-Resources",
      "validated": true,
      "lastValidatedAt": "2026-05-14T10:45:00Z"
    },
    "conduit": {
      "name": "Juro Core Banking",
      "role": "official_on_off_ramp"
    }
  },
  "expected": "ACCEPT",
  "reason": "All required Type 2 fields are present and valid"
}

Vector B-T2-002 (Missing isoProfileVersion)¶

{
  "vectorId": "B-T2-002",
  "purpose": "Reject Type 2 payload without isoProfileVersion",
  "input": {
    "walletId": "wlt_iso_0002",
    "walletIdType": "TYPE_2_ISO",
    "address": "0x2222222222222222222222222222222222222222",
    "chainId": 1,
    "status": "active",
    "isoConformance": {
      "resourceSet": "ISO-20022-API-Resources",
      "validated": true,
      "lastValidatedAt": "2026-05-14T10:45:00Z"
    },
    "conduit": {
      "name": "Juro Core Banking",
      "role": "official_on_off_ramp"
    }
  },
  "expected": "REJECT",
  "reason": "Type 2 requires isoProfileVersion"
}

Vector B-T2-003 (Invalid conduit authority)¶

{
  "vectorId": "B-T2-003",
  "purpose": "Reject Type 2 fiat/public flow with non-authoritative conduit",
  "input": {
    "walletId": "wlt_iso_0003",
    "walletIdType": "TYPE_2_ISO",
    "address": "0x2222222222222222222222222222222222222222",
    "chainId": 1,
    "status": "active",
    "isoProfileVersion": "iso20022-v1.0",
    "isoConformance": {
      "resourceSet": "ISO-20022-API-Resources",
      "validated": true,
      "lastValidatedAt": "2026-05-14T10:45:00Z"
    },
    "conduit": {
      "name": "Other Banking Rail",
      "role": "official_on_off_ramp"
    }
  },
  "expected": "REJECT",
  "reason": "Type 2 conduit authority is fixed to Juro Core Banking"
}

Vector B-T2-004 (Invalid isoConformance timestamp)¶

{
  "vectorId": "B-T2-004",
  "purpose": "Reject invalid RFC3339 timestamp",
  "input": {
    "walletId": "wlt_iso_0004",
    "walletIdType": "TYPE_2_ISO",
    "address": "0x2222222222222222222222222222222222222222",
    "chainId": 1,
    "status": "active",
    "isoProfileVersion": "iso20022-v1.0",
    "isoConformance": {
      "resourceSet": "ISO-20022-API-Resources",
      "validated": true,
      "lastValidatedAt": "14-05-2026 10:45:00"
    },
    "conduit": {
      "name": "Juro Core Banking",
      "role": "official_on_off_ramp"
    }
  },
  "expected": "REJECT",
  "reason": "lastValidatedAt must be RFC3339"
}

B.4 Transition Vectors¶

Vector B-TR-001 (Valid Type 1 to Type 2 Transition)¶

{
  "vectorId": "B-TR-001",
  "purpose": "Accept transition when prerequisites are met",
  "input": {
    "fromType": "TYPE_1_STANDARD",
    "toType": "TYPE_2_ISO",
    "isoValidationPassed": true,
    "juroCoreBankingConduitRegistered": true
  },
  "expected": "ACCEPT",
  "reason": "Transition prerequisites satisfied"
}

Vector B-TR-002 (Invalid Type 1 to Type 2 Transition)¶

{
  "vectorId": "B-TR-002",
  "purpose": "Reject transition without ISO validation",
  "input": {
    "fromType": "TYPE_1_STANDARD",
    "toType": "TYPE_2_ISO",
    "isoValidationPassed": false,
    "juroCoreBankingConduitRegistered": true
  },
  "expected": "REJECT",
  "reason": "ISO profile validation is mandatory"
}

B.5 Severity Guidance¶

Any failure in vectors B-T2-001 through B-T2-004 for a Type 2 implementation is BLOCKING.
Any failure in B-TR-001 or B-TR-002 is BLOCKING for systems supporting wallet-type transitions.
Any failure in B-T1-001 through B-T1-003 is BLOCKING for Type 1 claims.

Appendix C: CI Test Harness Mapping¶

This appendix maps each vector in Appendix B to a recommended automated test identifier and expected HTTP/error outcome.

Vector ID	Recommended Automated Test Name	Expected HTTP Status	Expected Error Code
B-T1-001	`test_wallet_identity_type1_valid_envelope_accepts`	200	NONE
B-T1-002	`test_wallet_identity_type1_invalid_wallet_id_type_rejects`	422	WALLET_ID_TYPE_INVALID
B-T1-003	`test_wallet_identity_type1_chain_id_string_rejects`	422	CHAIN_ID_INVALID_TYPE
B-T2-001	`test_wallet_identity_type2_valid_envelope_accepts`	200	NONE
B-T2-002	`test_wallet_identity_type2_missing_iso_profile_version_rejects`	422	ISO_PROFILE_VERSION_MISSING
B-T2-003	`test_wallet_identity_type2_non_authoritative_conduit_rejects`	403	TYPE2_CONDUIT_NOT_AUTHORIZED
B-T2-004	`test_wallet_identity_type2_invalid_last_validated_at_rejects`	422	ISO_LAST_VALIDATED_AT_INVALID
B-TR-001	`test_wallet_identity_transition_type1_to_type2_with_prereqs_accepts`	200	NONE
B-TR-002	`test_wallet_identity_transition_type1_to_type2_without_iso_validation_rejects`	409	ISO_VALIDATION_REQUIRED

C.1 Mapping Notes¶

NONE indicates successful processing with no application error payload.
Status 422 is recommended for schema and field-level semantic validation failures.
Status 403 is recommended for conduit authority policy violations.
Status 409 is recommended for transition precondition failures.

Appendix D: Privacy and SBT Safety Rails (Normative)¶

This appendix is normative for all Type 2 implementations.

D.1 Data Minimization and Placement¶

Implementations MUST NOT write raw KYC/KYB/AML personal data to on-chain state.
Implementations MUST store only commitment hashes and authorization state on-chain for Type 2 identity and settlement linkage.
Full identity claims and supporting documents MUST be stored off-chain in encrypted regulated storage.

D.2 Type 2 Enablement via Soul-Bound Token¶

Type 2 activation MUST require a non-transferable soul-bound token (SBT) attesting compliance approval.
The SBT MUST include status (active/suspended/revoked/expired) and verifier authority reference.
If SBT status is missing or non-active, Type 2-regulated operations MUST fail closed.

D.3 Proof-of-Authority Access Control¶

Access to private Type 2 dossiers MUST require Proof-of-Authority role grants.
Access checks MUST validate both actor authorization and declared purpose of access.
Every private-data read or disclosure MUST produce immutable audit records.

D.4 UETR and Block Linkage¶

UETR values SHOULD be generated as UUID v4 according to ISO 20022 tracking practice.
On-chain records MUST store only uetrHash and binding commitments; raw UETR and private settlement payloads MUST remain off-chain.
Implementations MUST support verifier-side recomputation of commitments using off-chain records plus on-chain commitment values.

D.5 Explorer and Indexer Redaction¶

Public explorer/indexer services MUST expose only public commitment artifacts for Type 2 flows.
Explorer/indexer services MUST NOT expose PII-bearing fields from Type 2 dossiers or private ISO payloads.
Regulated disclosure MUST be performed through authorized private APIs, not public chain indexing.

D.6 Reference Architecture Artifact¶

Implementation profile and rollout baseline are defined in:

artifacts/production-gates/JFOS_WALLETTYPE2_PRIVACY_SAFETY_RAILS_20260515.md

Strict validation and conformance artifacts are defined in:

artifacts/production-gates/JFOS_WALLETTYPE2_ENROLLMENT_SCHEMA_20260515.json
artifacts/production-gates/JFOS_WALLETTYPE2_SBT_ISSUANCE_SCHEMA_20260515.json
artifacts/production-gates/JFOS_WALLETTYPE2_ACCEPTANCE_TEST_MATRIX_20260515.md
artifacts/production-gates/JFOS_WALLETTYPE2_DEPENDENCY_GATES_20260515.md

D.7 Minimum Type 2 Enrollment Dataset (Normative)¶

For Type 2 creation and SBT issuance, implementations MUST collect and verify subject data according to subject type and MUST keep all raw values off-chain.

D.7.1 Individual clients¶

At minimum, implementations MUST capture:

Full legal name.
Date of birth.
Residential address (physical address).
Identification number (jurisdiction-appropriate SSN/TIN/passport/license identifier).
Nationality/citizenship.
Occupation/job title and employment status.
Source of funds and purpose of account.
Estimated annual income or net-worth risk band.
PEP declaration.
Tax identifier and tax domicile metadata.

Required verification evidence MUST include:

Government photo identification.
Proof of address within policy validity window.
Tax form or tax certificate where required by jurisdiction.
Biometric matching evidence where legally permitted and configured.

D.7.2 Legal entities¶

At minimum, implementations MUST capture:

Legal entity name and DBA/trade names where applicable.
LEI when required by jurisdiction or market flow.
Tax and registration identifiers.
Principal place of business and mailing address.
Country of incorporation using ISO 3166-1 alpha-2.
Nature of business and expected account activity profile.
Source of wealth declaration.
Beneficial owner, controlling person, and authorized signatory datasets.

Required verification evidence MUST include, where applicable:

Formation/incorporation records.
Governing rules (bylaws, operating agreement, partnership equivalent).
Good standing or active registry proof.
Ownership and control records.
Trust/charity artifacts for trust and nonprofit structures.

D.7.3 Government and government agencies¶

At minimum, implementations MUST capture:

Official legal entity name.
Government entity type.
Enabling legislation or decree reference.
Principal operating address.
Tax/regulatory identifier.
Source of public funds and expected activity profile.
Authorized official/signatory identities.

Required verification evidence MUST include:

Enabling legal instrument.
Delegation/authorization instrument naming signatories.
Proof of appointment for authorized officials.
Identity evidence for signatories.
Tax status forms where applicable.

D.8 ISO 20022 Mapping Guardrails (Normative)¶

Type 2 records MUST support ISO 3166-1 alpha-2 country code normalization.
Type 2 records MUST support ISO 4217 currency code normalization.
Type 2 records MUST support BIC mapping for servicing institutions where required.
Entity and government records MUST support Organization Identification mapping (OrgId), including AnyBIC or Othr/Id patterns as required.
Implementations SHOULD support Ultimate Debtor and Ultimate Creditor mapping for shell-risk mitigation and look-through transparency in regulated flows.

D.9 Risk Escalation Triggers (Normative)¶

Enhanced due diligence MUST be triggered for at least:

High-risk jurisdictions.
PEP/signatory elevated-risk outcomes.
State-owned enterprise mixed-ownership structures requiring deeper ownership tracing.
Negative media or sanctions-adjacent alerts requiring manual case review.

Copyright¶

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.