portfolio / wire operation
Explain portfolio P&L between two marks
totalfinance.portfolio.explain_pnl
Explain the change in net asset value between two dated valuation marks: external flows, investment return, and the identity components (realized, unrealized, income, transaction costs, financing, foreign exchange) that reconcile to it with a published residual, by currency and by grouping. The result is portfolioPnl(...) verbatim.
| Pack / profiles | portfolio / full, portfolio |
|---|---|
| Default discovery | Opt-in |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | small / Do not assume inline interruption |
| Handle-eligible inputs | ledger, from.market, to.market |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"ledger": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.portfolio-ledger",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"portfolioId": {
"type": "string"
},
"baseCurrency": {
"type": "string"
},
"lotRelief": {
"type": "string",
"enum": [
"fifo",
"lifo",
"highest-cost",
"specific-lot"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Portfolio event envelopes (each re-validated by readPortfolioLedgerSnapshot)"
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"baseCurrency",
"lotRelief",
"events"
],
"description": "A serialized portfolio ledger (totalfinance.portfolio-ledger, the FC7 JSON form)"
},
"from": {
"type": "object",
"properties": {
"valuationDate": {
"type": "string",
"format": "date",
"description": "Strict YYYY-MM-DD; the mark instant is 00:00 UTC"
},
"market": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.market-snapshot",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"asOf": {
"type": "number",
"description": "Epoch ms (resolved on the artifact)"
},
"conventions": {
"type": "object",
"properties": {
"conventionsVersion": {
"type": "string"
},
"asOfConvention": {
"type": "string",
"enum": [
"explicit-instant",
"date-midnight-utc"
],
"description": "How asOf was expressed at create time (a bare date is refused by option pricing)"
},
"dayCount": {
"type": "string"
},
"compounding": {
"type": "string"
},
"calendar": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"conventionsVersion",
"asOfConvention"
]
},
"observations": {
"type": "object",
"properties": {
"spots": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"riskFreeRates": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"dividendYields": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"volatilities": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"curves": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"surfaces": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"chains": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"asOf",
"conventions",
"observations"
],
"description": "A Gate B market snapshot (totalfinance.market-snapshot); its interior is re-validated by the read door"
},
"currencyConversions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"baseCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quoteCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quotePerBase": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"baseCurrency",
"quoteCurrency",
"quotePerBase"
]
}
}
},
"additionalProperties": false,
"required": [
"valuationDate",
"market"
],
"description": "The opening valuation mark"
},
"to": {
"type": "object",
"properties": {
"valuationDate": {
"type": "string",
"format": "date",
"description": "Strict YYYY-MM-DD; the mark instant is 00:00 UTC"
},
"market": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.market-snapshot",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"asOf": {
"type": "number",
"description": "Epoch ms (resolved on the artifact)"
},
"conventions": {
"type": "object",
"properties": {
"conventionsVersion": {
"type": "string"
},
"asOfConvention": {
"type": "string",
"enum": [
"explicit-instant",
"date-midnight-utc"
],
"description": "How asOf was expressed at create time (a bare date is refused by option pricing)"
},
"dayCount": {
"type": "string"
},
"compounding": {
"type": "string"
},
"calendar": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"conventionsVersion",
"asOfConvention"
]
},
"observations": {
"type": "object",
"properties": {
"spots": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"riskFreeRates": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"dividendYields": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"volatilities": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"curves": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"surfaces": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"chains": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"asOf",
"conventions",
"observations"
],
"description": "A Gate B market snapshot (totalfinance.market-snapshot); its interior is re-validated by the read door"
},
"currencyConversions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"baseCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quoteCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quotePerBase": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"baseCurrency",
"quoteCurrency",
"quotePerBase"
]
}
}
},
"additionalProperties": false,
"required": [
"valuationDate",
"market"
],
"description": "The closing valuation mark (strictly after `from`)"
},
"instrumentClassification": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"underlying": {
"type": "string"
},
"assetClass": {
"type": "string"
},
"strategy": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"description": "Identity metadata per instrument for grouping; unknown instruments group as unclassified"
}
},
"additionalProperties": false,
"required": [
"ledger",
"from",
"to"
]
}Output schema
{
"type": "object",
"properties": {
"baseCurrency": {
"type": "string"
},
"from": {
"type": "object"
},
"to": {
"type": "object"
},
"netAssetValueChange": {
"type": "number"
},
"externalFlows": {
"type": "number"
},
"investmentReturn": {
"type": "number"
},
"components": {
"type": "object",
"description": "realized, unrealized, income, costs, financing, FX, total"
},
"residual": {
"type": "number"
},
"byCurrency": {
"type": "array",
"items": {
"type": "object"
}
},
"groupings": {
"type": "array",
"items": {
"type": "object"
}
},
"assumptions": {
"type": "object",
"description": "Applied conventions"
},
"diagnostics": {
"type": "object",
"description": "Engine, method, warnings"
}
},
"required": [
"baseCurrency",
"from",
"to",
"netAssetValueChange",
"externalFlows",
"investmentReturn",
"components",
"residual",
"byCurrency",
"groupings",
"assumptions",
"diagnostics"
]
}