solace-zar-trustless-escrow 0.1.0

data/lib/solace/zar_trustless_escrow/programs/zar_trustless_escrow/mediated_escrow_deposit_operations.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    class ZarTrustlessEscrow < Base
+      # Three-party mediated escrow operations for
+      # {Solace::Programs::ZarTrustlessEscrow}: deposit, release, and reclaim
+      # against the MediatedEscrowDeposit 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 MediatedEscrowDepositOperations
+        # Fetches and deserializes the MediatedEscrowDeposit account at the given
+        # address. Derive the address first with {#get_mediated_escrow_deposit_address}.
+        #
+        # @param address [#to_s] Base58 address of the MediatedEscrowDeposit account.
+        # @return [Solace::ZarTrustlessEscrow::MediatedEscrowDeposit] The deserialized deposit.
+        # @raise [RuntimeError] If no account exists at the address.
+        def fetch_mediated_escrow_deposit(address:)
+          account = connection.get_account_info(address.to_s)
+          raise "MediatedEscrowDeposit account not found at #{address}" unless account
+
+          Solace::ZarTrustlessEscrow::MediatedEscrowDeposit.deserialize(
+            Solace::Utils::Codecs.base64_to_bytestream(account['data'][0])
+          )
+        end
+
+        # Returns whether a MediatedEscrowDeposit account exists at the given
+        # address. Derive the address first with {#get_mediated_escrow_deposit_address}.
+        #
+        # @param address [#to_s] Base58 address of the MediatedEscrowDeposit account.
+        # @return [Boolean] True if an account exists at the address.
+        def mediated_escrow_deposit_exists?(address:)
+          !connection.get_account_info(address.to_s).nil?
+        end
+
+        # Deposits funds into a three-party mediated escrow, signs, and
+        # (optionally) sends it. The depositor and fee payer sign.
+        #
+        # @param payer [Solace::Keypair] The fee payer (signs).
+        # @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_mediated_deposit}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def mediated_deposit(payer:, depositor:, sign: true, execute: true, **composer_opts)
+          composer = compose_mediated_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 mediated-deposit transaction. Derives the MediatedEscrowDeposit
+        # 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 id [#to_s] Unique id used to derive the escrow PDA.
+        # @param mediator [#to_s] Mediator who decides the outcome.
+        # @param beneficiary [#to_s] Beneficiary the mediator may release to.
+        # @param amount [Integer] u64 amount to deposit.
+        # @param fee_payer [#to_s, Keypair] The fee payer (writable signer).
+        # @param rent_collector [#to_s] (Optional) Rent collector on close (default: nil).
+        # @param expires_at [Integer] (Optional) Unix timestamp for depositor reclaim (default: nil).
+        # @param token_program_id [String] Token program that owns the mint (default: legacy SPL Token).
+        # @return [Solace::TransactionComposer] A composer with the mediated-deposit instruction.
+        def compose_mediated_deposit(
+          mint:,
+          depositor:,
+          id:,
+          mediator:,
+          beneficiary:,
+          amount:,
+          fee_payer:,
+          rent_collector: nil,
+          expires_at: nil,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          mediated_escrow_deposit, = get_mediated_escrow_deposit_address(id:)
+          program_token_account, = get_vault_address(mint:)
+          depositor_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            depositor,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowMediatedDepositComposer.new(
+            mint:,
+            depositor:,
+            depositor_token_account:,
+            mediated_escrow_deposit:,
+            program_token_account:,
+            fee_payer:,
+            amount:,
+            id:,
+            mediator:,
+            beneficiary:,
+            rent_collector:,
+            expires_at:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+
+        # Releases a mediated escrow on behalf of the mediator, signs, and
+        # (optionally) sends it. The mediator and fee payer sign.
+        #
+        # @param payer [Solace::Keypair] The fee payer (signs).
+        # @param mediator [Solace::Keypair] The mediator (signs).
+        # @param sign [Boolean] Whether to sign the transaction.
+        # @param execute [Boolean] Whether to send the transaction.
+        # @param composer_opts [Hash] Options for {#compose_mediated_release}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def mediated_release(payer:, mediator:, sign: true, execute: true, **composer_opts)
+          composer = compose_mediated_release(fee_payer: payer, mediator:, **composer_opts)
+
+          yield composer if block_given?
+
+          tx = composer
+               .set_fee_payer(payer)
+               .compose_transaction
+
+          if sign
+            tx.sign(payer, mediator)
+
+            connection.send_transaction(tx.serialize) if execute
+          end
+
+          tx
+        end
+
+        # Prepares a mediated-release transaction. Derives the MediatedEscrowDeposit
+        # PDA, the program vault, and the recipient's associated token account.
+        #
+        # @param mint [#to_s] Mint of the escrowed tokens.
+        # @param mediator [#to_s, Keypair] The mediator releasing the funds.
+        # @param recipient [#to_s] Depositor or beneficiary receiving the tokens.
+        # @param rent_collector [#to_s] Account that receives the closed-account rent.
+        # @param id [#to_s] Unique id used to derive the escrow PDA.
+        # @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 mediated-release instruction.
+        def compose_mediated_release(
+          mint:,
+          mediator:,
+          recipient:,
+          rent_collector:,
+          id:,
+          fee_payer:,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          mediated_escrow_deposit, = get_mediated_escrow_deposit_address(id:)
+          program_token_account, = get_vault_address(mint:)
+          recipient_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            recipient,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowMediatedReleaseComposer.new(
+            mint:,
+            mediator:,
+            recipient:,
+            recipient_token_account:,
+            mediated_escrow_deposit:,
+            program_token_account:,
+            rent_collector:,
+            fee_payer:,
+            id:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+
+        # Reclaims an expired mediated escrow as the depositor, signs, and
+        # (optionally) sends it. The depositor and fee payer sign.
+        #
+        # @param payer [Solace::Keypair] The fee payer (signs).
+        # @param depositor [Solace::Keypair] The depositor (signs, receives tokens and rent).
+        # @param sign [Boolean] Whether to sign the transaction.
+        # @param execute [Boolean] Whether to send the transaction.
+        # @param composer_opts [Hash] Options for {#compose_mediated_reclaim}.
+        # @return [Solace::Transaction] The created or sent transaction.
+        def mediated_reclaim(payer:, depositor:, sign: true, execute: true, **composer_opts)
+          composer = compose_mediated_reclaim(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 mediated-reclaim transaction. Derives the MediatedEscrowDeposit
+        # 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 (receives the tokens and rent).
+        # @param id [#to_s] Unique id used to derive the escrow PDA.
+        # @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 mediated-reclaim instruction.
+        def compose_mediated_reclaim(
+          mint:,
+          depositor:,
+          id:,
+          fee_payer:,
+          token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+        )
+          mediated_escrow_deposit, = get_mediated_escrow_deposit_address(id:)
+          program_token_account, = get_vault_address(mint:)
+          depositor_token_account, = Solace::Programs::AssociatedTokenAccount.get_address(
+            owner:            depositor,
+            mint:,
+            token_program_id:
+          )
+
+          ix = Composers::ZarTrustlessEscrowMediatedReclaimComposer.new(
+            mint:,
+            depositor:,
+            depositor_token_account:,
+            mediated_escrow_deposit:,
+            program_token_account:,
+            fee_payer:,
+            id:,
+            program_id:,
+            token_program_id:
+          )
+
+          TransactionComposer.new(connection:).add_instruction(ix)
+        end
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/programs/zar_trustless_escrow.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative 'zar_trustless_escrow/escrow_deposit_operations'
+require_relative 'zar_trustless_escrow/mediated_escrow_deposit_operations'
+
+module Solace
+  module Programs
+    # High-level client for the ZAR Trustless Escrow program.
+    #
+    # Provides PDA derivation (class methods), account fetching, the shared vault
+    # setup, and a compose/send pair per instruction. The instruction operations
+    # live in two mixins included below, split by escrow type:
+    #   - {EscrowDepositOperations} — two-party escrow (deposit/claim/reclaim).
+    #   - {MediatedEscrowDepositOperations} — three-party mediated escrow.
+    #
+    # @example
+    #   program = Solace::Programs::ZarTrustlessEscrow.new(connection:)
+    #   vault, = program.get_vault_address(mint: mint_address)
+    class ZarTrustlessEscrow < Base
+      include EscrowDepositOperations
+      include MediatedEscrowDepositOperations
+
+      class << self
+        # Derives the EscrowDeposit PDA for a claim authority, from the on-chain
+        # seeds ["escrow_deposit", claim_authority].
+        #
+        # @param claim_authority [#to_s] Base58 authority that can claim the deposit.
+        # @param program_id [#to_s] The escrow program id (default: mainnet PROGRAM_ID).
+        # @return [Array<String, Integer>] The escrow deposit address and bump seed.
+        def get_escrow_deposit_address(claim_authority:, program_id: Solace::ZarTrustlessEscrow::PROGRAM_ID)
+          Solace::Utils::PDA.find_program_address(
+            [Solace::ZarTrustlessEscrow::ESCROW_DEPOSIT_SEED, claim_authority.to_s],
+            program_id.to_s
+          )
+        end
+
+        # Derives the MediatedEscrowDeposit PDA for an id, from the on-chain seeds
+        # ["mediated_escrow_deposit", id].
+        #
+        # @param id [#to_s] Base58 unique id the escrow was created with.
+        # @param program_id [#to_s] The escrow program id (default: mainnet PROGRAM_ID).
+        # @return [Array<String, Integer>] The mediated escrow deposit address and bump seed.
+        def get_mediated_escrow_deposit_address(id:, program_id: Solace::ZarTrustlessEscrow::PROGRAM_ID)
+          Solace::Utils::PDA.find_program_address(
+            [Solace::ZarTrustlessEscrow::MEDIATED_ESCROW_DEPOSIT_SEED, id.to_s],
+            program_id.to_s
+          )
+        end
+
+        # Derives the per-mint program vault PDA, from the on-chain seeds
+        # ["vault", mint]. A single vault is shared across all deposits for a mint.
+        #
+        # @param mint [#to_s] Base58 mint the vault holds.
+        # @param program_id [#to_s] The escrow program id (default: mainnet PROGRAM_ID).
+        # @return [Array<String, Integer>] The vault address and bump seed.
+        def get_vault_address(mint:, program_id: Solace::ZarTrustlessEscrow::PROGRAM_ID)
+          Solace::Utils::PDA.find_program_address(
+            [Solace::ZarTrustlessEscrow::VAULT_SEED, mint.to_s],
+            program_id.to_s
+          )
+        end
+      end
+
+      # Initializes a new ZAR Trustless Escrow client.
+      #
+      # @param connection [Solace::Connection] The connection to the Solana cluster.
+      # @param program_id [String] The escrow program id (default: mainnet PROGRAM_ID).
+      def initialize(connection:, program_id: Solace::ZarTrustlessEscrow::PROGRAM_ID)
+        super
+      end
+
+      # Alias for the class method, defaulting to this client's program id.
+      #
+      # @param options [Hash] Options for the get_escrow_deposit_address class method.
+      # @return [Array<String, Integer>] The escrow deposit address and bump seed.
+      def get_escrow_deposit_address(**options)
+        self.class.get_escrow_deposit_address(program_id:, **options)
+      end
+
+      # Alias for the class method, defaulting to this client's program id.
+      #
+      # @param options [Hash] Options for the get_mediated_escrow_deposit_address class method.
+      # @return [Array<String, Integer>] The mediated escrow deposit address and bump seed.
+      def get_mediated_escrow_deposit_address(**options)
+        self.class.get_mediated_escrow_deposit_address(program_id:, **options)
+      end
+
+      # Alias for the class method, defaulting to this client's program id.
+      #
+      # @param options [Hash] Options for the get_vault_address class method.
+      # @return [Array<String, Integer>] The vault address and bump seed.
+      def get_vault_address(**options)
+        self.class.get_vault_address(program_id:, **options)
+      end
+
+      # Initializes the per-mint program vault, signs, and (optionally) sends it.
+      # The vault is shared across both escrow types, so this lives on the client
+      # itself rather than in an escrow-type mixin. The fee payer is the only signer.
+      #
+      # @param payer [Solace::Keypair] The fee payer (pays fees and rent, signs).
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to send the transaction.
+      # @param composer_opts [Hash] Options for {#compose_token_account_init}.
+      # @return [Solace::Transaction] The created or sent transaction.
+      def token_account_init(payer:, sign: true, execute: true, **composer_opts)
+        composer = compose_token_account_init(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 token-account-init transaction. Derives the program vault PDA.
+      #
+      # @param mint [#to_s] Mint the vault holds.
+      # @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 token-account-init instruction.
+      def compose_token_account_init(
+        mint:,
+        fee_payer:,
+        token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
+      )
+        program_token_account, = get_vault_address(mint:)
+
+        ix = Composers::ZarTrustlessEscrowTokenAccountInitComposer.new(
+          mint:,
+          program_token_account:,
+          fee_payer:,
+          program_id:,
+          token_program_id:
+        )
+
+        TransactionComposer.new(connection:).add_instruction(ix)
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/types/escrow_deposit.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    # Immutable value object representing the deserialized EscrowDeposit account —
+    # the two-party escrow created by the `deposit` instruction and consumed by
+    # `claim` / `re_claim`. Fetching from the chain is the Program layer's
+    # responsibility — see Solace::Programs::ZarTrustlessEscrow#get_escrow_deposit.
+    #
+    # On-chain layout (state/escrow_deposit.rs, matches the IDL):
+    #   discriminator(8), version(u8), mint(32), depositor(32), claim_pubkey(32),
+    #   amount(u64), sponsor(Option<Pubkey>).
+    #
+    # @example
+    #   deposit = program.get_escrow_deposit(claim_authority: claim_authority)
+    #   deposit.amount       # => 1_000_000
+    #   deposit.claim_pubkey # => "9xQ..."
+    EscrowDeposit = Data.define(
+      :version,      # Integer — escrow deposit version
+      :mint,         # String  — base58 mint of the escrowed tokens
+      :depositor,    # String  — base58 original depositor
+      :claim_pubkey, # String  — base58 authority that can claim the deposit
+      :amount,       # Integer — escrowed amount (u64)
+      :sponsor       # String, nil — base58 optional fee sponsor
+    ) do
+      # Deserializes an EscrowDeposit from a stream of Borsh-encoded account data.
+      #
+      # @param io [IO, StringIO] Stream positioned at the start of the account data.
+      # @return [EscrowDeposit] The deserialized, frozen value.
+      def self.deserialize(io)
+        io.read(8) # skip the 8-byte Anchor discriminator
+
+        new(
+          version:      Solace::Utils::Codecs.decode_u8(io),
+          mint:         Solace::Utils::Codecs.decode_pubkey(io),
+          depositor:    Solace::Utils::Codecs.decode_pubkey(io),
+          claim_pubkey: Solace::Utils::Codecs.decode_pubkey(io),
+          amount:       Solace::Utils::Codecs.decode_le_u64(io),
+          sponsor:      Solace::Utils::Codecs.decode_option_pubkey(io)
+        )
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/types/mediated_escrow_deposit.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    # Immutable value object representing the deserialized MediatedEscrowDeposit
+    # account — the three-party escrow created by `mediated_deposit` and consumed
+    # by `mediated_release` / `mediated_reclaim`. Fetching from the chain is the
+    # Program layer's responsibility — see
+    # Solace::Programs::ZarTrustlessEscrow#get_mediated_escrow_deposit.
+    #
+    # On-chain layout (state/mediated_escrow_deposit.rs, matches the IDL):
+    #   discriminator(8), version(u8), mint(32), depositor(32), mediator(32),
+    #   beneficiary(32), amount(u64), rent_collector(Option<Pubkey>),
+    #   expires_at(Option<i64>).
+    #
+    # @example
+    #   escrow = program.get_mediated_escrow_deposit(id: id)
+    #   escrow.mediator   # => "9xQ..."
+    #   escrow.expires_at # => 1_780_000_000 or nil
+    MediatedEscrowDeposit = Data.define(
+      :version,        # Integer — mediated escrow deposit version
+      :mint,           # String  — base58 mint of the escrowed tokens
+      :depositor,      # String  — base58 original depositor
+      :mediator,       # String  — base58 mediator who decides the outcome
+      :beneficiary,    # String  — base58 beneficiary the mediator may release to
+      :amount,         # Integer — escrowed amount (u64)
+      :rent_collector, # String, nil — base58 optional rent collector on close
+      :expires_at      # Integer, nil — unix timestamp after which depositor may reclaim
+    ) do
+      # Deserializes a MediatedEscrowDeposit from a stream of Borsh-encoded data.
+      #
+      # @param io [IO, StringIO] Stream positioned at the start of the account data.
+      # @return [MediatedEscrowDeposit] The deserialized, frozen value.
+      def self.deserialize(io)
+        io.read(8) # skip the 8-byte Anchor discriminator
+
+        new(
+          version:        Solace::Utils::Codecs.decode_u8(io),
+          mint:           Solace::Utils::Codecs.decode_pubkey(io),
+          depositor:      Solace::Utils::Codecs.decode_pubkey(io),
+          mediator:       Solace::Utils::Codecs.decode_pubkey(io),
+          beneficiary:    Solace::Utils::Codecs.decode_pubkey(io),
+          amount:         Solace::Utils::Codecs.decode_le_u64(io),
+          rent_collector: Solace::Utils::Codecs.decode_option_pubkey(io),
+          expires_at:     Solace::Utils::Codecs.decode_option_i64(io)
+        )
+      end
+    end
+  end
+end

data/lib/solace/zar_trustless_escrow/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Solace
+  module ZarTrustlessEscrow
+    VERSION = '0.1.0'
+  end
+end

data/lib/solace/zar_trustless_escrow.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'solace'
+require 'solace/zar_trustless_escrow/version'
+
+module Solace
+  # ZAR Trustless Escrow — a Solace extension for the on-chain escrow program.
+  #
+  # The program supports two escrow shapes:
+  #   - Two-party escrow: a depositor locks funds claimable by a claim authority,
+  #     reclaimable by the depositor (deposit / claim / re_claim).
+  #   - Three-party mediated escrow: a depositor locks funds that a mediator
+  #     releases to the depositor or a beneficiary, with an optional expiry that
+  #     lets the depositor reclaim (mediated_deposit / mediated_release /
+  #     mediated_reclaim).
+  module ZarTrustlessEscrow
+    # Base class for all errors raised by this gem.
+    class Error < StandardError; end
+  end
+end
+
+require 'solace/zar_trustless_escrow/constants'
+require 'solace/zar_trustless_escrow/codecs_extensions'
+require 'solace/zar_trustless_escrow/errors'
+
+def req_glob(path)
+  Dir[File.join(__dir__, path)].each { |f| require f }
+end
+
+# Load account types
+req_glob('zar_trustless_escrow/types/*.rb')
+
+# Load instructions and composers
+req_glob('zar_trustless_escrow/instructions/*.rb')
+req_glob('zar_trustless_escrow/composers/*.rb')
+
+# Load programs (the program client depends on the layers above)
+req_glob('zar_trustless_escrow/programs/*.rb')