Return-of-Capital Adjustment: Keep Price, Return, and Tax Views Separate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

/** Exact, point-in-time return-of-capital reference implementation. */
const SCALE = 100000000n;
const US_TAX_SCOPE = "US_FEDERAL_INDIVIDUAL_TAXABLE_2025";

const text = (v: unknown, n: string): string => { if (typeof v !== "string" || !v.trim()) throw new TypeError(`${n} must be a non-empty string`); return v; };
const instant = (v: unknown, n: string): number => {
  const s=text(v,n),m=s.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|([+-])(\d{2}):(\d{2}))$/); if(!m) throw new RangeError(`${n} must be a valid ISO 8601 instant`);
  const year=+m[1],month=+m[2],day=+m[3],hour=+m[4],minute=+m[5],second=+m[6],offsetHour=m[7]==="Z"?0:+m[9],offsetMinute=m[7]==="Z"?0:+m[10]; const leap=year%4===0&&(year%100!==0||year%400===0),days=[31,leap?29:28,31,30,31,30,31,31,30,31,30,31]; if(month<1||month>12||day<1||day>days[month-1]||hour>23||minute>59||second>59||offsetHour>14||offsetMinute>59||(offsetHour===14&&offsetMinute!==0)) throw new RangeError(`${n} must be a valid ISO 8601 instant`);
  const ms=Date.parse(s); if(!Number.isFinite(ms)) throw new RangeError(`${n} must be a valid ISO 8601 instant`); return ms;
};
const dec = (v: unknown, n: string, positive=false): bigint => {
  if(typeof v!=="string" || !/^(?:0|[1-9]\d*)(?:\.\d{1,8})?$/.test(v)) throw new TypeError(`${n} must be a non-negative plain decimal string with at most 8 places`);
  const [w,f=""]=v.split("."); const x=BigInt(w)*SCALE+BigInt((f+"00000000").slice(0,8)); if(positive && x===0n) throw new RangeError(`${n} must be positive`); return x;
};
const out = (v: bigint): string => { const sign=v<0n?"-":""; const x=v<0n?-v:v; return `${sign}${x/SCALE}.${(x%SCALE).toString().padStart(8,"0")}`; };
const roundDiv = (n: bigint,d: bigint): bigint => { if(d<=0n) throw new RangeError("nonpositive denominator"); const sign=n<0n?-1n:1n, x=n<0n?-n:n, q=x/d, r=x%d; return sign*(q+(r*2n>=d?1n:0n)); };
const mul = (a: bigint,b: bigint): bigint => roundDiv(a*b,SCALE);
const ratio = (a: bigint,b: bigint): bigint => roundDiv(a*SCALE,b);

function selectRevision(revisions: unknown, asOf: number): any {
  if(!Array.isArray(revisions)||!revisions.length) throw new TypeError("revisions must be a non-empty list");
  const seen=new Set<string>(); let eventId: string|undefined; const candidates: any[]=[];
  for(const r of revisions){ if(!r||typeof r!=="object"||Array.isArray(r)) throw new TypeError("each revision must be an object"); const x:any=r; const eid=text(x.eventId,"eventId"); eventId ??= eid; if(eid!==eventId) throw new RangeError("all revisions must describe one eventId"); if(!Number.isInteger(x.revisionSequence)||x.revisionSequence<1) throw new RangeError("revisionSequence must be a positive integer"); const key=`${text(x.revisionId,"revisionId")}|${x.revisionSequence}`; if(seen.has(key)) throw new RangeError("duplicate revision identity"); seen.add(key); const observed=instant(x.observedAt,"observedAt"),available=instant(x.availableAt,"availableAt");text(x.sourceId,"sourceId");if(observed>available)throw new RangeError("event revision must satisfy observedAt <= availableAt");if(available<=asOf)candidates.push([available,x.revisionSequence,x]); }
  if(!candidates.length) throw new RangeError("no event revision was available at asOf"); candidates.sort((a,b)=>a[0]-b[0]||a[1]-b[1]); return candidates.at(-1)[2];
}
function observation(value: any,name: string,asOf: number): [bigint,string] { if(!value||typeof value!=="object"||Array.isArray(value))throw new TypeError(`${name} must be an object`); const observed=instant(value.observedAt,`${name}.observedAt`),available=instant(value.availableAt,`${name}.availableAt`); if(observed>available||available>asOf)throw new RangeError(`${name} must satisfy observedAt <= availableAt <= asOf`); text(value.sourceId,`${name}.sourceId`); return [dec(value.price,`${name}.price`,true),text(value.currency,`${name}.currency`)]; }

