finrb 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8474be54c480d3150125ba2a00e7b935fbfb10281ce857304889ebca48839bac
-  data.tar.gz: 571f0f38b0a662c749df453e314cb3f916efe27e2f466896e600719a9048aef1
+  metadata.gz: 2a5f20ce5e17a03b0043df557ea5ea2207eb15e286e8f80664ef436dadc6cbce
+  data.tar.gz: de4773bdabd2131fcfcf4be29cc9befecf47fd92353e308d7cdae5569d7c914e
 SHA512:
-  metadata.gz: 31edbc91ddfe6bfd433daaae2598be24b7fe22d604e40745b238a66c01ad8cd597d9a441b4643f9cd0a1adc5230cd2e3780fc1ba791e5799e921ffb0a6bc6e59
-  data.tar.gz: 59b760dfb7f1c27686d34362ad9da310b2bb20ccfc440b42f39e6c551fd14c1ac134dd3ed8795e0cf9d4274c264e085a95b59339bd71b5c11e6763f99f9b82a1
+  metadata.gz: e0afa3b1d816b589d23ea2a6cd16c3a274d4ce68bb2a2552caa7b5c398d214b66c3f287fc824c7b607c6288df40b2b7fe7541c84f190a8e3f282cd8ed47238a7
+  data.tar.gz: 22c1d7ace18c693faa7f7d28551a064a1e9390e61d9bb023724dc98afbc24c13ae8d80044496260e1c846a37ba7d0a3b70da58e318d04a56aae979f5ead7892b

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # finrb changelog
 
+## 1.3.0
+
+### Dated lending and calendars
+
+- Add opt-in dated amortization with monthly, quarterly, semiannual, and annual
+  payment frequencies, explicit short-final stubs, and Actual/365 Fixed or
+  Actual/360 interest accrual. Rate durations remain expressed in months.
+- Add `Amortization#cashflow_yield` to report the dated borrower's effective
+  annual cashflow-equivalent cost from net proceeds and scheduled payments.
+  This is not a jurisdiction-specific legal APR disclosure.
+- Add dependency-free US Federal Reserve payment-day and Israel TASE trading
+  calendars with business-day adjustment conventions. Supported ranges are
+  explicit: US 1950–2065 and TASE 2000–2050.
+- Extract immutable `Finrb::Schedule` payment periods for reuse by dated loans
+  and fixed-rate bonds.
+
+### Fixed income
+
+- Add `Finrb::FixedRateBond` for regular fixed-coupon bullet bonds, with
+  Actual/Actual ICMA coupon accrual, accrued interest, clean and dirty prices,
+  and yield-to-maturity.
+- Correct accrued-interest selection when settlement falls between an
+  unadjusted coupon boundary and its business-day-adjusted payment date.
+
+### Verification and development
+
+- Add pinned QuantLib reference fixtures and seeded randomized cross-validation
+  for dated amortization, calendar profiles, and fixed-rate bond valuations.
+- Add calendar and randomized bond oracle checks to CI, and organize scripts by
+  verification, fixture generation, packaging, documentation, and benchmarks.
+
 ## 1.2.0
 
 ### Validation and financial correctness

data/CONTRIBUTING.md

@@ -13,12 +13,12 @@ and TruffleRuby are tested as informational compatibility targets.
 ```shell
 bundle install
 bundle exec rake quality
-bundle exec rubocop
 ```
 
-`rake quality` runs the RSpec suite with coverage, verifies maintained API
-examples, and validates the packaged RBS declarations. Additional checks are
-available for changes that affect their domains:
+`rake quality` runs RuboCop and the RSpec suite with coverage, verifies
+maintained API examples, and validates the packaged RBS declarations. Run
+`bundle exec rake lint` alone for a focused full-repository lint check.
+Additional checks are available for changes that affect their domains:
 
 ```shell
 bundle exec rake security:audit

data/README.md

@@ -58,6 +58,9 @@ API explicitly returns another financial object, such as `Finrb::Rate`.
 | `Finrb::Cashflow` | NPV, XNPV, IRR, and XIRR |
 | `Finrb::Rate` | Nominal APR, effective APY, and compounding conversions |
 | `Finrb::Amortization` | Fixed and adjustable-rate loan amortization |
+| `Finrb::Schedule` | Immutable dated payment periods with optional calendar adjustment |
+| `Finrb::FixedRateBond` | Fixed-coupon bullet bond cashflows, accrued interest, price, and yield |
+| `Finrb::Calendars` | US Federal Reserve and Israel TASE business calendars |
 | `Finrb::TVM` | Present value, future value, payments, periods, and perpetuities |
 | `Finrb::Returns` | Holding-period, time-weighted, portfolio, and risk-adjusted returns |
 | `Finrb::Yields` | Money-market, bond-equivalent, effective, and continuous yield conversions |
@@ -131,6 +134,44 @@ first.interest_only?
 first.closing_balance
 ```
 
