solace-zar-trustless-escrow 0.1.0

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `mediated_deposit` instruction: locks `amount` tokens into
+      # a three-party MediatedEscrowDeposit PDA (keyed by `id`) and the per-mint
+      # program vault.
+      class MediatedDepositInstruction
+        # 8-byte Anchor discriminator: SHA256("global:mediated_deposit")[0..7].
+        DISCRIMINATOR = [138, 97, 90, 177, 112, 255, 208, 193].freeze
+
+        # Builds a Solace::Instruction for `mediated_deposit`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, depositor, depositor_token_account, mediated_escrow_deposit,
+        #   program_token_account, fee_payer, system_program, token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          id:,
+          mediator:,
+          beneficiary:,
+          rent_collector:,
+          expires_at:,
+          mint_index:,
+          depositor_index:,
+          depositor_token_account_index:,
+          mediated_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,
+              mediated_escrow_deposit_index,
+              program_token_account_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index
+            ]
+            ix.data = data(amount:, id:, mediator:, beneficiary:, rent_collector:, expires_at:)
+          end
+        end
+
+        # Encodes the MediatedDepositCreateArgs struct in Borsh format.
+        #
+        # @param amount [Integer] u64 amount to deposit.
+        # @param id [#to_s] base58 unique id used to derive the mediated escrow PDA.
+        # @param mediator [#to_s] base58 mediator who decides the outcome.
+        # @param beneficiary [#to_s] base58 beneficiary the mediator may release to.
+        # @param rent_collector [#to_s, nil] optional base58 rent collector on close.
+        # @param expires_at [Integer, nil] optional unix timestamp for depositor reclaim.
+        # @return [Array<Integer>]
+        def self.data(amount:, id:, mediator:, beneficiary:, rent_collector:, expires_at:)
+          DISCRIMINATOR +
+            Solace::Utils::Codecs.encode_le_u64(amount).bytes +
+            Solace::Utils::Codecs.encode_pubkey(id) +
+            Solace::Utils::Codecs.encode_pubkey(mediator) +
+            Solace::Utils::Codecs.encode_pubkey(beneficiary) +
+            Solace::Utils::Codecs.encode_option_pubkey(rent_collector) +
+            Solace::Utils::Codecs.encode_option_i64(expires_at)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `mediated_reclaim` instruction: after expiry, the original
+      # depositor reclaims a MediatedEscrowDeposit and closes the deposit account.
+      class MediatedReclaimInstruction
+        # 8-byte Anchor discriminator: SHA256("global:mediated_reclaim")[0..7].
+        DISCRIMINATOR = [192, 255, 211, 122, 12, 11, 191, 146].freeze
+
+        # Builds a Solace::Instruction for `mediated_reclaim`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, depositor, depositor_token_account, mediated_escrow_deposit,
+        #   program_token_account, fee_payer, system_program, token_program,
+        #   associated_token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          id:,
+          mint_index:,
+          depositor_index:,
+          depositor_token_account_index:,
+          mediated_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,
+              depositor_index,
+              depositor_token_account_index,
+              mediated_escrow_deposit_index,
+              program_token_account_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index,
+              associated_token_program_index
+            ]
+            ix.data = data(id:)
+          end
+        end
+
+        # Encodes the MediatedReclaimCreateArgs struct in Borsh format.
+        #
+        # @param id [#to_s] base58 unique id used to derive the mediated escrow PDA.
+        # @return [Array<Integer>]
+        def self.data(id:)
+          DISCRIMINATOR + Solace::Utils::Codecs.encode_pubkey(id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `mediated_release` instruction: the mediator releases a
+      # MediatedEscrowDeposit to the recipient (depositor or beneficiary) and
+      # closes the deposit, sending rent to the rent collector.
+      class MediatedReleaseInstruction
+        # 8-byte Anchor discriminator: SHA256("global:mediated_release")[0..7].
+        DISCRIMINATOR = [154, 204, 22, 195, 162, 179, 197, 181].freeze
+
+        # Builds a Solace::Instruction for `mediated_release`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, mediator, recipient, recipient_token_account,
+        #   mediated_escrow_deposit, program_token_account, rent_collector,
+        #   fee_payer, system_program, token_program, associated_token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          id:,
+          mint_index:,
+          mediator_index:,
+          recipient_index:,
+          recipient_token_account_index:,
+          mediated_escrow_deposit_index:,
+          program_token_account_index:,
+          rent_collector_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,
+              mediator_index,
+              recipient_index,
+              recipient_token_account_index,
+              mediated_escrow_deposit_index,
+              program_token_account_index,
+              rent_collector_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index,
+              associated_token_program_index
+            ]
+            ix.data = data(id:)
+          end
+        end
+
+        # Encodes the MediatedReleaseArgs struct in Borsh format.
+        #
+        # @param id [#to_s] base58 unique id used to derive the mediated escrow PDA.
+        # @return [Array<Integer>]
+        def self.data(id:)
+          DISCRIMINATOR + Solace::Utils::Codecs.encode_pubkey(id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `re_claim` instruction: the original depositor (or sponsor)
+      # reclaims an unclaimed EscrowDeposit and closes the deposit account.
+      class ReclaimInstruction
+        # 8-byte Anchor discriminator: SHA256("global:re_claim")[0..7].
+        DISCRIMINATOR = [105, 179, 220, 94, 121, 140, 144, 24].freeze
+
+        # Builds a Solace::Instruction for `re_claim`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, depositor, depositor_token_account, escrow_deposit,
+        #   program_token_account, fee_payer, system_program, token_program,
+        #   associated_token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          claim_authority:,
+          mint_index:,
+          depositor_index:,
+          depositor_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,
+              depositor_index,
+              depositor_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(claim_authority:)
+          end
+        end
+
+        # Encodes the ReclaimCreateArgs struct in Borsh format.
+        #
+        # @param claim_authority [#to_s] base58 authority used to derive the escrow PDA.
+        # @return [Array<Integer>]
+        def self.data(claim_authority:)
+          DISCRIMINATOR + Solace::Utils::Codecs.encode_pubkey(claim_authority)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    module Instructions
+      # Encoder for the `token_account_init` instruction: initializes the per-mint
+      # program vault token account if it does not already exist.
+      class TokenAccountInitInstruction
+        # 8-byte Anchor discriminator: SHA256("global:token_account_init")[0..7].
+        DISCRIMINATOR = [124, 4, 173, 7, 212, 208, 18, 239].freeze
+
+        # Builds a Solace::Instruction for `token_account_init`.
+        #
+        # Account indices are in the on-chain order:
+        #   mint, program_token_account, fee_payer, system_program, token_program.
+        #
+        # @return [Solace::Instruction]
+        def self.build(
+          mint_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,
+              program_token_account_index,
+              fee_payer_index,
+              system_program_index,
+              token_program_index
+            ]
+            ix.data = data
+          end
+        end
+
+        # Encodes the `token_account_init` 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/programs/zar_trustless_escrow/escrow_deposit_operations.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    class ZarTrustlessEscrow < Base
+      # Two-party escrow operations for {Solace::Programs::ZarTrustlessEscrow}:
+      # deposit, claim, and reclaim against the EscrowDeposit account. Mixed into
+      # the program client; methods run in the client's instance context
+      # (connection, program_id, and the get_*_address derivations are available).
+      # The per-mint vault setup (token_account_init) is shared across escrow types
+      # and lives on the client itself, not here.
+      module EscrowDepositOperations
+        # Fetches and deserializes the EscrowDeposit account at the given address.
+        # Derive the address first with {#get_escrow_deposit_address}.
+        #
+        # @param address [#to_s] Base58 address of the EscrowDeposit account.
+        # @return [Solace::ZarTrustlessEscrow::EscrowDeposit] The deserialized deposit.
+        # @raise [RuntimeError] If no account exists at the address.
+        def fetch_escrow_deposit(address:)
+          account = connection.get_account_info(address.to_s)
+          raise "EscrowDeposit account not found at #{address}" unless account
+
+          Solace::ZarTrustlessEscrow::EscrowDeposit.deserialize(
+            Solace::Utils::Codecs.base64_to_bytestream(account['data'][0])
+          )
+        end
+
+        # Returns whether an EscrowDeposit account exists at the given address.
+        # Derive the address first with {#get_escrow_deposit_address}.
+        #
+        # @param address [#to_s] Base58 address of the EscrowDeposit account.
+        # @return [Boolean] True if an account exists at the address.
+        def escrow_deposit_exists?(address:)
+          !connection.get_account_info(address.to_s).nil?
+        end
+
+        # Deposits funds into a two-party escrow, signs, and (optionally) sends it.
+        # The depositor and fee payer sign; when a sponsor pays, pass the sponsor
+        # keypair as payer and its address as sponsor.
+        #
+        # @param payer [Solace::Keypair] The fee payer (the depositor or the sponsor).
+        # @param depositor [Solace::Keypair] The depositor (signs).
+        # @param sign [Boolean] Whether to sign the transaction.
+        # @param execute [Boolean] Whether to send the transaction.
+        # @param composer_opts [Hash] Options for {#compose_deposit}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def deposit(payer:, depositor:, sign: true, execute: true, **composer_opts)
+          composer = compose_deposit(fee_payer: payer, depositor:, **composer_opts)
+
+          yield composer if block_given?
+
+          tx = composer
+               .set_fee_payer(payer)
+               .compose_transaction
+
+          if sign
+            tx.sign(payer, depositor)
+
+            connection.send_transaction(tx.serialize) if execute
+          end
+
+          tx
+        end
+
+        # Prepares a deposit transaction. Derives the EscrowDeposit PDA, the program
+        # vault, and the depositor's associated token account.
+        #
+        # @param mint [#to_s] Mint of the escrowed tokens.
+        # @param depositor [#to_s, Keypair] The depositor.
+        # @param claim_authority [#to_s] Authority that can claim the deposit.
+        # @param amount [Integer] u64 amount to deposit.
+        # @param fee_payer [#to_s, Keypair] The fee payer (writable signer).
+        # @param sponsor [#to_s] (Optional) Fee sponsor recorded on the deposit (default: nil).
+        # @param token_program_id [String] Token program that owns the mint (default: legacy SPL Token).
+        # @return [Solace::TransactionComposer] A composer with the deposit instruction.
+        def compose_deposit(
+          mint:,
+          depositor:,
+          claim_authority:,
+          amount:,
+          fee_payer:,
+          sponsor: nil,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          escrow_deposit, = get_escrow_deposit_address(claim_authority:)
+          program_token_account, = get_vault_address(mint:)
+          depositor_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            depositor,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowDepositComposer.new(
+            mint:,
+            depositor:,
+            depositor_token_account:,
+            escrow_deposit:,
+            program_token_account:,
+            fee_payer:,
+            amount:,
+            claim_authority:,
+            sponsor:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+
+        # Claims a two-party escrow on behalf of the claim authority, signs, and
+        # (optionally) sends it. The claim authority and fee payer sign.
+        #
+        # @param payer [Solace::Keypair] The fee payer (signs).
+        # @param claim_authority [Solace::Keypair] The claim authority (signs).
+        # @param sign [Boolean] Whether to sign the transaction.
+        # @param execute [Boolean] Whether to send the transaction.
+        # @param composer_opts [Hash] Options for {#compose_claim}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def claim(payer:, claim_authority:, sign: true, execute: true, **composer_opts)
+          composer = compose_claim(fee_payer: payer, claim_authority:, **composer_opts)
+
+          yield composer if block_given?
+
+          tx = composer
+               .set_fee_payer(payer)
+               .compose_transaction
+
+          if sign
+            tx.sign(payer, claim_authority)
+
+            connection.send_transaction(tx.serialize) if execute
+          end
+
+          tx
+        end
+
+        # Prepares a claim transaction. Derives the EscrowDeposit PDA, the program
+        # vault, and the claimant's associated token account.
+        #
+        # @param mint [#to_s] Mint of the escrowed tokens.
+        # @param claim_authority [#to_s, Keypair] Authority that can claim the deposit.
+        # @param claimant [#to_s] Recipient of the released tokens.
+        # @param fee_payer [#to_s, Keypair] The fee payer (writable signer).
+        # @param token_program_id [String] Token program that owns the mint (default: legacy SPL Token).
+        # @return [Solace::TransactionComposer] A composer with the claim instruction.
+        def compose_claim(
+          mint:,
+          claim_authority:,
+          claimant:,
+          fee_payer:,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          escrow_deposit, = get_escrow_deposit_address(claim_authority:)
+          program_token_account, = get_vault_address(mint:)
+          claimant_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            claimant,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowClaimComposer.new(
+            mint:,
+            claim_authority:,
+            claimant:,
+            claimant_token_account:,
+            escrow_deposit:,
+            program_token_account:,
+            fee_payer:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+
+        # Reclaims an unclaimed two-party escrow, signs, and (optionally) sends it.
+        # The fee payer (the depositor or the sponsor) is the only signer.
+        #
+        # @param payer [Solace::Keypair] The fee payer (the depositor or the sponsor).
+        # @param sign [Boolean] Whether to sign the transaction.
+        # @param execute [Boolean] Whether to send the transaction.
+        # @param composer_opts [Hash] Options for {#compose_reclaim}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def reclaim(payer:, sign: true, execute: true, **composer_opts)
+          composer = compose_reclaim(fee_payer: payer, **composer_opts)
+
+          yield composer if block_given?
+
+          tx = composer
+               .set_fee_payer(payer)
+               .compose_transaction
+
+          if sign
+            tx.sign(payer)
+
+            connection.send_transaction(tx.serialize) if execute
+          end
+
+          tx
+        end
+
+        # Prepares a reclaim transaction. Derives the EscrowDeposit PDA, the program
+        # vault, and the depositor's associated token account.
+        #
+        # @param mint [#to_s] Mint of the escrowed tokens.
+        # @param depositor [#to_s] Original depositor (receives the tokens).
+        # @param claim_authority [#to_s] Authority used to derive the escrow PDA.
+        # @param fee_payer [#to_s, Keypair] The fee payer (the depositor or the sponsor).
+        # @param token_program_id [String] Token program that owns the mint (default: legacy SPL Token).
+        # @return [Solace::TransactionComposer] A composer with the reclaim instruction.
+        def compose_reclaim(
+          mint:,
+          depositor:,
+          claim_authority:,
+          fee_payer:,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          escrow_deposit, = get_escrow_deposit_address(claim_authority:)
+          program_token_account, = get_vault_address(mint:)
+          depositor_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            depositor,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowReclaimComposer.new(
+            mint:,
+            depositor:,
+            depositor_token_account:,
+            escrow_deposit:,
+            program_token_account:,
+            fee_payer:,
+            claim_authority:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+      end
+    end
+  end
+end