solace-zar-trustless-escrow 0.1.0

data/lib/solace/zar_trustless_escrow/composers/mediated_release_composer.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes a `mediated_release` instruction for the ZAR Trustless Escrow
+    # program.
+    #
+    # The mediator releases a MediatedEscrowDeposit to the recipient (the depositor
+    # or the beneficiary) and closes the deposit, sending rent to the rent
+    # collector (which defaults to the mediator when none was set at deposit time).
+    #
+    # Required params:
+    #   :mint                    [#to_s] Mint of the escrowed tokens.
+    #   :mediator                [#to_s, Keypair] Mediator (readonly signer).
+    #   :recipient               [#to_s] Depositor or beneficiary receiving tokens.
+    #   :recipient_token_account [#to_s] Recipient's destination token account (ATA).
+    #   :mediated_escrow_deposit [#to_s] MediatedEscrowDeposit PDA.
+    #   :program_token_account   [#to_s] Per-mint program vault PDA.
+    #   :rent_collector          [#to_s] Account that receives the closed-account rent.
+    #   :fee_payer               [#to_s, Keypair] Fee payer (writable signer).
+    #   :id                      [#to_s] Unique id used to derive the escrow PDA.
+    #
+    # Optional params:
+    #   :program_id       [#to_s] Escrow program id (default: PROGRAM_ID, mainnet).
+    #   :token_program_id [#to_s] Token program (default: legacy SPL Token).
+    class ZarTrustlessEscrowMediatedReleaseComposer < Base
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # Extracts the mediator from the params
+      #
+      # @return [String] The mediator address
+      def mediator
+        params[:mediator].to_s
+      end
+
+      # Extracts the recipient from the params
+      #
+      # @return [String] The recipient address
+      def recipient
+        params[:recipient].to_s
+      end
+
+      # Extracts the recipient's destination token account from the params
+      #
+      # @return [String] The recipient token account address
+      def recipient_token_account
+        params[:recipient_token_account].to_s
+      end
+
+      # Extracts the MediatedEscrowDeposit PDA address from the params
+      #
+      # @return [String] The mediated escrow deposit address
+      def mediated_escrow_deposit
+        params[:mediated_escrow_deposit].to_s
+      end
+
+      # Extracts the per-mint program vault address from the params
+      #
+      # @return [String] The program token account address
+      def program_token_account
+        params[:program_token_account].to_s
+      end
+
+      # Extracts the rent collector from the params
+      #
+      # @return [String] The rent collector address
+      def rent_collector
+        params[:rent_collector].to_s
+      end
+
+      # Extracts the fee payer address from the params
+      #
+      # @return [String] The fee payer address
+      def fee_payer
+        params[:fee_payer].to_s
+      end
+
+      # Extracts the unique escrow id from the params
+      #
+      # @return [String] The escrow id
+      def id
+        params[:id].to_s
+      end
+
+      # Returns the escrow program id (defaults to the mainnet PROGRAM_ID)
+      #
+      # @return [String] The escrow program id
+      def program_id
+        (params[:program_id] || Solace::ZarTrustlessEscrow::PROGRAM_ID).to_s
+      end
+
+      # Returns the token program id (defaults to the legacy SPL Token program)
+      #
+      # @return [String] The token program id
+      def token_program_id
+        (params[:token_program_id] || Solace::Constants::TOKEN_PROGRAM_ID).to_s
+      end
+
+      # Returns the System Program id
+      #
+      # @return [String] The System Program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Returns the Associated Token Account Program id
+      #
+      # @return [String] The Associated Token Account Program id
+      def associated_token_program
+        Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_readonly_nonsigner(mint)
+        account_context.add_readonly_signer(mediator)
+        account_context.add_readonly_nonsigner(recipient)
+        account_context.add_writable_nonsigner(recipient_token_account)
+        account_context.add_writable_nonsigner(mediated_escrow_deposit)
+        account_context.add_writable_nonsigner(program_token_account)
+        account_context.add_writable_nonsigner(rent_collector)
+        account_context.add_writable_signer(fee_payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(token_program_id)
+        account_context.add_readonly_nonsigner(associated_token_program)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        Solace::ZarTrustlessEscrow::Instructions::MediatedReleaseInstruction.build(
+          id:,
+          mint_index:                     context.index_of(mint),
+          mediator_index:                 context.index_of(mediator),
+          recipient_index:                context.index_of(recipient),
+          recipient_token_account_index:  context.index_of(recipient_token_account),
+          mediated_escrow_deposit_index:  context.index_of(mediated_escrow_deposit),
+          program_token_account_index:    context.index_of(program_token_account),
+          rent_collector_index:           context.index_of(rent_collector),
+          fee_payer_index:                context.index_of(fee_payer),
+          system_program_index:           context.index_of(system_program),
+          token_program_index:            context.index_of(token_program_id),
+          associated_token_program_index: context.index_of(associated_token_program),
+          program_index:                  context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/composers/reclaim_composer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes a `re_claim` instruction for the ZAR Trustless Escrow program.
+    #
+    # The original depositor (or sponsor, as fee payer) reclaims an unclaimed
+    # EscrowDeposit and closes the deposit account.
+    #
+    # Required params:
+    #   :mint                    [#to_s] Mint of the escrowed tokens.
+    #   :depositor               [#to_s] Original depositor (receives the tokens).
+    #   :depositor_token_account [#to_s] Depositor's destination token account (ATA).
+    #   :escrow_deposit          [#to_s] EscrowDeposit PDA.
+    #   :program_token_account   [#to_s] Per-mint program vault PDA.
+    #   :fee_payer               [#to_s, Keypair] Fee payer (writable signer).
+    #   :claim_authority         [#to_s] Authority used to derive the escrow PDA.
+    #
+    # Optional params:
+    #   :program_id       [#to_s] Escrow program id (default: PROGRAM_ID, mainnet).
+    #   :token_program_id [#to_s] Token program (default: legacy SPL Token).
+    class ZarTrustlessEscrowReclaimComposer < Base
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # Extracts the depositor address from the params
+      #
+      # @return [String] The depositor address
+      def depositor
+        params[:depositor].to_s
+      end
+
+      # Extracts the depositor's destination token account from the params
+      #
+      # @return [String] The depositor token account address
+      def depositor_token_account
+        params[:depositor_token_account].to_s
+      end
+
+      # Extracts the EscrowDeposit PDA address from the params
+      #
+      # @return [String] The escrow deposit address
+      def escrow_deposit
+        params[:escrow_deposit].to_s
+      end
+
+      # Extracts the per-mint program vault address from the params
+      #
+      # @return [String] The program token account address
+      def program_token_account
+        params[:program_token_account].to_s
+      end
+
+      # Extracts the fee payer address from the params
+      #
+      # @return [String] The fee payer address
+      def fee_payer
+        params[:fee_payer].to_s
+      end
+
+      # Extracts the claim authority from the params
+      #
+      # @return [String] The claim authority address
+      def claim_authority
+        params[:claim_authority].to_s
+      end
+
+      # Returns the escrow program id (defaults to the mainnet PROGRAM_ID)
+      #
+      # @return [String] The escrow program id
+      def program_id
+        (params[:program_id] || Solace::ZarTrustlessEscrow::PROGRAM_ID).to_s
+      end
+
+      # Returns the token program id (defaults to the legacy SPL Token program)
+      #
+      # @return [String] The token program id
+      def token_program_id
+        (params[:token_program_id] || Solace::Constants::TOKEN_PROGRAM_ID).to_s
+      end
+
+      # Returns the System Program id
+      #
+      # @return [String] The System Program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Returns the Associated Token Account Program id
+      #
+      # @return [String] The Associated Token Account Program id
+      def associated_token_program
+        Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_readonly_nonsigner(mint)
+        account_context.add_readonly_nonsigner(depositor)
+        account_context.add_writable_nonsigner(depositor_token_account)
+        account_context.add_writable_nonsigner(escrow_deposit)
+        account_context.add_writable_nonsigner(program_token_account)
+        account_context.add_writable_signer(fee_payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(token_program_id)
+        account_context.add_readonly_nonsigner(associated_token_program)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        Solace::ZarTrustlessEscrow::Instructions::ReclaimInstruction.build(
+          claim_authority:,
+          mint_index:                     context.index_of(mint),
+          depositor_index:                context.index_of(depositor),
+          depositor_token_account_index:  context.index_of(depositor_token_account),
+          escrow_deposit_index:           context.index_of(escrow_deposit),
+          program_token_account_index:    context.index_of(program_token_account),
+          fee_payer_index:                context.index_of(fee_payer),
+          system_program_index:           context.index_of(system_program),
+          token_program_index:            context.index_of(token_program_id),
+          associated_token_program_index: context.index_of(associated_token_program),
+          program_index:                  context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/composers/token_account_init_composer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes a `token_account_init` instruction for the ZAR Trustless Escrow
+    # program.
+    #
+    # Initializes the per-mint program vault token account if it does not already
+    # exist. A single vault is shared across all deposits for a given mint.
+    #
+    # Required params:
+    #   :mint                  [#to_s] Mint the vault holds.
+    #   :program_token_account [#to_s] Per-mint program vault PDA.
+    #   :fee_payer             [#to_s, Keypair] Fee payer (writable signer).
+    #
+    # Optional params:
+    #   :program_id       [#to_s] Escrow program id (default: PROGRAM_ID, mainnet).
+    #   :token_program_id [#to_s] Token program (default: legacy SPL Token).
+    class ZarTrustlessEscrowTokenAccountInitComposer < Base
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # Extracts the per-mint program vault address from the params
+      #
+      # @return [String] The program token account address
+      def program_token_account
+        params[:program_token_account].to_s
+      end
+
+      # Extracts the fee payer address from the params
+      #
+      # @return [String] The fee payer address
+      def fee_payer
+        params[:fee_payer].to_s
+      end
+
+      # Returns the escrow program id (defaults to the mainnet PROGRAM_ID)
+      #
+      # @return [String] The escrow program id
+      def program_id
+        (params[:program_id] || Solace::ZarTrustlessEscrow::PROGRAM_ID).to_s
+      end
+
+      # Returns the token program id (defaults to the legacy SPL Token program)
+      #
+      # @return [String] The token program id
+      def token_program_id
+        (params[:token_program_id] || Solace::Constants::TOKEN_PROGRAM_ID).to_s
+      end
+
+      # Returns the System Program id
+      #
+      # @return [String] The System Program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_writable_nonsigner(mint)
+        account_context.add_writable_nonsigner(program_token_account)
+        account_context.add_writable_signer(fee_payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(token_program_id)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        Solace::ZarTrustlessEscrow::Instructions::TokenAccountInitInstruction.build(
+          mint_index:                  context.index_of(mint),
+          program_token_account_index: context.index_of(program_token_account),
+          fee_payer_index:             context.index_of(fee_payer),
+          system_program_index:        context.index_of(system_program),
+          token_program_index:         context.index_of(token_program_id),
+          program_index:               context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/constants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Solace
+  # Program IDs, PDA seeds, and cluster helpers for the ZAR Trustless Escrow
+  # program. The values mirror the [programs.*] entries in Anchor.toml and the
+  # constants exported by the TypeScript SDK.
+  module ZarTrustlessEscrow
+    # Per-cluster on-chain program IDs for the ZAR Trustless Escrow program.
+    # These mirror the [programs.*] entries in Anchor.toml and the PROGRAM_ID
+    # constants exported by the TypeScript SDK.
+    MAINNET_PROGRAM_ID  = 'ZARxRie8kHmJ3V3GSRFS6CUDjCMm5pEoZyhEddq6FSu'
+    DEVNET_PROGRAM_ID   = 'ZARTiAgmDYUcqbx35KF4cfJYudyQAeM4iagCXs5AR9V'
+    TESTNET_PROGRAM_ID  = 'ZARJV7Y9nLeJYPFdcd9xdXBxGWN84jDR1TdiiyZhKSo'
+    LOCALNET_PROGRAM_ID = 'HKzzmBQk3uat5Vak8RyPyDe3f6Fi9boR1vDV6qMrSXmH'
+
+    # Default program ID used when a cluster is not specified. Defaults to mainnet.
+    PROGRAM_ID = MAINNET_PROGRAM_ID
+
+    # PDA seed prefix for an EscrowDeposit account, derived from
+    # ["escrow_deposit", claim_authority].
+    ESCROW_DEPOSIT_SEED = 'escrow_deposit'
+
+    # PDA seed prefix for a MediatedEscrowDeposit account, derived from
+    # ["mediated_escrow_deposit", id].
+    MEDIATED_ESCROW_DEPOSIT_SEED = 'mediated_escrow_deposit'
+
+    # PDA seed prefix for the per-mint program vault token account, derived from
+    # ["vault", mint]. A single vault is shared across all deposits for a mint.
+    VAULT_SEED = 'vault'
+
+    # Maps a cluster symbol/string to its program ID.
+    #
+    # @param cluster [Symbol, String] One of :mainnet, :devnet, :testnet, :localnet.
+    # @return [String] The base58 program ID for the cluster.
+    # @raise [ArgumentError] If the cluster is unknown.
+    def self.program_id_for(cluster)
+      case cluster.to_sym
+      when :mainnet  then MAINNET_PROGRAM_ID
+      when :devnet   then DEVNET_PROGRAM_ID
+      when :testnet  then TESTNET_PROGRAM_ID
+      when :localnet then LOCALNET_PROGRAM_ID
+      else
+        raise ArgumentError, "Unknown cluster: #{cluster.inspect} (use :mainnet, :devnet, :testnet, :localnet)"
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/errors/program_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Errors
+      # A resolved on-chain TrustlessEscrowError, carrying its custom error code,
+      # variant name, and message. Returned by {Errors.from_code} and
+      # {Errors.from_name} so callers can translate a failed transaction's custom
+      # error code into a meaningful, rescuable Ruby error.
+      class ProgramError < Solace::ZarTrustlessEscrow::Error
+        # @!attribute [r] code
+        #   @return [Integer] The on-chain custom error code (6000-based).
+        attr_reader :code
+
+        # @!attribute [r] error_name
+        #   @return [String] The TrustlessEscrowError variant name.
+        attr_reader :error_name
+
+        # @param code [Integer] The on-chain custom error code.
+        # @param error_name [String] The TrustlessEscrowError variant name.
+        # @param message [String] The variant's on-chain #[msg] text.
+        def initialize(code:, error_name:, message:)
+          @code = code
+          @error_name = error_name
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'errors/program_error'
+
+module Solace
+  module ZarTrustlessEscrow
+    # Lookup for the on-chain TrustlessEscrowError codes, translating a custom
+    # program error code (e.g. from a failed transaction) into a {ProgramError}.
+    #
+    # The mapping is ported from the program's source of truth,
+    # programs/trustless_escrow/src/errors.rs — NOT the TypeScript SDK's errors
+    # file, which is stale (it omits DepositAmountInvalid, shifting every later
+    # code, and is missing all mediated-escrow errors). Anchor assigns each variant
+    # a code of {FIRST_ERROR_CODE} + its declaration index.
+    #
+    # @example
+    #   Solace::ZarTrustlessEscrow::Errors.from_code(6019)
+    #   # => #<ProgramError code=6019 error_name="MediatedExpiryMustBeInFuture" ...>
+    module Errors
+      extend self
+
+      # First on-chain custom error code (Anchor's default offset); maps to the
+      # first TrustlessEscrowError variant.
+      FIRST_ERROR_CODE = 6000
+
+      # TrustlessEscrowError variants in declaration order — index N is code
+      # FIRST_ERROR_CODE + N. Each entry is [variant name, on-chain #[msg] text].
+      DEFINITIONS = [
+        ['MintInvalid',
+         "MintInvalid: The mint provided does not match the escrow deposit's mint."],
+        ['DepositorInvalid',
+         'Depositor invalid'],
+        ['DepositAmountInvalid',
+         'DepositAmountInvalid: The deposit amount must be greater than 0.'],
+        ['SubsidyMismatch',
+         'Subsidy mismatch'],
+        ['InvalidAuthority',
+         'Either fee payer should be sponsor or depositor should be signer'],
+        ['InvalidCloseAuthority',
+         'InvalidCloseAuthority: When a sponsor is present, the fee payer must be the sponsor.'],
+        ['ClaimAuthorityMustBeASigner',
+         'ClaimAuthorityMustBeASigner: The claim authority must be a signer.'],
+        ['ClaimAuthorityIsInvalid',
+         "ClaimAuthorityIsInvalid: The claim authority provided does not match the escrow deposit's claim authority."],
+        ['DepositorCannotBeClaimant',
+         'DepositorCannotBeClaimant: The depositor cannot be the claimant (use reclaim instruction instead).'],
+        ['ReclaimerMustBeDepositor',
+         'ReclaimerMustBeDepositor: The reclaimer must be the depositor.'],
+        ['InvalidReclaimSigner',
+         'InvalidReclaimSigner: The reclaimer signer must be the depositor or the sponsor.'],
+        ['MediatorCannotBeDepositorOrBeneficiary',
+         'MediatorCannotBeDepositorOrBeneficiary: The mediator cannot be the depositor or the beneficiary.'],
+        ['InvalidMediator',
+         'InvalidMediator: The signer is not the mediator of the mediated escrow deposit.'],
+        ['MediatedDepositorCannotBeBeneficiary',
+         'MediatedDepositorCannotBeBeneficiary: The depositor and beneficiary cannot be the same account.'],
+        ['InvalidReleaseRecipient',
+         'InvalidReleaseRecipient: The recipient must be either the depositor or the beneficiary.'],
+        ['MediatedReclaimNotExpirable',
+         'MediatedReclaimNotExpirable: No expiry is set, so only the mediator can distribute the funds.'],
+        ['MediatedReclaimNotYetExpired',
+         'MediatedReclaimNotYetExpired: The mediated escrow deposit cannot be reclaimed before its expiry timestamp.'],
+        ['MediatedReclaimerMustBeDepositor',
+         'MediatedReclaimerMustBeDepositor: Only the depositor can reclaim the deposit after the expiry date.'],
+        ['InvalidRentCollector',
+         'InvalidRentCollector: The rent collector provided does not match the mediated escrow ' \
+         "deposit's rent collector."],
+        ['MediatedExpiryMustBeInFuture',
+         'MediatedExpiryMustBeInFuture: The expiry timestamp, when provided, must be in the future.']
+      ].freeze
+
+      # code => [name, message], derived by offsetting each declaration index with
+      # FIRST_ERROR_CODE.
+      BY_CODE = DEFINITIONS.each_with_index.to_h do |(name, message), index|
+        [FIRST_ERROR_CODE + index, [name, message]]
+      end.freeze
+
+      # name => code, for resolving an error by its variant name.
+      CODE_BY_NAME = BY_CODE.to_h { |code, (name, _message)| [name, code] }.freeze
+
+      # Resolves a {ProgramError} from an on-chain custom error code.
+      #
+      # @param code [Integer] The custom program error code (e.g. 6019).
+      # @return [ProgramError, nil] The typed error, or nil if the code is unknown.
+      def from_code(code)
+        name, message = BY_CODE[code]
+        return nil unless name
+
+        ProgramError.new(code:, error_name: name, message:)
+      end
+
+      # Resolves a {ProgramError} from a TrustlessEscrowError variant name.
+      #
+      # @param name [String] The variant name (e.g. "InvalidMediator").
+      # @return [ProgramError, nil] The typed error, or nil if the name is unknown.
+      def from_name(name)
+        code = CODE_BY_NAME[name]
+        return nil unless code
+
+        from_code(code)
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/instructions/claim_instruction.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `claim` instruction: the claim authority releases an
+      # EscrowDeposit to the claimant and closes the deposit account.
+      class ClaimInstruction
+        # 8-byte Anchor discriminator: SHA256("global:claim")[0..7].
+        DISCRIMINATOR = [62, 198, 214, 193, 213, 159, 108, 210].freeze
+
+        # Builds a Solace::Instruction for `claim`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, claim_authority, claimant, claimant_token_account,
+        #   escrow_deposit, program_token_account, fee_payer, system_program,
+        #   token_program, associated_token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          mint_index:,
+          claim_authority_index:,
+          claimant_index:,
+          claimant_token_account_index:,
+          escrow_deposit_index:,
+          program_token_account_index:,
+          fee_payer_index:,
+          system_program_index:,
+          token_program_index:,
+          associated_token_program_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [
+              mint_index,
+              claim_authority_index,
+              claimant_index,
+              claimant_token_account_index,
+              escrow_deposit_index,
+              program_token_account_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index,
+              associated_token_program_index
+            ]
+            ix.data = data
+          end
+        end
+
+        # Encodes the `claim` instruction data (discriminator only — no args).
+        #
+        # @return [Array<Integer>]
+        def self.data
+          DISCRIMINATOR.dup
+        end
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/instructions/deposit_instruction.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `deposit` instruction: locks `amount` tokens from the
+      # depositor into a per-claim-authority EscrowDeposit PDA and the per-mint
+      # program vault.
+      class DepositInstruction
+        # 8-byte Anchor discriminator: SHA256("global:deposit")[0..7].
+        DISCRIMINATOR = [242, 35, 198, 137, 82, 225, 242, 182].freeze
+
+        # Builds a Solace::Instruction for `deposit`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, depositor, depositor_token_account, escrow_deposit,
+        #   program_token_account, fee_payer, system_program, token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          claim_authority:,
+          sponsor:,
+          mint_index:,
+          depositor_index:,
+          depositor_token_account_index:,
+          escrow_deposit_index:,
+          program_token_account_index:,
+          fee_payer_index:,
+          system_program_index:,
+          token_program_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [
+              mint_index,
+              depositor_index,
+              depositor_token_account_index,
+              escrow_deposit_index,
+              program_token_account_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index
+            ]
+            ix.data = data(amount:, claim_authority:, sponsor:)
+          end
+        end
+
+        # Encodes the DepositCreateArgs struct in Borsh format.
+        #
+        # @param amount [Integer] u64 amount to deposit.
+        # @param claim_authority [#to_s] base58 authority that can claim the deposit.
+        # @param sponsor [#to_s, nil] optional base58 fee sponsor.
+        # @return [Array<Integer>]
+        def self.data(amount:, claim_authority:, sponsor:)
+          DISCRIMINATOR +
+            Solace::Utils::Codecs.encode_le_u64(amount).bytes +
+            Solace::Utils::Codecs.encode_pubkey(claim_authority) +
+            Solace::Utils::Codecs.encode_option_pubkey(sponsor)
+        end
+      end
+    end
+  end
+end