> For the complete documentation index, see [llms.txt](https://docs.pokefi.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pokefi.xyz/technical-reference/solana-programs.md). # Solana Programs PokeFi's on-chain logic follows the proven Solana escrow pattern: program-derived addresses (PDAs) hold assets, and only the program can move them, gated by loan state. USDC transfers use `transfer_checked` to validate mint and decimals and prevent spoofed-token attacks. The programs are written in Rust using the [Anchor framework](https://anchor-lang.com). PokeFi keeps a small program surface. Two programs do the work: one represents vaulted cards, and one runs the loan lifecycle. {% hint style="info" %} The core programs are audited before mainnet beta. The deployed program addresses are published and verifiable on Solana Explorer. See [Security](/reference/security.md). {% endhint %} *** ## Title Token Program The Title Token program represents each vaulted card on-chain. A title token is an SPL token with rich Metaplex metadata (grader and certificate number, grade, set, population, photos, and vault reference). Key properties: * **Mint authority is the custody authority.** A title token can only be minted by the authorized custody service, after a physical card has been received and authenticated. This is what ties a token to a real, vaulted asset. * **Redeemable and burnable.** When the token holder redeems the physical card, and the card is not escrowed against a live loan, the token is burned as the card ships out. * **The unit of collateral.** The title token, not the wallet, is what moves into escrow when a card backs a loan. See [The Title Token](/technical-reference/title-tokens.md) for the token standard details. *** ## Loan Program The Loan program is the core. It manages the loan from request through settlement using PDA-controlled escrow. Each loan has a **loan account** (a PDA) that is the single source of truth for its terms and status, and an **escrow** (a PDA) that holds the title token for the loan's duration. ### Accounts **Loan account (PDA).** Stores the loan's authoritative state: | Field | Description | | ------------------ | ------------------------------------------------------- | | Borrower | The borrower's wallet | | Lender | The lender's wallet, unset until the loan is funded | | Collateral mint | The title token mint backing the loan | | Principal | Requested USDC amount | | Max APR | The borrower's ceiling on interest, in basis points | | APR | The agreed rate, set at funding, never above max APR | | Duration | The loan term in days | | Total repayment | Principal plus fixed interest, set at funding | | Start and maturity | Timestamps set at funding | | Status | `open`, `funded`, `repaid`, `defaulted`, or `cancelled` | **Escrow (PDA).** A program-controlled account that holds the title token. Only the program can move the token, and only according to loan state. No borrower or lender key can unilaterally seize it. ### Instructions #### `create_loan_request` Called by the borrower to publish a request. * Initializes the loan account with the requested principal, term, and max APR, in status `open` * Moves the card's title token into the loan escrow PDA * Emits a `requested` event The card is escrowed immediately, before any lender funds it, which guarantees the collateral is locked and ready. #### `fund_loan` Called by a lender to fund an open request. * Validates the loan is `open` and the lender is not the borrower * Validates the chosen APR is at or below the borrower's max APR * Atomically releases the lender's USDC to the borrower via `transfer_checked` * Records the agreed APR, computes and stores the total repayment and the maturity timestamp, and sets status to `funded` * Emits a `funded` event Once funded, the loan's economics are fixed. There are no margin calls or mid-loan liquidations. #### `repay` Called by the borrower to repay principal plus interest in USDC. * Validates the loan is `funded` * Accepts full or partial repayment via `transfer_checked` * When cumulative repayments cover the total repayment amount, releases the title token from escrow back to the borrower and sets status to `repaid` * Emits `repayment` events and, on full repayment, a `repaid` event #### `claim_default` Called after maturity passes without full repayment. * Validates the loan is `funded` and that maturity has elapsed * Transfers the title token from escrow to the lender (or into the liquidation flow) * Sets status to `defaulted` * Emits a `defaulted` event Default is deterministic: it is defined entirely by maturity elapsing without full repayment. #### `cancel_request` Called by the borrower to withdraw an unfunded request. * Validates the loan is still `open` * Releases the title token from escrow back to the borrower and sets status to `cancelled` * Emits a `cancelled` event A funded loan cannot be cancelled; it must settle by repayment or default. *** ## Why PDA-Gated Escrow All escrow accounts are PDAs: addresses derived deterministically from the program's public key and a set of seeds. PDAs have no private key, so no one can sign for them externally. Only the program can authorize actions on them. This design means: * The borrower cannot sell, move, or redeem the card while it backs a live loan. * The lender cannot touch the card unless the loan defaults at maturity. * PokeFi cannot move a title token or USDC outside the explicit instruction logic above. * The only ways assets move are the instructions described here. *** ## Events and the Transparency Ledger Every state transition emits an event: `requested`, `funded`, `repayment`, `repaid`, `defaulted`, `claimed`, `cancelled`. These are indexed off-chain into an append-only ledger that powers the public explorer, so anyone can audit the full history of any loan and its collateral. See [Architecture Overview](/technical-reference/architecture.md). *** ## Post-Beta: Pool Program A curated **Pool program** is planned for after beta. Lenders deposit USDC and receive a yield-bearing share token, and capital is allocated across many loans under managed risk parameters. It is not part of the peer-to-peer beta, where each lender funds individual loans directly. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pokefi.xyz/technical-reference/solana-programs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.