+Pass a Ruby `Date` as `start_date:` to opt into an actual/365 dated schedule.
+The start date is the accrual boundary; the first payment date is one month
+later. Month-end anchors stay at month end, while other day numbers are clamped
+to shorter months and recovered from the original anchor in the following
+month. Dated periods accrue simple nominal APR for their actual number of days
+(`APR * days / 365`); this is a specific convention, not a universal loan
+standard. Dates stay unadjusted by default. To opt in, supply a finrb market
+calendar and explicit business-day convention; the adjusted payment dates then
+drive the actual/365 accrual. finrb includes US Federal Reserve and Israel
+TASE full-day calendars, with no runtime holiday-data dependency.
+The profiles intentionally support US dates from 1950 through 2065 and TASE
+dates from 2000 through 2050; querying or configuring dates outside those
+windows raises `RangeError` rather than extrapolating silently.
+
+```ruby
+require 'date'
+
+dated = Finrb::Amortization.new(
+  100_000,
+  Finrb::Rate.new(0.05, :apr, duration: 3),
+  start_date: Date.new(2024, 1, 31)
+)
+dated.schedule.first.date # => #<Date: 2024-02-29 ...>
+
+bank_calendar = Finrb::Calendars::USFederalReserve.new
+calendar_adjusted = Finrb::Amortization.new(
+  100_000,
+  Finrb::Rate.new(0.05, :apr, duration: 3),
+  start_date: Date.new(2026, 1, 31),
+  calendar: bank_calendar,
+  business_day_convention: :modified_following
+)
+calendar_adjusted.schedule.first.date # => #<Date: 2026-02-27 ...>
+```
+
+See the [calendar API guide](docs/api.md#business-calendars) for market scope,
+holiday overrides, and supported date-adjustment conventions.
+
 Pass several duration-bearing rates for an adjustable-rate schedule. A block
 can modify each scheduled payment, for example to add a $150 principal payment:
 
@@ -185,6 +226,25 @@ financed_fee.net_proceeds    # => Flt::DecNum('250000')
 financed_fee.amount_financed # => Flt::DecNum('252500')
 ```
 
+For a dated schedule, `cashflow_yield` calculates the effective annual
+cashflow-equivalent cost to the borrower using net proceeds on the start date
+and each actual payment on its scheduled date. The final payment already
+includes any balloon settlement, so it is counted only once. The result is a
+`Finrb::Rate`; it is not a jurisdiction-specific legal APR and follows the
+current `Finrb::Cashflow.xirr` configuration.
+
+```ruby
+require 'date'
+
+dated_loan = Finrb::Amortization.new(
+  250_000,
+  rate,
+  start_date: Date.new(2025, 1, 15),
+  origination_fee: 2_500
+)
+dated_loan.cashflow_yield.apy # effective annual cost implied by proceeds and payments
+```
+
 ## Configuration
 
 Configure process-wide defaults during application startup:
@@ -261,14 +321,14 @@ Install the bundle and run the self-contained quality checks:
 ```shell
 bundle install
 bundle exec rake quality
-bundle exec rubocop
 bundle exec rake security:audit
 bundle exec rake package:verify
 ```
 
-The quality task runs the RSpec suite with line and branch coverage, generated
-IRR/XIRR properties, committed SciPy/QuantLib reference fixtures, and RBS
-validation.
+The quality task runs RuboCop, the RSpec suite with line and branch coverage,
+generated IRR/XIRR properties, committed SciPy/QuantLib reference fixtures,
+verified API examples, and RBS validation. Run `bundle exec rake lint` alone for
+a focused full-repository lint check.
 
 `security:audit` updates ruby-advisory-db and checks the locked dependencies.
 `package:verify` builds the gem, validates its contents and metadata, installs
@@ -321,17 +381,28 @@ only finrb's runtime dependencies and RSpec; MRI-only development tooling such
 as RBS, RuboCop, and coverage is deliberately excluded from engine
 compatibility runs.
 
-Maintainers with the optional Python environment can run the larger seeded
-solver verification campaign:
+Maintainers with the optional Python environment can run seeded randomized
+cross-validation campaigns for solvers and fixed-rate bonds:
 
 ```shell
-python3 -m pip install --requirement script/requirements-solver-verification.txt
+python3 -m pip install --requirement script/verification/requirements-solver.txt
 bundle exec rake solver:verify
 ```
 
+The bond campaign needs only QuantLib-Python 1.43:
+
+```shell
+python3 -m pip install --requirement script/verification/requirements-bonds.txt
+bundle exec rake bond:verify
+```
+
+The same bond campaign can run in the isolated Docker target with
+`bundle exec rake docker:verify_bond`.
+
 The Python packages are verification references, not gem dependencies. See
 [the fixture documentation](spec/fixtures/README.md) for reproducibility,
-Docker, batching, and tolerance details.
+Docker, batching, and tolerance details. Verification and maintainer utilities
+are grouped by purpose under `script/`.
 
 ## Project links
 

data/lib/finrb/amortization.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'calendars'
 require_relative 'cashflows'
+require_relative 'day_count'
 require_relative 'decimal'
 require_relative 'precision'
+require_relative 'schedule'
 require_relative 'transaction'
 require_relative 'validation'
+require 'date'
 
 module Finrb
   # the Amortization class provides an interface for working with loan amortizations.
@@ -19,22 +23,29 @@ module Finrb
   #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
   #   extra_payments = Finrb::Amortization.new(250000, rate){ |period| period.payment - 150 }
   class Amortization
+    FREQUENCY_MONTHS = Schedule::FREQUENCY_MONTHS
+    STUB_CONVENTIONS = Schedule::STUB_CONVENTIONS
+    public_constant :FREQUENCY_MONTHS, :STUB_CONVENTIONS
+
     # Immutable breakdown of one amortization period. Payments retain finrb's
     # cashflow sign convention and are negative; the other monetary fields are
     # non-negative.
     class Entry
       ATTRIBUTES = %i[period opening_balance payment interest principal additional_payment balloon_payment interest_only closing_balance].freeze
       MONETARY_ATTRIBUTES = ATTRIBUTES - %i[period interest_only]
-      private_constant :ATTRIBUTES, :MONETARY_ATTRIBUTES
+      DATE_ATTRIBUTE = :date
+      private_constant :ATTRIBUTES, :DATE_ATTRIBUTE, :MONETARY_ATTRIBUTES
 
-      attr_reader(*ATTRIBUTES)
+      attr_reader(*ATTRIBUTES, DATE_ATTRIBUTE)
 
-      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:)
+      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:, date: nil)
         raise(ArgumentError, 'period must be a non-negative integer.') unless period.is_a?(Integer) && !period.negative?
         raise(ArgumentError, 'interest_only must be true or false.') unless [true, false].include?(interest_only)
+        raise(ArgumentError, 'date must be a Date or nil.') unless date.nil? || date.instance_of?(Date)
 
         @period = period
         @interest_only = interest_only
+        @date = date
         MONETARY_ATTRIBUTES.each do |name|
           value = binding.local_variable_get(name)
           instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s.tr('_', ' ')))
@@ -43,17 +54,18 @@ module Finrb
       end
 
       def ==(other)
-        other.instance_of?(self.class) && ATTRIBUTES.all? { |name| public_send(name) == other.public_send(name) }
+        other.instance_of?(self.class) && ([DATE_ATTRIBUTE] + ATTRIBUTES).all? { |name| public_send(name) == other.public_send(name) }
       end
       alias eql? ==
 
       def hash
-        attributes = ATTRIBUTES.map { |name| public_send(name) }
-        attributes.hash
+        [date, *ATTRIBUTES.map { |name| public_send(name) }].hash
       end
 
       def to_h
-        ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+        attributes = ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+        attributes[DATE_ATTRIBUTE] = date unless date.nil?
+        attributes
       end
 
       alias interest_only? interest_only
@@ -71,7 +83,7 @@ module Finrb
     attr_reader :origination_fee
     # @return [Integer] number of leading periods that pay interest but no scheduled principal
     attr_reader :interest_only_periods
-    # @return [Flt::DecNum] the required monthly payment.  For loans with more than one rate, returns nil
+    # @return [Flt::DecNum] the required regular payment. For loans with more than one rate, returns nil
     attr_reader :payment
     # @return [Flt::DecNum] the principal amount of the loan
     attr_reader :principal
@@ -79,6 +91,18 @@ module Finrb
     attr_reader :rates
     # @return [Array<Entry>] immutable period-by-period loan breakdown
     attr_reader :schedule
+    # @return [Date, nil] the date from which payment dates are generated
+    attr_reader :start_date
+    # @return [Finrb::Calendars::Base, nil] the calendar used to adjust dated payments
+    attr_reader :calendar
+    # @return [Symbol, nil] business-day convention used when adjusting dated payments
+    attr_reader :business_day_convention
+    # @return [Symbol] day-count convention used for dated interest accrual
+    attr_reader :day_count
+    # @return [Symbol] interval between dated payments
+    attr_reader :frequency
+    # @return [Symbol] final partial-period handling
+    attr_reader :stub
 
     # @return [Flt::DecNum] the periodic payment due on a loan
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
@@ -114,8 +138,17 @@ module Finrb
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
-    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, &block)
+    # @param [Finrb::Calendars::Base, nil] calendar optional market calendar for dated payment adjustment
+    # @param [Symbol, nil] business_day_convention required when calendar is supplied
+    # @param [Symbol] frequency dated payment interval; rate durations remain in months
+    # @param [Symbol] stub explicit handling for a final partial dated period
+    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, start_date: nil, calendar: nil, business_day_convention: nil, day_count: DayCount::DEFAULT, frequency: :monthly, stub: :none, &block)
       @principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
+      raise(ArgumentError, 'start_date must be a Date or nil.') unless start_date.nil? || start_date.instance_of?(Date)
+
+      validate_day_count!(start_date, day_count)
+
+      validate_calendar_options!(start_date, calendar, business_day_convention)
 
       @origination_fee = Validation.non_negative_decimal(origination_fee, name: 'origination fee')
       raise(ArgumentError, 'finance_origination_fee must be true or false.') unless [true, false].include?(finance_origination_fee)
@@ -134,12 +167,16 @@ module Finrb
       @rates     = rates
       @block     = block
 
-      # compute the total duration from all of the rates.
-      @periods = rates.sum(&:duration)
+      initialize_schedule(start_date, frequency, stub, rates, calendar, business_day_convention)
+
       valid_interest_only = interest_only_periods.is_a?(Integer) && interest_only_periods.between?(0, @periods - 1)
       raise(ArgumentError, 'interest_only_periods must be a non-negative integer shorter than the loan term.') unless valid_interest_only
 
       @interest_only_periods = interest_only_periods
+      @start_date = start_date
+      @calendar = calendar
+      @business_day_convention = business_day_convention
+      @day_count = day_count
       @period = 0
 
       compute
@@ -149,7 +186,7 @@ module Finrb
     # @return [Numeric] -1, 0, or +1
     # @param [Amortization] other
     def ==(other)
-      (principal == other.principal) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
+      (principal == other.principal) && (start_date == other.start_date) && (calendar == other.calendar) && (business_day_convention == other.business_day_convention) && (day_count == other.day_count) && (frequency == other.frequency) && (stub == other.stub) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
     end
 
     attr_reader :finance_origination_fee
@@ -164,13 +201,31 @@ module Finrb
       @transactions.filter_map { |trans| trans.difference if trans.payment? }
     end
 
+    # Calculate the effective annual yield implied by borrower proceeds and
+    # scheduled loan payments. This is a cashflow-equivalent borrowing yield,
+    # not a jurisdiction-specific legal APR.
+    # @param [Numeric, nil] guess initial rate used by XIRR; defaults to Finrb.config.guess
+    # @return [Rate] the effective annual cashflow-equivalent yield
+    # @raise [ArgumentError] if the amortization has no start date
+    # @example
+    #   rate = Rate.new(0.05, :apr, duration: 12)
+    #   loan = Amortization.new(10_000, rate, start_date: Date.new(2025, 1, 15), origination_fee: 250)
+    #   loan.cashflow_yield.apy #=> effective annual borrower cost
+    def cashflow_yield(guess = nil)
+      raise(ArgumentError, 'cashflow_yield requires a start_date.') unless start_date
+
+      transactions = [Transaction.new(net_proceeds, date: start_date)]
+      transactions.concat(schedule.map { |entry| Transaction.new(entry.payment, date: entry.date) })
+      Cashflow.xirr(transactions, guess)
+    end
+
     # amortize the balance of loan with the given interest rate
     # @return none
     # @param [Rate] rate the interest rate to use in the amortization
-    def amortize(rate)
+    def amortize(rate, periods)
       regular_payment = nil
 
-      rate.duration.to_i.times do
+      periods.times do
         # Do this first in case the balance is zero already.
         break if @balance.zero?
 
@@ -178,13 +233,16 @@ module Finrb
         regular_payment ||= build_regular_payment(rate) unless interest_only
 
         # Compute and record interest on the outstanding balance.
-        int = Precision.money(@balance * rate.monthly)
-        interest = Interest.new(int, period: @period)
+        due_date = @payment_dates&.fetch(@period)
+        periodic_rate = due_date ? dated_period_rate(rate, @period) : rate.monthly
+        int = Precision.money(@balance * periodic_rate)
+        interest = Interest.new(int, period: @period, date: due_date)
         @balance += interest.amount
         @transactions << interest.dup
 
-        payment = interest_only ? build_interest_only_payment(int) : regular_payment
+        payment = interest_only ? build_interest_only_payment(int, due_date) : regular_payment
         payment.period = @period
+        payment.date = due_date if due_date
         payment.amount = -@balance if payment.amount.abs > @balance
         @additional_by_period << [-payment.difference, Flt::DecNum(0)].max
         @interest_only_by_period << interest_only
@@ -203,8 +261,8 @@ module Finrb
       @additional_by_period = []
       @interest_only_by_period = []
 
-      @rates.each do |rate|
-        amortize(rate)
+      @rates.each_with_index do |rate, index|
+        amortize(rate, @rate_period_counts.fetch(index))
       end
 
       # Add the residual balloon and any rounding remainder to the last payment.
@@ -226,7 +284,7 @@ module Finrb
 
     private :amortize, :compute
 
-    # @return [Integer] the time required to pay off the loan, in months
+    # @return [Integer] number of payments in the amortization schedule
     # @example In most cases, the duration is equal to the total duration of all rates
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
@@ -267,12 +325,66 @@ module Finrb
 
     private
 
+    def validate_calendar_options!(start_date, calendar, convention)
+      if calendar.nil?
+        raise(ArgumentError, 'business_day_convention requires a calendar.') unless convention.nil?
+
+        return
+      end
+
+      raise(ArgumentError, 'calendar must be a Finrb::Calendars::Base instance.') unless calendar.is_a?(Calendars::Base)
+      raise(ArgumentError, 'calendar adjustment requires a start_date.') unless start_date
+      raise(ArgumentError, "business_day_convention must be one of #{Calendars::Base::CONVENTIONS.join(', ')}.") unless Calendars::Base::CONVENTIONS.include?(convention)
+    end
+
+    def validate_day_count!(start_date, day_count)
+      raise(ArgumentError, "day_count must be one of #{DayCount::CONVENTIONS.join(', ')}.") unless DayCount::CONVENTIONS.include?(day_count)
+      raise(ArgumentError, 'a non-default day_count requires a start_date.') if start_date.nil? && day_count != DayCount::DEFAULT
+    end
+
+    def validate_schedule_options!(start_date, frequency, stub)
+      raise(ArgumentError, "frequency must be one of #{FREQUENCY_MONTHS.keys.join(', ')}.") unless FREQUENCY_MONTHS.key?(frequency)
+      raise(ArgumentError, "stub must be one of #{STUB_CONVENTIONS.join(', ')}.") unless STUB_CONVENTIONS.include?(stub)
+      raise(ArgumentError, 'a non-monthly frequency requires a start_date.') if start_date.nil? && frequency != :monthly
+      raise(ArgumentError, 'a non-default stub requires a start_date.') if start_date.nil? && stub != :none
+    end
+
+    def initialize_schedule(start_date, frequency, stub, rates, calendar, business_day_convention)
+      @term_months = rates.sum(&:duration)
+      validate_schedule_options!(start_date, frequency, stub)
+      @frequency = frequency
+      @stub = stub
+      @dated_schedule = start_date && Schedule.from_months(start_date:, term_months: @term_months, frequency:, stub:, calendar:, business_day_convention:)
+      @payment_dates = @dated_schedule&.payment_dates
+      @periods = @payment_dates ? @payment_dates.length : @term_months
+      @rate_period_counts = start_date ? periods_per_rate(rates, frequency, @periods) : rates.map(&:duration)
+    end
+
+    def periods_per_rate(rates, frequency, total_periods)
+      interval = FREQUENCY_MONTHS.fetch(frequency)
+      cumulative_months = 0
+      previous_period_count = 0
+      rates.each_with_index.map do |rate, index|
+        cumulative_months += rate.duration
+        if index == rates.length - 1
+          total_periods - previous_period_count
+        else
+          raise(ArgumentError, 'rate changes must align with a payment date for dated non-monthly schedules.') if (cumulative_months % interval).nonzero?
+
+          period_count = cumulative_months / interval
+          periods_in_segment = period_count - previous_period_count
+          previous_period_count = period_count
+          periods_in_segment
+        end
+      end
+    end
+
     def build_schedule
       opening_balance = @amount_financed
       @transactions.each_slice(2).with_index.map do |(interest, payment), index|
         principal = -(payment.amount + interest.amount)
         closing_balance = opening_balance - principal
-        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:)
+        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:, date: payment.date)
         opening_balance = closing_balance
         entry
       end
@@ -280,15 +392,20 @@ module Finrb
 
     def build_regular_payment(rate)
       periods = @periods - @period
-      amount = Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
-      Payment.new(amount, period: @period).tap do |payment|
+      amount =
+        if @start_date
+          dated_payment(@balance, rate, @period, @balloon)
+        else
+          Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
+        end
+      Payment.new(amount, period: @period, date: @payment_dates && @payment_dates.fetch(@period)).tap do |payment|
         payment.modify(&@block) if @block
         validate_payment!(payment)
       end
     end
 
-    def build_interest_only_payment(interest)
-      Payment.new(-interest, period: @period).tap do |payment|
+    def build_interest_only_payment(interest, date)
+      Payment.new(-interest, period: @period, date:).tap do |payment|
         payment.modify(&@block) if @block
         validate_payment!(payment, allow_zero: true)
       end
@@ -301,5 +418,24 @@ module Finrb
       requirement = allow_zero ? 'must not produce a positive amount' : 'must produce a negative amount'
       raise(ArgumentError, "payment modification #{requirement}.")
     end
+
+    def dated_period_rate(rate, period_index)
+      period = @dated_schedule.periods.fetch(period_index)
+      year_fraction = DayCount.year_fraction(period.accrual_start_date, period.payment_date, convention: @day_count)
+      periodic_rate = Precision.rate(rate.apr * year_fraction)
+      Validation.decimal_greater_than(periodic_rate, minimum: -1, name: 'dated periodic rate')
+    end
+
+    def dated_payment(balance, rate, period_index, balloon)
+      periods = (period_index...@periods).map { |index| dated_period_rate(rate, index) }
+      discount_factors = []
+      growth = Flt::DecNum('1')
+      periods.each do |periodic_rate|
+        growth *= periodic_rate + 1
+        discount_factors << (Flt::DecNum('1') / growth)
+      end
+      balloon_discounted = balloon * discount_factors.last
+      -Precision.money((balance - balloon_discounted) / discount_factors.sum)
+    end
   end
 end