export function calculate(payload: any): any {
  if(!payload||typeof payload!=="object"||Array.isArray(payload))throw new TypeError("payload must be an object"); const data=structuredClone(payload); const asOf=instant(data.asOf,"asOf"),r=selectRevision(data.revisions,asOf),status=text(r.status,"status"); if(!["confirmed","cancelled"].includes(status))throw new RangeError("status must be confirmed or cancelled"); if(status==="cancelled")return {eventId:r.eventId,revisionId:r.revisionId,state:"cancelled",applied:false};
  const exAt=instant(r.exAt,"exAt"); if(!r.terms||typeof r.terms!=="object")throw new TypeError("terms must be an object"); const t=r.terms,eventCurrency=text(t.eventCurrency,"eventCurrency"),gross=dec(t.grossCapitalReturnPerShare,"grossCapitalReturnPerShare"),withholding=dec(t.withholdingPerShare??"0","withholdingPerShare"),fees=dec(t.feesPerShare??"0","feesPerShare"); if(withholding+fees>gross)throw new RangeError("withholding plus fees cannot exceed the gross distribution");
  const [reference,priceCurrency]=observation(data.referenceObservation,"referenceObservation",asOf); if(instant(data.referenceObservation.observedAt,"referenceObservation.observedAt")>=exAt)throw new RangeError("referenceObservation must precede exAt");
  const fx=data.fxObservation; if(!fx||typeof fx!=="object")throw new TypeError("fxObservation must be an object"); const fxRate=dec(fx.priceCurrencyPerEventCurrency,"priceCurrencyPerEventCurrency",true);if(text(fx.anchorPolicy,"fxObservation.anchorPolicy")!=="ON_OR_BEFORE_REFERENCE_OBSERVATION")throw new RangeError("unsupported FX anchor policy");const fxObs=instant(fx.observedAt,"fxObservation.observedAt"),fxAvail=instant(fx.availableAt,"fxObservation.availableAt"); if(fxObs>fxAvail||fxAvail>asOf)throw new RangeError("FX must satisfy observedAt <= availableAt <= asOf");if(fxObs>instant(data.referenceObservation.observedAt,"referenceObservation.observedAt"))throw new RangeError("FX observation must be on or before the reference observation"); text(fx.sourceId,"fxObservation.sourceId"); if(eventCurrency===priceCurrency&&fxRate!==SCALE)throw new RangeError("same-currency events require an identity FX rate of 1"); if(eventCurrency!==priceCurrency&&text(fx.pair,"fxObservation.pair")!==`${eventCurrency}/${priceCurrency}`)throw new RangeError("FX pair must be eventCurrency/priceCurrency");
  const order=r.sameDayOrdering; if(!order||typeof order!=="object"||!Number.isInteger(order.sequence)||order.sequence<1||!Array.isArray(order.priorEventIds)||order.priorEventIds.length!==order.sequence-1||order.priorEventIds.some((x:unknown)=>typeof x!=="string"||!x))throw new RangeError("reference price must identify every earlier same-day action");
  const grossPrice=mul(gross,fxRate),netPrice=mul(gross-withholding-fees,fxRate),theoretical=reference-grossPrice; if(theoretical<=0n)throw new RangeError("gross distribution must leave a positive theoretical ex-price"); const factor=ratio(theoretical,reference);
  let returns:any=null; if(data.exObservation!=null){const [exPrice,exCurrency]=observation(data.exObservation,"exObservation",asOf);if(exCurrency!==priceCurrency)throw new RangeError("exObservation currency must equal price currency");if(instant(data.exObservation.observedAt,"exObservation.observedAt")<exAt)throw new RangeError("exObservation must be at or after exAt");returns={rawPriceReturn:out(ratio(exPrice,reference)-SCALE),grossTotalReturn:out(ratio(exPrice+grossPrice,reference)-SCALE),netCashReturn:out(ratio(exPrice+netPrice,reference)-SCALE)};}
  let taxResult:any=null; if(data.taxIllustration!=null){const tax=data.taxIllustration;if(!tax||typeof tax!=="object"||text(tax.jurisdiction,"taxIllustration.jurisdiction")!==US_TAX_SCOPE)throw new RangeError(`tax illustration supports only ${US_TAX_SCOPE}`);if(eventCurrency!=="USD"||text(tax.currency,"taxIllustration.currency")!=="USD")throw new RangeError("US tax illustration requires USD event and basis amounts");text(tax.sourceId,"taxIllustration.sourceId");const taxObs=instant(tax.observedAt,"taxIllustration.observedAt"),taxAvail=instant(tax.availableAt,"taxIllustration.availableAt");if(taxObs>taxAvail||taxAvail>asOf)throw new RangeError("tax illustration must satisfy observedAt <= availableAt <= asOf");const basis=dec(tax.basisPerShareBefore,"basisPerShareBefore"),classified=dec(tax.confirmedReturnOfCapitalPerShare,"confirmedReturnOfCapitalPerShare");if(classified>gross)throw new RangeError("tax-classified return of capital cannot exceed the gross distribution");const reduction=basis<classified?basis:classified;taxResult={basisPerShareAfter:out(basis-reduction),basisReductionPerShare:out(reduction),excessOverBasisPerShare:out(classified-reduction)};}
  return {eventId:r.eventId,revisionId:r.revisionId,state:"confirmed",applied:true,priceCurrency,marketDataAdjustment:{referencePrice:out(reference),grossDistributionInPriceCurrency:out(grossPrice),theoreticalExPrice:out(theoretical),backwardHistoryFactor:out(factor),forwardPostEventFactor:out(ratio(SCALE,factor)),factorDirection:"multiply_pre_ex_history_by_backwardHistoryFactor",theoreticalPriceIsObservedTrade:false},investorReturnDiagnostics:returns,usFederalTaxIllustration:taxResult};
}